@homie-rocks/studio 0.16.1 → 0.18.0

package/worker/index.mjs

@@ -37,7 +37,10 @@
  *                              knocks for a Homie box, so it stops knocking (a studio site is not a box)
  *   /.well-known/homie-studio.json   what the homie.rocks directory reads
  *   /games/<id>/source.json    a public game's source for remixing, with its credit and licence (worker/license.mjs)
- *   /media/<key>               the studio's large media, from R2 (once `storage add` bound it), with byte ranges
+ *   /media/<key>               a loose file in the studio's R2 (`media put`), with byte ranges
+ *   /music/<slug>/<file>, /videos/<slug>/<file>   a song's or video's files: from the site's own files, or, for a
+ *                              file `media move` put in the studio's R2 (the catalogue names its key), from R2 at the
+ *                              same address, with byte ranges, HEAD, ETag and the site's own cache headers
  *   /api/stats                 the studio's numbers, for its owner only (a read key, or the owner's page session)
  *   /_studio/stats             the owner's private stats page (one-time sign-in link from `homie-studio stats link`)
  *   /_studio/office            the owner's back office: live rooms and who is in them, kick, mute, announce, close,
@@ -62,9 +65,12 @@
  * after `homie-studio storage add` (R2 needs a payment method on the account),
  * MEDIA. Everything else runs on Cloudflare's free Workers plan.
  *
- * The relay is the netplay contract's own room.mjs (NETPLAY.md v1 rev 6), run
+ * The relay is the netplay contract's own room.mjs (NETPLAY.md v1 rev 7), run
  * unchanged inside the Table, so a game that plays in `homie-studio dev`
- * plays the same way here.
+ * plays the same way here. A beginner server whose AI may talk also gets the
+ * Table's own house guides (worker/agents.mjs HouseAgents), whose brains run
+ * on the Table's alarm: Workers AI through the optional AI binding (deploy adds
+ * it when a server uses it), or the owner's own key (secret HOMIE_BRAIN_KEY).
  */
 import { NetRoom, WATCH_POLICIES } from './room.mjs';
 import { ROOM_ID, badRoomPage, frameAncestors, noWatchPage, playPage, watchPage } from './pages.mjs';
@@ -72,7 +78,8 @@ import {
   PUBLIC_SERVER, SERVER_ID, homeOf, memberCounts, memberOf, noteMember, policyOf, pooledRoom, roomCode, roomServer, serverAccess, serverPassOf, serverView, serversOf,
   setMembership,
 } from './servers.mjs';
-import { agentFacts, aiName, decodeFacts, encodeFacts, passById, passRefusal, sitRoute } from './agents.mjs';
+import { BRAIN_BUDGET, HouseAgents, agentFacts, aiName, decodeFacts, encodeFacts, passById, passRefusal, sitRoute } from './agents.mjs';
+import { talks } from './brain.mjs';
 import { doorPage, serverPage, serversPage } from './site.mjs';
 import { qrSvg } from './qr.mjs';
 import { SEAT_MAX, perAddress, seatsOf } from './seats.mjs';
@@ -274,21 +281,50 @@ async function assetWithRange(request, env, url) {
   return new Response(body.subarray(r.start, r.end + 1), { status: 206, headers });
 }
 
-/** A file from the studio's R2 bucket, with byte ranges. */
-async function mediaObject(request, env, key) {
+/** Does an If-None-Match header name this ETag (or `*`)? Weak and strong forms compare alike for a GET. */
+function etagMatches(header, etag) {
+  if (!header || !etag) return false;
+  const bare = (t) => String(t).trim().replace(/^W\//, '');
+  return header.split(',').some((t) => t.trim() === '*' || bare(t) === bare(etag));
+}
+
+/**
+ * A file from the studio's R2 bucket, with byte ranges (206), HEAD, and If-None-Match (304).
+ * `cache`: the Cache-Control it is served with. /media/<key> keeps its hour; a song or video served at its own
+ * address (media move) gets exactly what the site's static files get, `public, max-age=0, must-revalidate` with an
+ * ETag, so moving a file to R2 changes nothing a browser or a phone sees. `type`: the catalogue's type, for an
+ * object stored without one.
+ */
+async function mediaObject(request, env, key, { cache = 'public, max-age=3600', type = null } = {}) {
   const range = request.headers.get('range');
+  const inm = request.headers.get('if-none-match');
+  const headOnly = request.method === 'HEAD';
   let head = null;
-  if (range) head = await env.MEDIA.head(key);
-  if (range && !head) return new Response('not found', { status: 404 });
-  const r = head ? parseRange(range, head.size) : null;
-  if (r?.unsatisfiable) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${head.size}` } });
+  if (range || inm || headOnly) {
+    head = await env.MEDIA.head(key);
+    if (!head) return new Response('not found', { status: 404 });
+  }
+  const base = (obj) => {
+    const headers = new Headers();
+    obj.writeHttpMetadata?.(headers);
+    if (!headers.get('content-type') && type) headers.set('content-type', type);
+    if (obj.httpEtag) headers.set('etag', obj.httpEtag);
+    if (obj.uploaded) headers.set('last-modified', new Date(obj.uploaded).toUTCString());
+    headers.set('cache-control', cache);
+    headers.set('accept-ranges', 'bytes');
+    return headers;
+  };
+  if (head && inm && etagMatches(inm, head.httpEtag)) return new Response(null, { status: 304, headers: base(head) });
+  const r = head && range ? parseRange(range, head.size) : null;
+  if (r?.unsatisfiable) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${head.size}`, 'accept-ranges': 'bytes' } });
+  if (headOnly) {
+    const headers = base(head);
+    headers.set('content-length', String(head.size));
+    return new Response(null, { headers });
+  }
   const obj = await env.MEDIA.get(key, r ? { range: { offset: r.start, length: r.end - r.start + 1 } } : undefined);
   if (!obj) return new Response('not found', { status: 404 });
