@homie-rocks/studio 0.16.1 → 0.18.0

package/bin/homie-studio.mjs

@@ -17,7 +17,8 @@
  *   homie-studio game remix <source.json url> --id <new id>
  *   homie-studio games
  *   homie-studio build [<id>]
- *   homie-studio dev [--port 8787]        (--stop: stop exactly this studio's dev server, nothing else)
+ *   homie-studio dev [--port 8787] [--remote-ai]   (--stop: stop exactly this studio's dev server, nothing else;
+ *                                         AI guides think scripted here unless --remote-ai: real Workers AI, billed)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
  *   homie-studio chrome [install] [--fresh]  (which Chrome the checks use; on Linux, `install` fetches Chrome for Testing;
  *                                          --fresh fetches it even when the machine has a Chrome)
@@ -31,8 +32,14 @@
  *                                         migrations and deploys: the Worker and database are the Deploy button's.
  *   homie-studio publish
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
- *   homie-studio media put <file> [--as <key>]
- *   homie-studio media list
+ *   homie-studio media list               (every song and video page, where each file is served from, what moves to R2)
+ *   homie-studio media move [<file>...] [--dry-run] [--verify]
+ *                                         (with storage: the big files of published songs and videos into R2, each
+ *                                          read back and checked by SHA-256 before the site stops carrying it; the
+ *                                          address stays the same and the file stays in this folder. With no file:
+ *                                          everything over studio.json media.r2Over, 1 MiB unless set, or left out of
+ *                                          git. Every deploy does it too. --verify re-checks what R2 holds)
+ *   homie-studio media put <file> [--as <key>]   (a loose file at /media/<key>; for a song or video, media move)
  *   homie-studio status
  *   homie-studio upgrade [--apply] [--diff]
  *                                         (what this version's template adds to an existing studio: AGENTS.md
@@ -71,9 +78,14 @@
  *   homie-studio agents pass <game|any> --label "<Name>" [--server <id>] [--hands self|host] [--days 7]
  *                                         (an AI's way into a seat, always marked AI; the pass is shown once)
  *   homie-studio agents passes [<game>]   homie-studio agents revoke <pass id>
- *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key
+ *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key [--budget <n>]
  *                                         (a narrowing change, closing a server, removing a member and the first
- *                                          time AI guides may talk are ASKED for, like office kick)
+ *                                          time AI guides may talk are ASKED for, like office kick; --budget is
+ *                                          Workers AI neurons a day, or dollars a day for the owner's key)
+ *   homie-studio agents brain key [--remove]   (the owner's AI key, typed into a page on this computer only)
+ *   homie-studio agents sit <game> [--server <id>] [--pass hap_…] [--label Claude]
+ *                                         (an AI guide's seat from this terminal: then lines of `do <goal> {args}`,
+ *                                          `say <line> {args}`, `look`, `stand`)
  *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
@@ -130,14 +142,14 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, wr
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
-import { ciDeploy, deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { setupAttach } from '../lib/setup.mjs';
 import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { publish } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
-import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
+import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
@@ -145,7 +157,8 @@ import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { playersOwner, playersShow } from '../lib/players.mjs';
 import { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeRevoke, officeShow } from '../lib/office.mjs';
-import { agentsBrain, agentsPass, agentsPasses, agentsRevoke, serversClose, serversLevel, serversLines, serversList, serversMember, serversNew, serversSet } from '../lib/servers.mjs';
+import { agentsBrain, agentsBrainKey, agentsPass, agentsPasses, agentsRevoke, serversClose, serversLevel, serversLines, serversList, serversMember, serversNew, serversSet } from '../lib/servers.mjs';
+import { AgentSeat } from '../lib/agent-seat.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
@@ -157,7 +170,7 @@ import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -203,10 +216,31 @@ function print(result) {
     case 'media list':
       for (const kind of ['music', 'videos']) {
         lines.push(`${kind}/manifest.json: ${result[kind].pages.length} page(s)`);
-        for (const e of result[kind].pages) lines.push(`  /${kind}/${e.slug}/  ${e.title}  (${e.files.map((f) => `${f.role} from ${f.from}`).join(', ')})`);
+        for (const e of result[kind].pages) lines.push(`  /${kind}/${e.slug}/  ${e.title}  (${e.files.map((f) => `${f.role} from ${f.from === 'r2' ? 'R2' : f.from}`).join(', ')})`);
         for (const m of result[kind].skipped) lines.push(`  left out: ${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+        for (const m of result[kind].notes ?? []) lines.push(`  note: ${m.item} ${m.file}: ${m.why}`);
       }
+      if (result.moves.length) {
+        lines.push('', `Big media${result.r2 ? ' for R2' : ''} (over ${result.over === null ? '(off)' : lineOf(result.over)}, or left out of git):`);
+        for (const m of result.moves) lines.push(`  ${m.path}  ${m.bytes ? sizeOf(m.bytes) : ''}  ${m.state === 'too-big' ? m.why : m.reason ?? ''}`);
+      }
+      if (result.storage) lines.push('', result.storage);
+      if (result.r2) lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media once these are in. ${result.cost}`);
+      break;
+    case 'media move': {
+      const verb = result.dryRun ? 'Would move' : 'Moved';
+      if (result.ok === false && result.needs === 'storage') { lines.push(result.why); break; }
+      if (result.off) { lines.push(result.why); break; }
+      const todo = result.rows.filter((r) => r.state === 'move');
+      if (result.dryRun) lines.push(todo.length ? `${verb} ${todo.length} file(s) to R2 ${result.bucket}:` : 'Nothing to move: every big file is in R2 already, or none is published.', ...todo.map((r) => `  ${r.path}  ${sizeOf(r.bytes)}  (${r.reason})`));
+      else lines.push(result.moved.length ? `${verb} ${result.moved.length} file(s) to R2 ${result.bucket}, each read back and checked by SHA-256:` : 'Nothing moved.', ...result.moved.map((m) => `  ${m.path}  ${sizeOf(m.bytes)}  -> served at ${m.url} (the same address)`));
+      for (const f of result.failed ?? []) lines.push(`  NOT moved: ${f.path}: ${f.why}`);
+      for (const v of result.verified ?? []) lines.push(`  ${v.ok ? 'verified' : 'MISMATCH'}: ${v.path}${v.why ? `: ${v.why}` : ''}`);
+      for (const r of result.rows.filter((x) => x.state === 'too-big' || x.state === 'unlisted' || x.state === 'missing')) lines.push(`  ${r.state}: ${r.path}: ${r.why}`);
+      if (result.next) lines.push('', result.next);
+      lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media. ${result.cost}`, ...(result.warning ? [`Warning: ${result.warning}`] : []));
       break;
+    }
     case 'deploy':
       if (result.ci) {
         lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}`));
@@ -214,7 +248,8 @@ function print(result) {
       }
       lines.push(`Live: ${result.url}`, ...(result.workersDev && result.workersDev !== result.url ? [`  also at ${result.workersDev}`] : []),
         ...(result.local ? [`  (the workers.dev address names your Cloudflare account, so it is kept in ${result.local} on this computer, never in studio.json)`] : []),
-        ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
+        ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`),
+        ...(result.media?.moved ?? []).map((m) => `  moved to R2 (checked by SHA-256): ${m.path}, still at ${m.url}`), ...(result.media?.failed ?? []).map((m) => `  not moved to R2: ${m.path}: ${m.why}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
         result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).');
       break;
     case 'deploy plan':
@@ -302,8 +337,12 @@ function print(result) {
       break;
     case 'servers level':
     case 'agents revoke':
+    case 'agents brain key':
       lines.push(result.message);
       break;
+    case 'agents sit':
+      lines.push(`Left ${result.room}.`);
+      break;
     case 'agents pass':
       lines.push(`${result.pass.name} (pass ${result.pass.id}, ${result.pass.role}, hands ${result.pass.hands}${result.pass.server ? `, ${result.pass.server} only` : ''}):`, `  ${result.secret}`, result.use);
       break;
@@ -399,6 +438,12 @@ function print(result) {
         if (!flags.has('diff')) lines.push('  (--diff shows how each differs from the template: "-" this studio\'s lines, "+" the template\'s)');
       }
       if (result.uncommitted && !result.applied && result.changes.length) lines.push('', `Note: ${result.uncommitted} file(s) have uncommitted changes; commit them first so the upgrade is a change of its own.`);
+      if (result.media) {
+        lines.push('', `Big media (songs and videos over ${result.media.over === null ? '(off)' : lineOf(result.media.over)}, or left out of git):`);
+        for (const r of result.media.inR2) lines.push(`  = ${r.path}  in R2`);
+        for (const r of result.media.big) lines.push(`  > ${r.path}  ${r.bytes ? sizeOf(r.bytes) : ''}  ${r.state === 'too-big' ? r.why : r.reason ?? ''}`);
+        if (result.media.next) lines.push(`  ${result.media.next}`);
+      }
       if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
     }
@@ -536,15 +581,27 @@ async function main() {
     if (sub === 'pass') return agentsPass(root, positional[2], { url, label: flags.get('label'), server: flags.get('server'), hands: flags.get('hands'), role: flags.get('role'), days: flags.get('days') });
     if (sub === 'passes') return agentsPasses(root, positional[2], { url });
     if (sub === 'revoke') return agentsRevoke(root, positional[2], { url });
-    if (sub === 'brain') return agentsBrain(root, positional[2], positional[3], positional[4], { url });
-    return { ok: false, command: 'agents', why: `unknown: agents ${sub ?? ''} (pass, passes, revoke, brain)` };
+    if (sub === 'brain' && positional[2] === 'key') return agentsBrainKey(root, { remove: flags.has('remove'), log });
+    if (sub === 'brain') return agentsBrain(root, positional[2], positional[3], positional[4], { url, budget: flags.get('budget') });
+    if (sub === 'sit') return agentsSit(root, positional[2], { url, server: flags.get('server'), pass: flags.get('pass'), label: flags.get('label') });
+    return { ok: false, command: 'agents', why: `unknown: agents ${sub ?? ''} (pass, passes, revoke, brain, brain key, sit)` };
   }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
+  if (cmd === 'media' && sub === 'move') return mediaMove(root, { paths: positional.slice(2), dryRun: flags.has('dry-run') || flags.has('plan'), verify: flags.has('verify'), log });
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
     const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
-    const view = (kind) => { const r = resolveMedia(root, kind, { r2 }); return { pages: r.entries.map((e) => ({ slug: e.slug, title: e.title, kind: e.kind, files: e.files.map(({ abs, rel, ...f }) => f) })), skipped: r.skipped }; };
-    return { ok: true, command: 'media list', r2, site: siteUrl(root, studio), music: view('music'), videos: view('videos') };
+    // What a deploy would serve (deploy: true), so "from r2" means the site no longer carries the file.
+    const view = (kind) => { const r = resolveMedia(root, kind, { r2, deploy: true }); return { pages: r.entries.map((e) => ({ slug: e.slug, title: e.title, kind: e.kind, files: e.files.map(({ abs, rel, ...f }) => f) })), skipped: r.skipped, notes: r.notes }; };
+    const over = r2OverOf(studio);
+    const plan = mediaPlan(root, { over });
+    const moves = plan.filter((x) => x.state === 'move' || x.state === 'too-big').map(({ abs, held, ...x }) => x);
+    const inR2 = plan.filter((x) => x.state === 'r2' || x.state === 'move').reduce((n, x) => n + (x.bytes ?? 0), 0);
+    return {
+      ok: true, command: 'media list', r2, site: siteUrl(root, studio), music: view('music'), videos: view('videos'), over, moves, inR2,
+      storage: r2 ? (moves.length ? 'the next deploy (or media move now) puts these in R2, checked by SHA-256; their addresses stay the same' : 'every big file is in R2') : (moves.length ? 'no storage: these stay on the site (files up to 25 MiB each), and a deploy from another computer or Workers Builds leaves out any file git does not keep. homie-studio storage add (a payment method on the Cloudflare account, asked first) fixes both' : null),
+      cost: R2_COST,
+    };
   }
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
@@ -714,7 +771,9 @@ async function dev(root) {
     m.on('close', done);
   });
   log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
-  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: workerDir(root), env, stdio: 'inherit' });
+  const ai = devConfig(root, flags.has('remote-ai'));
+  if (ai.note) log(ai.note);
+  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port, ...ai.args], { cwd: workerDir(root), env, stdio: 'inherit' });
   mkdirSync(dirname(devFile(root)), { recursive: true });
   writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
   log(`Stop it with: npx --no-install homie-studio dev --stop   (this studio's dev server only)`);
