@homie-rocks/studio 0.16.1 → 0.17.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)
@@ -71,9 +72,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]
@@ -145,7 +151,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 +164,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'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -302,8 +309,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;
@@ -536,8 +547,10 @@ 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 === 'list') {
@@ -714,7 +727,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 +740,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)
@@ -35,6 +37,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 +155,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 [];
@@ -236,6 +255,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');
@@ -277,6 +298,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),

package/lib/cloudflare.mjs

@@ -197,6 +197,11 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
+  // Workers AI (0.17.0): bound only when a server's AI guides think with it.
+  if (needsWorkersAi(root, w, cf.d1)) {
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true }));
+    step('Workers AI bound (AI): a server\'s AI guides think with it, within the day\'s budget (free allocation: 10,000 neurons a day)');
+  }
 
   const started = Date.now();
   const dep = w(['deploy', ...repoVar(root)]);
@@ -239,6 +244,21 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   };
 }
 
+/**
+ * Whether any server of this studio's games thinks with Workers AI (a D1 row with brain 'workers-ai', or a game.json
+ * seed): deploy binds AI only then (DESIGN section 6). A database without the servers table yet says no.
+ */
+export function needsWorkersAi(root, w, db) {
+  try {
+    const cat = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8'));
+    if ((cat.games ?? []).some((g) => (g.servers ?? []).some((s) => s.brain === 'workers-ai'))) return true;
+  } catch { /* not built */ }
+  const r = w(['d1', 'execute', db, '--remote', '--json', '--command', "SELECT COUNT(*) AS n FROM servers WHERE brain = 'workers-ai' AND state = 'open'"]);
+  if (r.code !== 0) return false;
+  const parsed = parseJson(r.stdout ?? r.out);
+  return Number((Array.isArray(parsed) ? parsed[0] : parsed)?.results?.[0]?.n) > 0;
+}
+
 /*
  * THE STUDIO'S REPOSITORY, FOR ITS WORKER (lib/repo.mjs). The Claude app's hand-off opens Claude Code on the studio's
  * own GitHub repository, and only the studio knows which it is: the deploy hands it to the Worker as a variable
@@ -299,6 +319,14 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
   if (migrate.code !== 0 && !first) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   if (!first) step('D1 migrations applied');
+  // Workers AI (0.17.0): bound only when a server's AI guides think with it. The checkout is thrown away after.
+  if (!first && needsWorkersAi(root, w, names.binding)) {
+    try {
+      const json = JSON.parse(readFileSync(configPath(root), 'utf8').replace(/^\s*\/\/.*$/gm, ''));
+      if (!json.ai) { json.ai = { binding: 'AI' }; writeFileSync(configPath(root), `${JSON.stringify(json, null, 2)}\n`); }
+      step('Workers AI bound (AI) for the AI guides');
+    } catch { step('could not add the Workers AI binding to wrangler.jsonc: the guides answer from the game\'s script'); }
+  }
   const started = Date.now();
   const dep = w(['deploy', ...repoVar(root)]);
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);

package/lib/mcp-tools.mjs

@@ -11,6 +11,10 @@
  *
  * Every tool works in ONE studio folder: one the person named, else the one in use, else the only one there is. The
  * file tools never leave it (lib/files.mjs).
+ *
+ * AN AI IN A SEAT (0.17.0, lib/agent-seat.mjs): agent_sit, agent_look, agent_do and agent_stand put the person's own
+ * AI in a game's guide seat, marked " · AI". This process holds the socket between turns; the game's own bot code
+ * moves the body while the AI thinks; the AI chooses only the game's own goals and lines (agents.json).
  */
 import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync } from 'node:fs';