-  const headers = new Headers();
-  obj.writeHttpMetadata(headers);
-  headers.set('etag', obj.httpEtag);
-  headers.set('cache-control', 'public, max-age=3600');
-  headers.set('accept-ranges', 'bytes');
+  const headers = base(obj);
   if (r) {
     headers.set('content-range', `bytes ${r.start}-${r.end}/${head.size}`);
     headers.set('content-length', String(r.end - r.start + 1));
@@ -298,6 +334,30 @@ async function mediaObject(request, env, key) {
   return new Response(obj.body, { headers });
 }
 
+/** The same Cache-Control the site's static files are served with (Workers static assets' default). */
+const ASSET_CACHE = 'public, max-age=0, must-revalidate';
+
+/**
+ * A song's or video's file that `media move` put in R2, by the address it always had (/music/<slug>/x.mp3,
+ * /videos/<slug>/x.mp4): the catalogue names its key (`r2`). Only files the catalogue lists as public are served this
+ * way, never any other key of the bucket.
+ */
+async function heldInR2(env, getCat, path) {
+  if (!env.MEDIA) return null;
+  const cat = await getCat();
+  let want;
+  try { want = decodeURIComponent(path); } catch { return null; }
+  for (const e of [...(cat.songs ?? []), ...(cat.videos ?? [])]) {
+    for (const f of e.files ?? []) {
+      if (typeof f.r2 !== 'string' || !f.r2 || f.r2.startsWith('players/') || typeof f.url !== 'string') continue;
+      let at;
+      try { at = decodeURIComponent(f.url); } catch { continue; }
+      if (at === want) return f;
+    }
+  }
+  return null;
+}
+
 /**
  * A catalogue media row as the directory reads it (absolute addresses). A song's cover (a video's poster) is its
  * own, else the manifest's default, else the landing still of the game it was made for (site.mjs mediaArt).
@@ -613,7 +673,12 @@ async function route(request, env, ctx) {
     }
     if (parts.some((p) => p === '..')) return notFoundPage('Nothing here.', cat);
     const file = await assetWithRange(request, env, url);
-    if (file.status === 404) return notFoundPage('Nothing here.', cat);
+    if (file.status === 404) {
+      // Not in the site's files: a song's or video's file that lives in the studio's R2 (media move), same address.
+      const held = await heldInR2(env, getCat, path);
+      if (held) return mediaObject(request, env, held.r2, { cache: ASSET_CACHE, type: held.type ?? null });
+      return notFoundPage('Nothing here.', cat);
+    }
     return file;
   }
   if (path === '/' || path === '/index.html') {
@@ -924,7 +989,12 @@ async function weekOf(env, game) {
 /** Everything else is a file of the built site (site/public, the games' files), with byte ranges for media. */
 async function fallback(request, env, url, getCat) {
   const asset = MEDIA_FILE.test(url.pathname) && request.headers.get('range') ? await assetWithRange(request, env, url) : await env.ASSETS.fetch(request);
-  if (asset.status === 404) return notFoundPage('Nothing here.', await getCat());
+  if (asset.status === 404) {
+    // A manifest file outside music/ and videos/ that media move put in R2 keeps its address too.
+    const held = (request.method === 'GET' || request.method === 'HEAD') ? await heldInR2(env, getCat, url.pathname) : null;
+    if (held) return mediaObject(request, env, held.r2, { cache: ASSET_CACHE, type: held.type ?? null });
+    return notFoundPage('Nothing here.', await getCat());
+  }
   return asset;
 }
 
@@ -950,6 +1020,15 @@ export class Table {
     /** The owner's holds, banner and closed door (they outlive an empty room), and the controls already used. */
     this.officeSaved = null;
     this.seen = new Map();
+    /** Revision 7: the game's vocabulary (agents.json, read once from the build), and the room's house guides. */
+    this.vocabRead = null;
+    this.house = null;
+    /** The AI brains' day (worker/agents.mjs): what the studio allows a day and has used, and what is not counted yet. */
+    this.brainDay = null;
+    this.brainCap = { neurons: BRAIN_BUDGET.neurons, micros: BRAIN_BUDGET.usd * 1e6 };
+    this.brainUsed = { neurons: 0, micros: 0 };
+    this.brainPending = { calls: {}, neurons: 0, micros: 0 };
+    this.brainReadAt = 0;
     ctx.blockConcurrencyWhile(async () => {
       this.saved = (await ctx.storage.get('net')) ?? null;
       this.recorded = (await ctx.storage.get('recorded')) ?? 0;
@@ -973,9 +1052,99 @@ export class Table {
     });
     if (this.saved) this.room.restore(this.saved);
     if (this.officeSaved) this.room.restoreOffice(this.officeSaved);
+    this.vocabRead = this.readVocab(game).catch(() => false);
     return this.room;
   }
 
+  /** The game's agents.json from the build (the only words an AI in this room may say), once. */
+  async readVocab(game) {
+    if (!this.env.ASSETS || !/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(game ?? ''))) return false;
+    const res = await this.env.ASSETS.fetch(new Request(`https://assets.local/games/${game}/agents.json`));
+    if (!res.ok) return false;
+    const ok = this.room.setVocabulary(await res.json());
+    if (ok) this.syncHouse();
+    return ok;
+  }
+
+  /**
+   * The room's house guides (worker/agents.mjs): seated while the server's AI may talk, the game has a vocabulary and a
+   * person is playing; stood up otherwise. Called on the 1 s beat and whenever the policy changes. No brain runs here:
+   * decisions run on the alarm.
+   */
+  syncHouse() {
+    const room = this.room;
+    if (!room) return;
+    if (!this.house) {
+      if (!talks(room.policy) || !room.vocab || !(room.policy.guides > 0)) return;
+      this.house = new HouseAgents({
+        room, env: this.env,
+        setAlarm: (at) => { this.ctx.storage.setAlarm(at).catch(() => {}); },
+        budget: { left: (kind) => this.brainCap[kind] - this.brainUsed[kind], spend: (c) => this.brainSpend(c) },
+        log: (line) => { try { console.log(JSON.stringify(line)); } catch { /* no console */ } },
+      });
+      this.ctx.waitUntil(this.readBrainDay().catch(() => {}));
+    }
+    this.house.sync();
+  }
+
+  /** What the studio allows its AI brains a day (meta `brain_budget`) and has used today (stats_daily), all games. */
+  async readBrainDay() {
+    const db = this.env.DB;
+    if (!db) return;
+    const day = today();
+    try {
+      const b = JSON.parse((await db.prepare("SELECT value FROM meta WHERE key = 'brain_budget'").first())?.value ?? 'null');
+      if (b && Number.isFinite(Number(b.neurons))) this.brainCap.neurons = Math.max(0, Number(b.neurons));
+      if (b && Number.isFinite(Number(b.usd))) this.brainCap.micros = Math.max(0, Number(b.usd)) * 1e6;
+    } catch { /* the defaults */ }
+    try {
+      const { results } = await db.prepare("SELECT metric, SUM(n) AS n FROM stats_daily WHERE day = ?1 AND metric IN ('brain-neurons', 'brain-microdollars') GROUP BY metric").bind(day).all();
+      const used = { neurons: 0, micros: 0 };
+      for (const r of results ?? []) used[r.metric === 'brain-neurons' ? 'neurons' : 'micros'] = Number(r.n) || 0;
+      // What this room spent and has not written yet is added on top.
+      this.brainUsed = { neurons: used.neurons + this.brainPending.neurons, micros: used.micros + this.brainPending.micros };
+    } catch { /* before migration 0002: nothing used */ }
+    this.brainDay = day;
+    this.brainReadAt = Date.now();
+  }
+
+  brainSpend(c) {
+    if (this.brainDay && this.brainDay !== today()) { this.brainUsed = { neurons: 0, micros: 0 }; this.brainDay = today(); }
+    this.brainUsed.neurons += c.neurons ?? 0;
+    this.brainUsed.micros += c.micros ?? 0;
+    this.brainPending.neurons += c.neurons ?? 0;
+    this.brainPending.micros += c.micros ?? 0;
+    const k = c.provider ?? 'script';
+    this.brainPending.calls[k] = (this.brainPending.calls[k] ?? 0) + 1;
+  }
+
+  /**
+   * The day's brain counters into D1 (stats_daily: brain-calls by provider, brain-neurons, brain-microdollars), and the
+   * day's budget and usage read again (an owner's new budget, other rooms' use): at most once a minute, on the alarm.
+   */
+  async flushBrain(force = false) {
+    const p = this.brainPending;
+    if (!this.env.DB || (!force && Date.now() - this.brainReadAt < 60_000)) return;
+    if (!Object.keys(p.calls).length && p.neurons < 1 && p.micros < 1) { await this.readBrainDay(); return; }
+    const neurons = Math.floor(p.neurons);
+    const micros = Math.floor(p.micros);
+    const rows = [
+      ...Object.entries(p.calls).map(([source, n]) => counter(this.env, { metric: 'brain-calls', subject: this.game ?? '', source, n })),
+      neurons ? counter(this.env, { metric: 'brain-neurons', subject: this.game ?? '', n: neurons }) : null,
+      micros ? counter(this.env, { metric: 'brain-microdollars', subject: this.game ?? '', n: micros }) : null,
+    ].filter(Boolean);
+    this.brainPending = { calls: {}, neurons: p.neurons - neurons, micros: p.micros - micros };
+    if (rows.length) await this.env.DB.batch(rows).catch(() => {});
+    await this.readBrainDay();
+  }
+
+  /** The alarm: the house guides' brains decide (worker/agents.mjs), then the day's usage is written. */
+  async alarm() {
+    // A brain that throws never takes the room with it: the alarm is not retried, the guides answer from the floor.
+    try { if (this.house) await this.house.onAlarm(); } catch (error) { try { console.log(JSON.stringify({ ev: 'brain-alarm-failed', room: this.code, error: String(error?.stack ?? error).slice(0, 400) })); } catch { /* no console */ } }
+    try { await this.flushBrain(); } catch { /* counted next time */ }
+  }
+
   async fetch(request) {
     const url = new URL(request.url);
     const game = url.searchParams.get('game');
@@ -984,12 +1153,14 @@ export class Table {
     const room = this.roomFor(game, code, max);
     // The back office (worker/office.mjs), from the studio's Worker only: the room as its owner sees it, and the
     // owner's signed controls, which this room verifies before it applies one (NETPLAY.md section 15).
-    if (url.pathname === '/__facts') return json(room.officeFacts());
+    if (url.pathname === '/__facts') return json({ ...room.officeFacts(), ...(this.house ? { brains: this.house.facts() } : {}) });
     if (url.pathname === '/__office') {
       const ctl = await request.json().catch(() => null);
       const why = await verifyControl(this.env, ctl, { game: this.game, room: this.code }, this.seen);
       if (why) return json({ ok: false, error: 'refused', why }, 403);
       const res = room.control(ctl.op, ctl.args && typeof ctl.args === 'object' ? ctl.args : {});
+      // AI talk turned off (a policy) or a guide kicked: the house guides follow at once.
+      if (this.house) this.house.sync();
       await this.ctx.storage.put('office', room.officeSaved()).catch(() => {});
       if (ctl.op === 'close' && res.ok) this.tellLobby({ closed: ctl.args?.reopen ? 0 : res.until });
       this.report();
@@ -1000,6 +1171,7 @@ export class Table {
     // The room's policy (section 17), composed by the Worker for every socket: a newer one than the room's applies.
     const pol = decodeFacts(url.searchParams.get('pol'));
     if (pol) room.setPolicy(pol);
+    if (this.house) this.house.sync();
     const agent = decodeFacts(url.searchParams.get('ag'));
     const [client, server] = Object.values(new WebSocketPair());
     server.accept();
@@ -1072,9 +1244,9 @@ export class Table {
       // A launch change the room applied by itself (after its round): its stored state says so too.
       if (room.officeDirty) { room.officeDirty = false; this.ctx.storage.put('office', room.officeSaved()).catch(() => {}); }
       n += 1;
-      if (n % 4 === 0) { room.tellWatchers(); this.report(); this.recordRound(); }
+      if (n % 4 === 0) { room.tellWatchers(); this.report(); this.recordRound(); this.syncHouse(); }
       if (room.seats.size === 0 && room.clients.size === 0) this.openCounted = false;
-      if (room.clients.size === 0 && room.watchers.size === 0) { clearInterval(this.timer); this.timer = null; this.report(); }
+      if (room.clients.size === 0 && room.watchers.size === 0) { clearInterval(this.timer); this.timer = null; this.report(); if (this.house) { this.ctx.waitUntil(this.flushBrain(true).catch(() => {})); this.house = null; } }
     }, 250);
   }
 
@@ -1109,7 +1281,9 @@ export class Table {
     const counts = room.facts().counts;
     // Players are people (an agent never counts as one, DESIGN D9); agents and AI bodies are reported apart.
     const players = counts.players;
-    const agents = counts.agents ?? 0;
+    // AIs with a pass (a house guide makes way for one, so the Lobby counts only these when it seats an AI).
+    let agents = 0;
+    for (const c of room.clients.values()) if (c.helloed && c.agent && c.seat !== null && !c.conn?.loopback) agents += 1;
     const ai = counts.ai ?? 0;
     // People for the stats: seated sockets that are not house QA (players is what the Lobby matches strangers by).
     let people = 0;

package/worker/office-page.mjs

@@ -320,6 +320,14 @@ export const OFFICE_SCRIPT = String.raw`(function () {
         if ((brain.value === 'workers-ai' || brain.value === 'owner-key') && !S.data.agentsTalk && !confirm('Let AI guides talk? They speak only the lines the game\'s agents.json gives them, at most one every 8 seconds, never about a person, and any player can quiet them.')) return;
         act('/_studio/api/agents/brain', { game: g.id, server: sv.id, mode: brain.value });
       })));
+      // What today's brains used of the day's budget (the whole studio), and what is missing for the one chosen.
+      var bd = S.data.brain;
+      if (bd && (sv.brain === 'workers-ai' || sv.brain === 'owner-key')) {
+        var used = sv.brain === 'workers-ai'
+          ? 'Workers AI: ' + Math.round(bd.used.neurons).toLocaleString('en-US') + ' / ' + Math.round(bd.budget.neurons).toLocaleString('en-US') + ' neurons today' + (bd.ai ? '' : ' · not bound yet: deploy once more')
+          : 'Your key: $' + bd.used.usd.toFixed(2) + ' / $' + bd.budget.usd.toFixed(2) + ' today' + (bd.key ? '' : ' · no key yet: homie-studio agents brain key');
+        add(body, add(el('div', 'line'), el('span', 'faint', used + (g.vocab ? '' : ' · this game has no agents.json: its guides have no words'))));
+      }
     }
     if (sv.id !== 'public') {
       var mbox = el('div', 'line'); mbox.appendChild(el('span', 'dim', 'Members:'));
@@ -635,6 +643,11 @@ export const OFFICE_SCRIPT = String.raw`(function () {
       var bots = (r.slots || []).filter(function (s) { return s.bot; });
       if (bots.length) people.appendChild(el('div', 'held', 'AI and bots: ' + bots.map(function (s) { return s.name + (s.agent ? ' (AI ' + (s.agent.role === 'guide' ? 'guide' : 'seat') + ')' : ''); }).join(', ')));
       if (r.vote && r.vote.open) people.appendChild(el('div', 'held', 'The party is voting on the AI\'s level: ' + r.vote.voters + ' of ' + r.vote.of_total + ' voted.'));
+      // The house guides' brains: which one runs (and why not), and their last few decisions (ids only, never words).
+      if (r.brains) {
+        var last = (r.brains.decisions || []).filter(function (x) { return x.goal || x.say; }).slice(-4).reverse().map(function (x) { return 'seat ' + (x.seat + 1) + ': ' + (x.goal ? x.goal + (x.args && Object.keys(x.args).length ? ' ' + Object.keys(x.args).map(function (k) { return x.args[k]; }).join(' ') : '') : 'no change') + (x.say ? ', said ' + x.say : '') + ' (' + x.provider + (x.ms ? ', ' + (x.ms / 1000).toFixed(1) + ' s' : '') + ', ' + dur(now - x.at) + ' ago)'; });
+        people.appendChild(el('div', 'held', 'Guides\' brain: ' + (r.brains.brain || 'script') + (r.brains.why ? ' · ' + r.brains.why : '') + ' · ' + r.brains.calls + ' calls' + (last.length ? ' · ' + last.join('; ') : '')));
+      }
       (r.bans || []).forEach(function (b) { people.appendChild(el('div', 'held', 'Kicked: ' + (b.name || 'someone') + ', may come back in ' + dur(b.until - now) + (b.address ? ' (their network too)' : ''))); });
       box.appendChild(people);
     }

package/worker/office.mjs

@@ -45,8 +45,9 @@
  */
 import { SEAT_MAX, seatsOf } from './seats.mjs';
 import { PUBLIC_SERVER, SERVER_LIMITS, checkServer, levelName, narrows, policyOf, roomServer, rowFor, serverView, serversOf, serverPassCookie, writeServer } from './servers.mjs';
-import { aiName, fillSpot, passById, passCreate, passList, passRevoke } from './agents.mjs';
-import { OWNER_COOKIE, cookieValues, ownerAllowed, ownerSession } from './stats.mjs';
+import { BRAIN_BUDGET, aiName, fillSpot, passById, passCreate, passList, passRevoke } from './agents.mjs';
+import { DEFAULT_MODEL, OWNER_MODEL } from './brain.mjs';
+import { OWNER_COOKIE, cookieValues, ownerAllowed, ownerSession, today } from './stats.mjs';
 import { esc, layout, notFoundPage } from './site.mjs';
 import { confirmPage, lockedPage, officePage } from './office-page.mjs';
 import { licenseOf } from './license.mjs';
@@ -455,9 +456,35 @@ async function roomRow(env, meta, room, max) {
     host: f.host ?? null, announce: f.announce ?? null,
     slots: slots.slice(0, 64).map((s) => ({ slot: s.slot, seat: s.seat ?? null, name: oneLine(s.name, 40), bot: Boolean(s.bot), ...(s.agent ? { agent: { role: s.agent.role ?? 'party', seat: s.agent.seat ?? null } } : {}) })),
     clients, bans: office.bans ?? [], mutes: office.mutes ?? [],
+    // The house guides' brains (0.17.0): which brain, why not when it is not, and the last decisions (seats and ids).
+    ...(f.brains && typeof f.brains === 'object' ? { brains: {
+      brain: String(f.brains.brain ?? ''), why: f.brains.why ? oneLine(f.brains.why, 120) : null, calls: Number(f.brains.calls) || 0,
+      guides: (Array.isArray(f.brains.guides) ? f.brains.guides : []).slice(0, 8).map((g) => ({ name: oneLine(g.name, 40), seat: g.seat ?? null, provider: g.provider ?? null })),
+      decisions: (Array.isArray(f.brains.decisions) ? f.brains.decisions : []).slice(-50),
+    } } : {}),
   };
 }
 
+/** The AI brains' day for the whole studio: the budget (meta brain_budget) and what today used (stats_daily). */
+export async function brainDay(env) {
+  const budget = { neurons: BRAIN_BUDGET.neurons, usd: BRAIN_BUDGET.usd };
+  const used = { neurons: 0, usd: 0, calls: 0 };
+  try {
+    const b = JSON.parse((await env.DB.prepare("SELECT value FROM meta WHERE key = 'brain_budget'").first())?.value ?? 'null');
+    if (b && Number.isFinite(Number(b.neurons))) budget.neurons = Number(b.neurons);
+    if (b && Number.isFinite(Number(b.usd))) budget.usd = Number(b.usd);
+  } catch { /* the defaults */ }
+  try {
+    const { results } = await env.DB.prepare("SELECT metric, SUM(n) AS n FROM stats_daily WHERE day = ?1 AND metric IN ('brain-calls', 'brain-neurons', 'brain-microdollars') GROUP BY metric").bind(today()).all();
+    for (const r of results ?? []) {
+      if (r.metric === 'brain-calls') used.calls = Number(r.n) || 0;
+      if (r.metric === 'brain-neurons') used.neurons = Number(r.n) || 0;
+      if (r.metric === 'brain-microdollars') used.usd = Math.round(Number(r.n) || 0) / 1e6;
+    }
+  } catch { /* nothing counted yet */ }
+  return { budget, used, ai: Boolean(env.AI), key: Boolean(env.HOMIE_BRAIN_KEY), model: env.HOMIE_BRAIN_MODEL || DEFAULT_MODEL, ownerModel: OWNER_MODEL };
+}
+
 async function invitesOf(env, game, origin) {
   try {
     const { results } = await env.DB.prepare('SELECT id, code, label, uses, max_uses, expires_at, revoked, created_at, server FROM office_invites WHERE game = ?1 ORDER BY created_at DESC LIMIT 100').bind(game).all();
@@ -500,7 +527,9 @@ export async function officeView(env, cat, origin) {
       id: g.id, name: g.name, launch, launchFrom: row?.launch ? 'office' : g.launch ? 'game.json' : 'default',
       // Servers (0.16.0): each with its policy and what is on it now; its build reads the dial only from netplay rev 6.
       servers: servers.map((sv) => ({ ...serverView(sv, { origin, game: g.id }), live: byServer[sv.id] ?? { rooms: 0, players: 0, ai: 0 }, members: members[sv.id] ?? 0 })),
-      build: { netplayRev: Number.isInteger(g.netplayRev) ? g.netplayRev : null, predates: !(Number(g.netplayRev) >= 6), caps: g.caps ?? null },
+      build: { netplayRev: Number.isInteger(g.netplayRev) ? g.netplayRev : null, predates: !(Number(g.netplayRev) >= 6), caps: g.caps ?? null, guides: Number(g.netplayRev) >= 7 },
+      // 0.17.0: the game's AI guides have words of their own (agents.json): without it they play but never talk.
+      vocab: g.vocab === true,
       passes: (await passList(env, { game: g.id })).filter((x) => x.live || Date.now() - x.createdAt < 7 * 86_400_000),
       remix: remixOf(g, settings), remixBuilt: g.landing?.source !== false, license: licenseOf(g.license).kind,
       seats: seatsOf(g), maxPlayers: max, maxSet: Number(row?.max_players) >= 1 ? Number(row.max_players) : null,
@@ -515,6 +544,7 @@ export async function officeView(env, cat, origin) {
     // The fill-a-spot service (an AI seated in an empty spot for a price) is a money decision: not offered yet.
     fillSpot: { available: Boolean(fillSpot()), note: 'Let a fill-a-spot service seat AI (coming later)' },
     agentsTalk: await talkConsented(env),
+    brain: await brainDay(env),
   };
 }
 async function memberCountsOf(env, game) {
@@ -624,7 +654,10 @@ function checkAction(cat, op, body) {
       if (!meta) return bad('game is one of this studio\'s game ids');
       if (typeof body.server !== 'string' || !(body.server === 'public' || /^[a-z0-9][a-z0-9-]{1,19}$/.test(body.server))) return bad('server is the server\'s id');
       if (!['off', 'script', 'workers-ai', 'owner-key'].includes(body.mode)) return bad('mode is off, script, workers-ai or owner-key');
-      return { ok: true, action: { op, game: meta.id, server: body.server, mode: body.mode } };
+      // The day's budget for the studio's brains: Workers AI neurons (workers-ai) or dollars of the owner's key (owner-key).
+      const budget = body.budget === undefined || body.budget === null ? undefined : Number(body.budget);
+      if (budget !== undefined && (!['workers-ai', 'owner-key'].includes(body.mode) || !(budget >= 0) || budget > (body.mode === 'owner-key' ? 100 : 1e7))) return bad('budget goes with workers-ai (neurons a day; the free allocation is 10,000 an account) or owner-key (dollars a day, at most 100)');
+      return { ok: true, action: { op, game: meta.id, server: body.server, mode: body.mode, ...(budget !== undefined ? { budget } : {}) } };
     }
     default:
       return bad('unknown control');
@@ -670,7 +703,7 @@ export function describe(cat, a) {
     case 'pass': return a.action === 'revoke' ? `Revoke the agent pass ${a.id}: that AI leaves every room and cannot sit again.` : `Issue an agent pass for an AI called "${a.label} · AI".`;
     case 'room-level': return `Set the AI in ${where} to ${levelName(a.level)} (level ${a.level}).`;
     case 'agents-brain': return ['workers-ai', 'owner-key'].includes(a.mode)
-      ? `Let the AI guides on ${gname}'s server ${a.server} talk: they speak only the lines the game's own agents.json gives them (never free text), at most one line every 8 seconds, never about a person, and a player can quiet them. Their brain runs on ${a.mode === 'workers-ai' ? 'this studio\'s own Workers AI (free allowance)' : 'your own AI provider key (your money, capped daily)'}.`
+      ? `Let the AI guides on ${gname}'s server ${a.server} talk: they speak only the lines the game's own agents.json gives them (never free text), at most one line every 8 seconds, never about a person, and a player can quiet them. Their brain runs on ${a.mode === 'workers-ai' ? `this studio's own Workers AI (free allowance${a.budget !== undefined ? `; at most ${Math.round(a.budget).toLocaleString('en-US')} neurons a day` : ''})` : `your own AI provider key (claude-haiku-4-5, your money${a.budget !== undefined ? `, at most $${Number(a.budget).toFixed(2)} a day` : ', capped daily'})`}.`
       : `Set the AI guides' brain on ${gname}'s server ${a.server} to ${a.mode}.`;
     default: return 'A control.';
   }
@@ -686,7 +719,12 @@ export async function needsAsk(env, cat, a) {
     const before = meta ? (await serversOf(env, meta, { fresh: true })).find((x) => x.id === a.server) : null;
     return narrows(before, a.fields);
   }
-  if (a.op === 'agents-brain') return ['workers-ai', 'owner-key'].includes(a.mode) && !(await talkConsented(env));
+  if (a.op === 'agents-brain') {
+    if (['workers-ai', 'owner-key'].includes(a.mode) && !(await talkConsented(env))) return true;
+    // Raising the cap on the owner's own money is the owner's to confirm; Workers AI's free allocation is not money.
+    if (a.mode === 'owner-key' && a.budget !== undefined) return a.budget > (await brainDay(env)).budget.usd;
+    return false;
+  }
   return false;
 }
 
@@ -765,7 +803,7 @@ export async function perform(env, cat, a) {
       try { await writeServer(env, meta.id, sv); } catch (error) { return { ok: false, error: 'not-migrated', message: `Servers need migration 0006_studio_servers.sql (npm run deploy). (${String(error?.message ?? error).slice(0, 120)})` }; }
       const view = serverView(sv, { origin: a.origin ?? '', game: meta.id });
       const notes = [];
-      if (sv.policy === 'beginner' && sv.guides) notes.push(`${sv.guides} AI guide seat${sv.guides === 1 ? '' : 's'} in every room, marked AI: the game's own bots play them now; guides talk once AI talk arrives (a later version, and only with the owner's yes).`);
+      if (sv.policy === 'beginner' && sv.guides) notes.push(`${sv.guides} AI guide seat${sv.guides === 1 ? '' : 's'} in every room, marked AI: they play from the game's script, silent. To let them talk (only the game's own agents.json lines), turn on a brain: agents brain ${meta.id} ${sv.id} workers-ai (the first time asks the owner).${meta.vocab ? '' : ` ${meta.name} has no agents.json yet: write one first.`}`);
       if (sv.policy === 'hybrid') notes.push(`${sv.aiSeats} seat${sv.aiSeats === 1 ? '' : 's'} in every room are AI companions, marked AI; the party votes their level.`);
       if (sv.policy === 'humans-only') notes.push('No AI can join; the game\'s practice bots are off unless the owner turns them on (bots: fill).');
       if (!(Number(meta.netplayRev) >= 6)) notes.push(`${meta.name}'s build predates servers (netplay revision ${meta.netplayRev ?? '5 or older'}): reserved AI seats stay empty and its bots do not read the dial until it is rebuilt with @homie-rocks/studio 0.16.`);
@@ -839,8 +877,24 @@ export async function perform(env, cat, a) {
         await writeServer(env, meta.id, sv);
         if (['workers-ai', 'owner-key'].includes(a.mode)) await env.DB.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('agents_talk_ok', ?1)").bind(String(Date.now())).run();
       } catch (error) { return { ok: false, error: 'not-migrated', message: `Servers need migration 0006_studio_servers.sql (npm run deploy). (${String(error?.message ?? error).slice(0, 120)})` }; }
+      if (a.budget !== undefined) {
+        const day = await brainDay(env);
+        const next = { neurons: day.budget.neurons, usd: day.budget.usd, ...(a.mode === 'workers-ai' ? { neurons: Math.round(a.budget) } : { usd: Math.round(a.budget * 100) / 100 }) };
+        await env.DB.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('brain_budget', ?1)").bind(JSON.stringify(next)).run().catch(() => {});
+      }
       await pushPolicy(env, meta, settings, sv);
-      return { ok: true, op: a.op, game: meta.id, server: sv.id, brain: sv.brain, note: ['workers-ai', 'owner-key'].includes(a.mode) ? 'Saved. AI guides\' talk arrives with @homie-rocks/studio 0.17; until then they play as the game\'s bots, silent.' : 'Saved.' };
+      const day = await brainDay(env);
+      const notes = [];
+      if (!meta.vocab && ['workers-ai', 'owner-key'].includes(a.mode)) notes.push(`${meta.name} has no agents.json yet: its guides play but have no words. Write one (the game skill's "Write the guide vocabulary"), build and deploy.`);
+      if (a.mode === 'workers-ai') notes.push(!env.AI ? 'This Worker has no Workers AI binding yet: run `npm run deploy` once more (it binds Workers AI when a server uses it). Until then the guides answer from the game\'s script.'
+        : !(day.budget.neurons > 0) ? 'The day\'s Workers AI budget is 0: the guides answer from the game\'s script (set --budget to let them think).'
+          : `The guides think with Workers AI (${day.model}) from their next decision: at most ${day.budget.neurons.toLocaleString('en-US')} neurons a day for the whole studio (${Math.round(day.used.neurons).toLocaleString('en-US')} used today), then the game's script until 00:00 UTC.`);
+      if (a.mode === 'owner-key') notes.push(!env.HOMIE_BRAIN_KEY ? 'Set your key on your own computer: `npx --no-install homie-studio agents brain key` opens a page there (the key goes straight to the Worker, never through a chat). Until then the guides answer from the game\'s script.'
+        : !(day.budget.usd > 0) ? 'The day\'s dollar cap is 0: the guides answer from the game\'s script.'
+          : `The guides think with your key (claude-haiku-4-5) from their next decision, at most $${day.budget.usd.toFixed(2)} a day ($${day.used.usd.toFixed(2)} used today), then the game's script until 00:00 UTC.`);
+      if (a.mode === 'script') notes.push('The guides play from the game\'s script, silent.');
+      if (a.mode === 'off') notes.push('The guides are the game\'s plain bots.');
+      return { ok: true, op: a.op, game: meta.id, server: sv.id, brain: sv.brain, budget: day.budget, note: `Saved. ${notes.join(' ')}`.trim() };
     }
     default: return { ok: false, error: 'op' };
   }