@@ -725,6 +784,54 @@ async function dev(root) {
   return { ok: true, command: 'dev', stopped: true };
 }
 
+/**
+ * AI guides under `dev` (0.17.0): they think scripted, for free, unless --remote-ai (real Workers AI on the signed-in
+ * account, billed like the live site). A config whose AI binding is not what was asked for runs from a copy in
+ * .wrangler/ (absolute paths, the same local state), so wrangler.jsonc itself is never changed by dev.
+ */
+function devConfig(root, remoteAi) {
+  const file = join(workerDir(root), 'wrangler.jsonc');
+  let json;
+  try { json = JSON.parse(readFileSync(file, 'utf8').replace(/^\s*\/\/.*$/gm, '')); } catch { return { args: [] }; }
+  if (Boolean(json.ai) === remoteAi) return { args: [], note: remoteAi ? 'AI guides think with Workers AI (remote, billed to the signed-in account).' : null };
+  const base = workerDir(root);
+  const abs = (p) => (p && !p.startsWith('/') ? join(base, p) : p);
+  delete json.$schema;
+  json.main = abs(json.main);
+  if (json.assets?.directory) json.assets.directory = abs(json.assets.directory);
+  json.d1_databases = (json.d1_databases ?? []).map((d) => ({ ...d, ...(d.migrations_dir ? { migrations_dir: abs(d.migrations_dir) } : {}) }));
+  if (remoteAi) json.ai = { binding: 'AI', remote: true }; else delete json.ai;
+  const copy = join(base, '.wrangler', 'homie-dev.wrangler.json');
+  mkdirSync(dirname(copy), { recursive: true });
+  writeFileSync(copy, `${JSON.stringify(json, null, 2)}\n`);
+  return { args: ['--config', copy, '--persist-to', join(base, '.wrangler', 'state')], note: remoteAi ? 'AI guides think with Workers AI (remote, billed to the signed-in account).' : 'AI guides think scripted here (no Workers AI under dev; --remote-ai for the real one).' };
+}
+
+/** `agents sit`: an AI guide's seat from this terminal, for a demo or a test of a vocabulary. Lines on stdin act. */
+async function agentsSit(root, game, { url, server, pass, label }) {
+  const site = url ?? siteUrl(root);
+  const seat = new AgentSeat({ site, game, server: server ?? null, pass: pass ?? null, label: label ?? 'Claude', root });
+  const r = await seat.sit();
+  if (!r.ok) return { ok: false, command: 'agents sit', why: r.why };
+  log(`Seated as ${r.name} in ${r.room} (seat ${r.seat}). Type: look | do <goal> {"arg":…} | say <line> {"arg":…} with a goal | stand`);
+  log(JSON.stringify({ view: r.view, asks: r.asks, choices: r.choices }, null, 1));
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin });
+  let goal = null;
+  for await (const line of rl) {
+    const [word, id, ...rest] = line.trim().split(/\s+/);
+    let args = {};
+    try { args = rest.length ? JSON.parse(rest.join(' ')) : {}; } catch { log('arguments are JSON, e.g. {"place":"camp"}'); continue; }
+    if (word === 'look') log(JSON.stringify(seat.look(), null, 1));
+    else if (word === 'do') { goal = { goal: id, args }; const d = await seat.do(goal); log(d.ok ? `done: ${JSON.stringify(d.sent)}` : `refused: ${d.why}`); }
+    else if (word === 'say') { const d = await seat.do({ ...(goal ?? { goal: Object.keys(seat.vocab.goals)[0], args: {} }), say: id, sayArgs: args }); log(d.ok ? `said: ${d.text}` : `refused: ${d.why}`); }
+    else if (word === 'stand') break;
+  }
+  rl.close();
+  await seat.stand();
+  return { ok: true, command: 'agents sit', stood: true, room: r.room };
+}
+
 /** A big file into the studio's R2, and its key on the music/ or videos/ manifest entry that names it. */
 function mediaPut(root, file, as) {
   if (!file || !existsSync(file) || !statSync(file).isFile()) return { ok: false, command: 'media put', why: 'usage: homie-studio media put <file> [--as <key>]' };

package/lib/agent-seat.mjs

@@ -0,0 +1,185 @@
+/**
+ * AN AI IN A SEAT, FROM THIS COMPUTER (@homie-rocks/studio 0.17.0, NETPLAY.md section 18): the local MCP's agent_sit,
+ * agent_look, agent_do and agent_stand, and `homie-studio agents sit`. The person's own AI (Claude in the desktop app,
+ * Claude Code, any MCP client) takes a guide's seat with hands `host`: the host's game moves the body every frame at the
+ * party's dial, while this holds the socket between the AI's turns (about 30 s a decision), keeps the latest view the
+ * host showed it and the asks made of it, and sends its goals and lines: only the game's own vocabulary (agents.json),
+ * which the relay checks again. It always plays as "<label> · AI".
+ *
+ * The pass: one the owner gave (`hap_…`), or, from a studio folder, a one-day guide pass minted with the owner's office
+ * key and revoked when the AI stands. The secret stays in this process; it is never printed or returned.
+ */
+import { parseDecision, renderLine, vocabularyOf } from '../worker/brain.mjs';
+import { withKey } from './office.mjs';
+
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const SERVER = /^[a-z0-9][a-z0-9-]{1,19}$/;
+const PASS = /^hap_[a-f0-9]{10}_[A-Za-z0-9_-]{40}$/;
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export class AgentSeat {
+  /**
+   * @param {object} o
+   * @param {string} o.site     the studio's site (https://…, or http://127.0.0.1:8787 for `homie-studio dev`)
+   * @param {string} o.game
+   * @param {string} [o.server] a server id (else the pass's, else public)
+   * @param {string} [o.pass]   an agent pass (hap_…); else one is minted from `root` with the office key
+   * @param {string} [o.root]   the studio folder (for a pass of its own)
+   */
+  constructor({ site, game, server = null, pass = null, label = 'Claude', root = null, WebSocketImpl = globalThis.WebSocket, fetchImpl = globalThis.fetch }) {
+    this.site = String(site ?? '').replace(/\/+$/, '');
+    this.game = game;
+    this.server = server;
+    this.pass = pass;
+    this.label = label;
+    this.root = root;
+    this.WS = WebSocketImpl;
+    this.fetch = fetchImpl;
+    this.minted = null;
+    this.ws = null;
+    this.seat = null;
+    this.name = null;
+    this.room = null;
+    this.policy = null;
+    this.view = null;
+    this.viewAt = 0;
+    this.asks = [];
+    this.party = [];
+    this.lastDo = null;
+    this.doAt = 0;
+    this.sayAt = 0;
+    this.closed = null;
+    this.errors = [];
+    this.vocab = null;
+    this.ping = null;
+  }
+
+  async sit() {
+    if (!GAME.test(String(this.game ?? ''))) return { ok: false, why: 'game is the game\'s id' };
+    if (this.server !== null && !SERVER.test(String(this.server)) && this.server !== 'public') return { ok: false, why: 'server is a server id' };
+    if (!this.site) return { ok: false, why: 'no site: run the studio here (preview_run / homie-studio dev) or deploy it, or give url' };
+    if (!this.WS) return { ok: false, why: 'this Node has no WebSocket (Node 22 or newer)' };
+    // The vocabulary: what this AI may choose and say, from the built game.
+    try {
+      const res = await this.fetch(`${this.site}/games/${this.game}/agents.json`, { signal: AbortSignal.timeout(10_000) });
+      if (res.ok) this.vocab = vocabularyOf(await res.json()).vocab;
+    } catch { this.vocab = null; }
+    if (!this.vocab) return { ok: false, why: `${this.game} has no agents.json (the guides' vocabulary): an AI with no game client has nothing to choose from` };
+    if (!this.pass) {
+      if (!this.root) return { ok: false, why: 'give pass (an agent pass, hap_…), or run this from the studio folder' };
+      const r = await withKey(this.root, this.site, (call) => call('/_studio/api/agents/pass', { action: 'create', game: this.game, label: this.label, role: 'guide', hands: 'host', days: 1, server: this.server && this.server !== 'public' ? this.server : null }));
+      if (!r.ok || !PASS.test(String(r.secret ?? ''))) return { ok: false, why: `could not make a pass: ${r.message ?? r.why ?? 'the office did not answer'}` };
+      this.pass = r.secret;
+      this.minted = r.pass?.id ?? null;
+    }
+    let sat;
+    try {
+      const res = await this.fetch(`${this.site}/${this.game}/api/agent`, {
+        method: 'POST', headers: { authorization: `Bearer ${this.pass}`, 'content-type': 'application/json', 'user-agent': 'homie-studio-agent' },
+        body: JSON.stringify(this.server ? { server: this.server } : {}), signal: AbortSignal.timeout(15_000),
+      });
+      sat = await res.json().catch(() => ({ ok: false, message: `the site answered ${res.status}` }));
+    } catch (error) { sat = { ok: false, message: error.message }; }
+    if (!sat.ok) { await this.revoke(); return { ok: false, why: sat.message ?? sat.error ?? 'the seat was refused', error: sat.error ?? null }; }
+    if (sat.hands !== 'host') { await this.revoke(); return { ok: false, why: 'this pass is for an AI that runs the game itself (hands self); agent_sit needs hands host' }; }
+    this.room = sat.room;
+    this.server = sat.server;
+    const ws = new this.WS(sat.ws);
+    this.ws = ws;
+    const welcome = await new Promise((done) => {
+      const timer = setTimeout(() => done({ t: 'timeout' }), 12_000);
+      ws.onopen = () => ws.send(JSON.stringify({ ...sat.hello, device: 'desk' }));
+      ws.onmessage = (e) => {
+        let m; try { m = JSON.parse(String(e.data)); } catch { return; }
+        if (m.t === 'welcome' || (m.t === 'error' && !this.seat)) { clearTimeout(timer); done(m); }
+        this.onFrame(m);
+      };
+      ws.onclose = (e) => { this.closed = this.closed ?? (e?.reason || 'closed'); clearTimeout(timer); done({ t: 'closed' }); };
+      ws.onerror = () => {};
+    });
+    if (welcome.t !== 'welcome') { this.close(); await this.revoke(); return { ok: false, why: welcome.message ?? `no seat (${welcome.code ?? welcome.t})`, error: welcome.code ?? welcome.t }; }
+    this.ping = setInterval(() => { try { ws.send(JSON.stringify({ t: 'ping', c: Date.now() })); } catch { /* closed */ } }, 2000);
+    // The host shows a guide the game every 2 s: wait for the first look (up to 6 s).
+    for (let i = 0; i < 30 && !this.view && !this.closed; i += 1) await wait(200);
+    return { ok: true, seat: this.seat, name: this.name, room: this.room, server: this.server, ...this.look() };
+  }
+
+  onFrame(m) {
+    switch (m.t) {
+      case 'welcome': this.seat = m.seat; this.name = m.name; this.policy = m.policy ?? null; return;
+      case 'policy': this.policy = m.policy ?? this.policy; return;
+      case 'error': this.errors = [...this.errors, { code: m.code, message: m.message, at: Date.now() }].slice(-6); if (['agents-alone', 'agents-off', 'kicked', 'room-closed', 'agent-yield'].includes(m.code)) this.closed = m.code; return;
+      case 'ev': {
+        const k = String(m.k ?? '');
+        const d = m.d && typeof m.d === 'object' ? m.d : {};
+        if (k === 'agent:view') { this.view = d; this.viewAt = Date.now(); return; }
+        const ask = /^ask:([a-z][a-z0-9_]{0,31})$/.exec(k)?.[1];
+        if (ask && d.seat === this.seat) { this.asks = [...this.asks, { k: ask, args: d.args ?? {}, from: m.from, at: Date.now() }].slice(-6); return; }
+        const line = /^say:([a-z][a-z0-9_]{0,31})$/.exec(k)?.[1];
+        if (line && m.from !== this.seat) this.party = [...this.party, { seat: m.from, line, args: d.args ?? {}, at: Date.now() }].slice(-6);
+        return;
+      }
+      default: return;
+    }
+  }
+
+  /** What the AI needs to decide: the view, the asks made of it, the party's lines, its choices (ids only). */
+  look() {
+    const now = Date.now();
+    const v = this.vocab;
+    const describe = (entries) => Object.fromEntries(Object.entries(entries ?? {}).map(([id, e]) => [id, { ...(e.about ? { about: e.about } : { text: e.text }), args: Object.fromEntries(Object.entries(e.args ?? {}).map(([k, s]) => [k, s.kind === 'player' ? 'player (a seat number)' : s.kind === 'list' ? s.values : `view.${s.key}`])) }]));
+    return {
+      seat: this.seat, name: this.name, room: this.room, closed: this.closed,
+      talking: Boolean(this.policy && ['workers-ai', 'owner-key'].includes(this.policy.brain) && this.policy.speech !== 'off'),
+      view: this.view, viewAgeMs: this.viewAt ? now - this.viewAt : null,
+      asks: this.asks.filter((a) => now - a.at < 60_000).map((a) => ({ ask: a.k, args: a.args, seat: a.from, text: v ? renderLine(v, a.k, a.args, { kind: 'asks', nameOf: (s) => `seat ${s}` }) : null, secondsAgo: Math.round((now - a.at) / 1000) })),
+      party: this.party.filter((p) => now - p.at < 60_000).map((p) => ({ seat: p.seat, line: p.line, args: p.args })),
+      lastDo: this.lastDo,
+      choices: v ? { goals: describe(v.goals), lines: describe(v.lines) } : null,
+      errors: this.errors.slice(-3),
+    };
+  }
+
+  /** One decision: a goal (and at most one line) of the vocabulary, checked here first and again by the relay. */
+  async do({ goal, args = {}, say = null, sayArgs = {} } = {}) {
+    if (!this.ws || this.closed) return { ok: false, why: this.closed ? `the seat closed (${this.closed}); agent_sit again` : 'not seated: agent_sit first' };
+    const p = parseDecision({ goal, args, say: say || null, sayArgs: say ? sayArgs : {} }, this.vocab, { view: this.view });
+    if (!p.ok) return { ok: false, why: `${p.why}. Choose a goal and line from look().choices, with values the view offers.` };
+    const now = Date.now();
+    if (now - this.doAt < 3000) await wait(3000 - (now - this.doAt));
+    if (!this.talking() && p.decision.say) return { ok: false, why: 'this server\'s AI may not talk (its owner has not turned AI talk on); choose a goal with say null' };
+    if (p.decision.say && Date.now() - this.sayAt < 8000) return { ok: false, why: 'a guide says at most one line every 8 seconds; send the goal alone, or wait' };
+    this.ws.send(JSON.stringify({ t: 'ev', k: 'agent:do', d: { goal: p.decision.goal, args: p.decision.args } }));
+    this.doAt = Date.now();
+    if (p.decision.say) { this.ws.send(JSON.stringify({ t: 'ev', k: `say:${p.decision.say}`, d: { args: p.decision.sayArgs } })); this.sayAt = Date.now(); }
+    this.lastDo = { goal: p.decision.goal, args: p.decision.args, say: p.decision.say, at: new Date().toISOString() };
+    this.asks = [];
+    await wait(300);
+    const refused = this.errors.find((e) => e.at >= this.doAt - 50);
+    return refused ? { ok: false, why: `the room said ${refused.code}: ${refused.message}` } : { ok: true, sent: this.lastDo, text: p.decision.say ? renderLine(this.vocab, p.decision.say, p.decision.sayArgs, { me: this.name, nameOf: (s) => `seat ${s}`, view: this.view }) : null };
+  }
+
+  talking() { return Boolean(this.policy && ['workers-ai', 'owner-key'].includes(this.policy.brain) && this.policy.speech !== 'off'); }
+
+  close() {
+    if (this.ping) clearInterval(this.ping);
+    this.ping = null;
+    if (this.ws) { try { this.ws.send(JSON.stringify({ t: 'bye' })); } catch { /* closed */ } try { this.ws.close(1000, 'bye'); } catch { /* closed */ } }
+    this.ws = null;
+    this.closed = this.closed ?? 'stood';
+  }
+
+  /** A pass this seat minted ends with it. */
+  async revoke() {
+    if (!this.minted || !this.root) return;
+    const id = this.minted;
+    this.minted = null;
+    await withKey(this.root, this.site, (call) => call('/_studio/api/agents/pass', { action: 'revoke', id })).catch(() => {});
+  }
+
+  async stand() {
+    this.close();
+    await this.revoke();
+    return { ok: true, stood: true, room: this.room };
+  }
+}

package/lib/build.mjs

@@ -5,6 +5,8 @@
  *   site/dist/games/<id>/index.html        the game's page (the Worker adds HOMIE_NET)
  *   site/dist/games/<id>/assets/main.js    its bundle (esbuild; @homie-rocks/studio/netplay inlined)
  *   site/dist/games/<id>/...               everything in games/<id>/public/
+ *   site/dist/games/<id>/agents.json       the AI guides' vocabulary (games/<id>/agents.json, checked; NETPLAY.md
+ *                                          section 18): the only goals and lines an AI in its rooms has
  *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site } from studio.json,
  *                                          game.json files, the music/ and videos/ manifests (media/MEDIA.md),
  *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