@@ -26,6 +30,7 @@ import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
 import { GAME_ID, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
+import { AgentSeat } from './agent-seat.mjs';
 
 export const UI = Object.freeze({
   setup: 'ui://homie-studio/setup',
@@ -960,6 +965,57 @@ export function toolDefs(ctx, avail = {}) {
         return r.job.code === 0 ? ok(text, { kind: 'run', args, result: r.result }) : fail(`homie-studio ${args.join(' ')}: ${whyOf(r.job)}`, { kind: 'run', args, result: r.result });
       },
     },
+    {
+      name: 'agent_sit', title: 'Sit in a game as an AI guide',
+      description: 'Take a guide\'s seat in a live room of one of the studio\'s games as an AI ("Claude · AI": always marked AI, never on a humans-only server, only in a room with people in it). The game\'s own bot code moves the body every frame; you choose its goal and, when the server lets its AI talk, one of the game\'s own lines (agents.json; never free text). Returns your seat, what you see (view), the asks players made of you and your choices. Then agent_look and agent_do every 20 to 40 seconds, and agent_stand when done. Uses the site running here (preview_run) or the live site; with no pass, makes a one-day guide pass with the owner\'s office key and revokes it when you stand.',
+      inputSchema: { type: 'object', properties: { game: str('The game\'s id'), server: str('Optional: a server id (default: the pass\'s, else Quick play)'), pass: str('Optional: an agent pass (hap_…) the owner gave; never shown back'), label: str('Optional: the name you play under (default "Claude"; " · AI" is added)'), url: str('Optional: the site (default: this computer\'s preview, else the live site)'), ...STUDIO_ARG }, required: ['game'] },
+      annotations: { title: 'Sit in a game as an AI guide', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        if (ctx.seat && !ctx.seat.closed) await ctx.seat.stand();
+        const site = a.url ? String(a.url) : devOf(root)?.url ?? siteUrl(root);
+        if (!site) return fail('the studio is not running here and has no live site: preview_run first, or studio_deploy');
+        const seat = new AgentSeat({ site, game: String(a.game ?? ''), server: a.server ?? null, pass: a.pass ?? null, label: a.label ? String(a.label).slice(0, 16) : 'Claude', root });
+        const r = await seat.sit();
+        if (!r.ok) return fail(`No seat: ${r.why}`, { kind: 'agent', ok: false, error: r.error ?? null });
+        ctx.seat = seat;
+        return ok(`Seated as ${r.name} in ${r.room} (seat ${r.seat}). ${r.talking ? 'This server lets its AI talk: lines from look.choices.lines, at most one every 8 s.' : 'This server\'s AI does not talk: choose goals only (say null).'} Look again with agent_look; act with agent_do { goal, args, say?, sayArgs? }.\n${JSON.stringify({ view: r.view, asks: r.asks, choices: r.choices }, null, 1).slice(0, 6000)}`, { kind: 'agent', ...r });
+      },
+    },
+    {
+      name: 'agent_look', title: 'Look as the AI guide',
+      description: 'What your AI guide sees now: the view the game showed you (game state, seats, never names), the asks players made of you (answer these first), the party\'s lines, your last goal, and your choices.',
+      inputSchema: { type: 'object', properties: {} },
+      annotations: { title: 'Look as the AI guide', ...RO },
+      run: async () => {
+        if (!ctx.seat) return fail('not seated: agent_sit first');
+        const l = ctx.seat.look();
+        return ok(`${l.closed ? `The seat closed (${l.closed}); agent_sit again.\n` : ''}${JSON.stringify(l, null, 1).slice(0, 8000)}`, { kind: 'agent', ...l });
+      },
+    },
+    {
+      name: 'agent_do', title: 'Act as the AI guide',
+      description: 'Choose your guide\'s goal (one of look.choices.goals, with argument values the view offers; a player argument is a seat number) and, if the server lets its AI talk, at most one line (look.choices.lines; never free text). The game\'s bot code carries it out at frame rate until you choose again. At most one goal every 3 s and one line every 8 s.',
+      inputSchema: { type: 'object', properties: { goal: str('A goal id'), args: { type: 'object', description: 'The goal\'s arguments' }, say: str('Optional: a line id'), sayArgs: { type: 'object', description: 'The line\'s arguments' } }, required: ['goal'] },
+      annotations: { title: 'Act as the AI guide', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      run: async (a) => {
+        if (!ctx.seat) return fail('not seated: agent_sit first');
+        const r = await ctx.seat.do({ goal: a.goal, args: a.args ?? {}, say: a.say ?? null, sayArgs: a.sayArgs ?? {} });
+        return r.ok ? ok(`Done: ${r.sent.goal} ${JSON.stringify(r.sent.args)}${r.text ? `, saying "${r.text}"` : ''}.`, { kind: 'agent', ...r }) : fail(r.why, { kind: 'agent', ok: false });
+      },
+    },
+    {
+      name: 'agent_stand', title: 'Leave the seat',
+      description: 'Your AI guide leaves the room (its seat becomes a guide the game\'s own script plays); a pass made for this sitting is revoked.',
+      inputSchema: { type: 'object', properties: {} },
+      annotations: { title: 'Leave the seat', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      run: async () => {
+        if (!ctx.seat) return ok('Not seated.');
+        const r = await ctx.seat.stand();
+        ctx.seat = null;
+        return ok(`Left ${r.room}.`, { kind: 'agent', ...r });
+      },
+    },
     {
       name: 'studio_job', title: 'A job, so far',
       description: 'Where a job a tool handed back is (an npm install, a check, a deploy, a render): running or done, its last lines and its result. Waits up to 30 s for it to finish.',

package/lib/office.mjs

@@ -59,7 +59,7 @@ function signinTo(root, url, to) {
 
 export const askedFor = (root, url, r, command) => {
   if (!r.ok) return { ok: false, command, why: r.message ?? r.why ?? `the studio said ${r.error ?? r.status}` };
-  if (r.needs !== 'owner' || !r.ask) return { ok: true, command, done: true, result: r, message: r.what ? `Done: ${r.what}` : 'Done.' };
+  if (r.needs !== 'owner' || !r.ask) return { ok: true, command, done: true, result: r, message: `${r.what ? `Done: ${r.what}` : 'Done.'}${r.note ? ` ${r.note}` : ''}` };
   const link = signinTo(root, url, `/_studio/confirm/${r.ask.id}`);
   return {
     ok: true, command, asked: true, ask: r.ask, what: r.ask.what,

package/lib/scaffold.mjs

@@ -55,7 +55,7 @@ export function slugify(name) {
  * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
  * the binding names and keep it linked.
  */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root' }) {
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false }) {
   const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
     : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
@@ -75,6 +75,9 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
     d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: at.migrations }],
     ...(r2 ? { r2_buckets: [{ binding: 'MEDIA', bucket_name: r2 }] } : {}),
+    // Workers AI, only when a server's AI guides think with it (agents_brain workers-ai; deploy adds it, 0.17.0).
+    // Never in Previews: they do not inherit it, so a Preview's guides answer from the game's script.
+    ...(ai ? { ai: { binding: 'AI' } } : {}),
     vars: { STUDIO_NAME: name },
     observability: { enabled: true },
     previews: { vars: { STUDIO_NAME: name, HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
@@ -288,6 +291,16 @@ studio's pinned copy, never a registry lookup of the bare name.
 - **Agent passes:** \`npx --no-install homie-studio agents pass <id> --label Claude [--server <server>]\` gives an
   AI its way into a seat (shown once; \`agents revoke <pass>\` ends it). It sits with \`POST /<id>/api/agent\`
   (Bearer pass), only in a room with people in it, and never on a humans-only server.
+- **AI guides that talk (0.17.0):** a beginner server's guides get a brain. A game's own words for them are
+  \`games/<id>/agents.json\` (its vocabulary: goals, lines, the asks a player taps; the build checks it), and
+  \`useAgents\` from \`@homie-rocks/studio/agents\` is the host's side: a view per guide, the scripted floor, goals
+  for the hands, lines drawn from the vocabulary (\`NETPLAY.md\` section 18; Ember Vale is the reference). The
+  brain is the server's: \`agents brain <id> <server> workers-ai\` (the studio's own Workers AI; \`npm run deploy\`
+  binds it; at most \`--budget\` neurons a day, 8,000 by default) or \`owner-key\` (the owner's own key, set with
+  \`agents brain key\` on this computer, never in a chat; a dollar cap a day). The first time AI talk is turned on
+  it only ASKS. The AI never types: it picks a goal and a line id; the relay drops anything else. With no AI, over
+  budget, or between decisions, the game's \`decide\` plays. \`agent_sit\` (the local MCP) puts the owner's own
+  Claude in a guide's seat.
 
 ## Continuing a build from the Claude app