@@ -13,7 +15,11 @@
  *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
  *                                          the studio's owner (worker/stats-page.mjs), never listed or indexed
  *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
- *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
+ *   site/dist/music/..., site/dist/videos/...   media files the site serves itself. A file the studio's R2 has (media
+ *                                          move: the same bytes, by SHA-256) is left out of a deploy's build and
+ *                                          served from R2 at the same address; a local build still copies it when it
+ *                                          fits, for `dev` (whose R2 is empty). Workers Builds (WORKERS_CI=1) builds
+ *                                          as a deploy.
  *
  * game.json "build" picks how a game becomes files (a ported game keeps its own shape):
  *   (absent) / { "mode": "bundle" }   src/main.ts (or "entry") bundled by esbuild — new games and ES-module ports
@@ -35,6 +41,7 @@ import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { licenseOf, remixRow } from '../worker/license.mjs';
 import { SERVER_LIMITS, serverOf } from '../worker/servers.mjs';
+import { vocabularyOf } from '../worker/brain.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
@@ -152,6 +159,22 @@ export function netplayRevOf(out) {
   return rev;
 }
 
+/**
+ * games/<id>/agents.json, checked (worker/brain.mjs vocabularyOf: argument types, text over 120 characters, a goal
+ * against a player, an ask naming a goal or line that is not there) and served beside the game, where the room's Table
+ * reads it. A game with none has guides that play but never talk. Returns whether it has one.
+ */
+export function vocabFor(g, out) {
+  const file = join(g.dir, 'agents.json');
+  if (!existsSync(file)) { rmSync(join(out, 'agents.json'), { force: true }); return false; }
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { throw new Error(`games/${g.id}/agents.json is not JSON: ${error.message}`); }
+  const v = vocabularyOf(raw);
+  if (!v.ok) throw new Error(`games/${g.id}/agents.json: ${v.problems.slice(0, 6).join('; ')}`);
+  writeFileSync(join(out, 'agents.json'), `${JSON.stringify(raw)}\n`);
+  return true;
+}
+
 /** game.json "servers": the seeds a game ships with (worker/servers.mjs; a D1 row of the same id wins). */
 function serverSeeds(g, log) {
   if (!Array.isArray(g.servers)) return [];
@@ -182,7 +205,7 @@ export function seatsFor(g, net = netplayOf(g)) {
   return { min: Math.min(max, minNamed ?? 1), max, asked };
 }
 
-export async function build(root, { only = null, log = () => {} } = {}) {
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1' } = {}) {
   const require = createRequire(join(root, 'package.json'));
   let esbuild;
   try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
@@ -236,6 +259,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     }
     if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
     if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+    // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
+    vocabFor(g, out);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id, { studio: studio.name ?? null, game: g.name ?? g.id, license: g.license }))}\n`);
     const main = join(out, 'assets', 'main.js');
@@ -249,9 +274,9 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   // Songs and videos (music/ and videos/ manifests): rebuilt with every full build; a one-game build keeps them.
   const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
   let media = null;
-  if (!only) media = buildMedia(root, dist, { r2, log });
+  if (!only) media = buildMedia(root, dist, { r2, deploy, log });
   else {
-    try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [] }; } catch { media = { songs: [], videos: [], skipped: [] }; }
+    try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [], notes: [] }; } catch { media = { songs: [], videos: [], skipped: [], notes: [] }; }
   }
   // The site around the games (site/SITE.md): the look, each game's landing, posts, and what site/ overrides.
   const theme = readTheme(root, { log });
@@ -277,6 +302,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       // predates servers), and game.json "agents": { "vote": "game" | false } (the game draws its own vote card, or none).
       ...(seeds.length ? { servers: seeds } : {}),
       netplayRev: netplayRevOf(join(dist, 'games', g.id)),
+      // 0.17.0: the game has a vocabulary for its AI guides (agents.json), so they can talk once the owner says so.
+      ...(existsSync(join(dist, 'games', g.id, 'agents.json')) ? { vocab: true } : {}),
       ...(g.agents && typeof g.agents === 'object' && (g.agents.vote === 'game' || g.agents.vote === false) ? { agents: { vote: g.agents.vote } } : {}),
       // Its source licence (worker/license.mjs), and, for a remix, what it is a remix of (shown on its landing).
       license: licenseOf(g.license),
@@ -322,7 +349,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
-    songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
+    songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped, mediaNotes: media.notes ?? [],
     posts: posts.map((p) => p.slug), postsSkipped, codexes, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
     landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };