@homie-rocks/studio 0.16.1 → 0.18.0

package/lib/cloudflare.mjs

@@ -9,19 +9,24 @@
  * brand-new account with no payment method, by the names in studio.json:
  *   the Worker (pages + rooms), a D1 database, and the Table/Lobby Durable
  *   Objects (SQLite-backed, declared by the Worker).
- * It never creates or binds R2: Cloudflare asks for a payment method before R2
- * works, even inside its free tier, so storage for large media is its own later
- * step (`homie-studio storage add`) that the person agrees to.
+ * It never creates R2: Cloudflare asks for a payment method before R2 works,
+ * even inside its free tier, so storage for large media is its own later step
+ * (`homie-studio storage add`) that the person agrees to. Once a studio has it,
+ * deploy binds it and moves the big songs and videos there first (mediaMove:
+ * uploaded, read back, checked by SHA-256), so the site stops carrying them and
+ * serves them from R2 at the same addresses.
  *
  * It REFUSES to touch a Worker, database or bucket of that name that this
  * studio did not create (studio.json `cloudflare.created` is the record), so it
  * can never overwrite someone's existing site. `deploy --plan` says all of this
  * before anything happens and calls nothing.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
+import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File, sizeOf } from './media.mjs';
 import { repoOf } from './repo.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
@@ -101,11 +106,11 @@ export function deployPlan(root) {
       { kind: 'Durable Object', name: 'Table', what: 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       storage
-        ? { kind: 'R2 bucket', name: storage, what: 'large media for /media/<key> (added with storage add)', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
+        ? { kind: 'R2 bucket', name: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
         : { kind: 'R2 bucket', name: null, what: 'none: a new studio needs no storage. `homie-studio storage add` adds it later, for large media only', state: 'not created', plan: null },
     ],
     cost: storage
-      ? 'Free on Cloudflare\'s Workers Free plan. R2 storage is free up to 10 GB-month; beyond that Cloudflare bills the account directly.'
+      ? `Free on Cloudflare's Workers Free plan. ${R2_COST} Beyond the free tier Cloudflare bills the account directly.`
       : 'Free: everything above is on Cloudflare\'s Workers Free plan, which needs no payment method. Its daily limits (100,000 Worker requests; D1 5 million rows read and 100,000 written) reset at 00:00 UTC; past them requests fail until the reset, nothing is charged.',
     login: 'One approval: `npx wrangler login` opens Cloudflare in the person\'s browser (a free account works; a new one verifies its email address first).',
     address: `https://${cf.worker}.<the account's workers.dev subdomain>.workers.dev`,
@@ -158,9 +163,22 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     for (const line of announced) log(line);
   }
 
-  const b = await build(root, { log });
+  // Big media into the studio's R2 before the build (0.18.0): only with storage this studio made, so a free account
+  // with no payment method is never asked anything about R2. Each file is read back and its SHA-256 compared before
+  // the build stops carrying it; a file that did not make it stays on the site (when it fits) and is named here.
+  const storage = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
+  let media = null;
+  if (storage) {
+    media = await mediaMove(root, { auto: true, accountId, log });
+    for (const m of media.moved ?? []) step(`moved ${m.path} (${sizeOf(m.bytes)}) to R2 and checked it by SHA-256; the site serves it at the same address, ${m.url}`);
+    for (const m of media.failed ?? []) step(`not moved to R2: ${m.path}: ${m.why}`);
+    if (media.why && !media.ok) step(`big media stays on the site this time: ${media.why}`);
+  }
+
+  const b = await build(root, { log, deploy: true });
   // A new studio goes live with its own Home ("First game coming soon") before it has a game.
   step(b.catalogue.length || b.songs.length || b.videos.length ? `built ${b.catalogue.length} game(s), ${b.songs.length} song(s), ${b.videos.length} video(s)` : 'built the home page (no game yet: "First game coming soon")');
+  for (const n of b.mediaNotes ?? []) step(`note: ${n.file}: ${n.why}`);
 
   // The Worker: never one this studio did not make.
   if (!created.has(`worker:${cf.worker}`)) {
@@ -189,7 +207,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
 
   // Storage (R2) is bound only when `storage add` made the bucket. Deploy itself never creates or lists R2, so a
   // free account with no payment method deploys the whole studio.
-  const r2 = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
+  const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
@@ -197,6 +215,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)]);
@@ -232,6 +255,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
     ok: true, command: 'deploy', url, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
+    ...(media ? { media: { moved: media.moved ?? [], failed: media.failed ?? [], inR2: media.inR2 ?? null } } : {}),
     games: b.catalogue.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })),
     songs: b.songs.map((slug) => ({ slug, page: url ? `${url}/music/${slug}/` : null })),
     videos: b.videos.map((slug) => ({ slug, page: url ? `${url}/videos/${slug}/` : null })),
@@ -239,6 +263,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 +338,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);
@@ -372,5 +419,112 @@ export async function storageAdd(root, { log = () => {} } = {}) {
     writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root) }));
   }
   log(`created R2 ${bucket}`);
-  return { ok: true, command: 'storage add', bucket, account: accountId, next: ['npm run deploy   (binds the bucket as MEDIA; the site serves it at /media/<key>)', 'npx --no-install homie-studio media put <file>'] };
+  return { ok: true, command: 'storage add', bucket, account: accountId, cost: R2_COST, next: ['npx --no-install homie-studio media move --dry-run   (which songs and videos go to R2: over 1 MiB, or left out of git)', 'npm run deploy   (binds the bucket as MEDIA, moves them, checks each by SHA-256, and serves them from R2 at the same addresses; the files stay in this folder)'] };
+}
+
+/** One Wrangler command, run without blocking (an upload of a music video takes a while); the last of its words kept. */
+function wranglerRun(bin, args, { cwd, env }) {
+  return new Promise((done) => {
+    const p = spawn(bin, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    const keep = (d) => { out = `${out}${d}`.slice(-8000); };
+    p.stdout.on('data', keep);
+    p.stderr.on('data', keep);
+    p.on('error', (e) => done({ code: 1, out: String(e.message) }));
+    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, '') }));
+  });
+}
+
+/** Read an object back from R2 (`wrangler r2 object get --pipe`) and hash it as it streams: nothing is written to disk. */
+function hashRemote(bin, path, { cwd, env }) {
+  return new Promise((done) => {
+    const p = spawn(bin, ['r2', 'object', 'get', path, '--remote', '--pipe'], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const h = createHash('sha256');
+    let bytes = 0;
+    let err = '';
+    p.stdout.on('data', (d) => { h.update(d); bytes += d.length; });
+    p.stderr.on('data', (d) => { err = `${err}${d}`.slice(-4000); });
+    p.on('error', (e) => done({ code: 1, err: String(e.message) }));
+    p.on('close', (code) => done({ code: code ?? 1, sha256: h.digest('hex'), bytes, err: err.replace(ANSI, '') }));
+  });
+}
+
+/*
+ * `homie-studio media move [<file>...] [--dry-run] [--verify]` (and every `deploy` of a studio with storage): the big
+ * public files of the studio's published songs and videos go into its own R2, at the key that is their path, so the
+ * site keeps serving them at the same address.
+ *
+ *   1. hash the file on this computer (SHA-256);
+ *   2. `wrangler r2 object put <bucket>/<path>`;
+ *   3. read it back (`wrangler r2 object get --pipe`) and hash what R2 returns;
+ *   4. only when size and hash match, record `r2: { key, sha256, bytes, at }` on the manifest's file.
+ *
+ * The next deploy's build leaves a recorded file out of the site's static assets (and serves it from R2). The file
+ * on this computer is never deleted, moved or changed. A file that fails any step is named, and stays on the site.
+ * `--verify` reads every file already recorded back from R2 and checks its hash again (it changes nothing).
+ */
+export async function mediaMove(root, { paths = null, dryRun = false, verify = false, auto = false, accountId = null, log = () => {} } = {}) {
+  const studio = readStudio(root);
+  const cf = { created: [], ...studio.cloudflare };
+  const bucket = cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`) ? cf.r2 : null;
+  const over = r2OverOf(studio);
+  const named = Array.isArray(paths) && paths.length ? paths : null;
+  const rows = mediaPlan(root, { over, paths: named });
+  const view = (r) => ({ path: r.path, kind: r.kind, slug: r.slug, role: r.role, state: r.state, bytes: r.bytes ?? null, ...(r.reason ? { reason: r.reason } : {}), ...(r.why ? { why: r.why } : {}) });
+  const held = rows.filter((r) => r.state === 'r2');
+  const todo = rows.filter((r) => r.state === 'move');
+  const inR2 = [...held, ...todo].reduce((n, r) => n + (r.bytes ?? 0), 0);
+  const base = {
+    command: 'media move', bucket, over, rows: rows.map(view), inR2, cost: R2_COST,
+    // Over the free 10 GB-month, Cloudflare bills the account: say so with the number.
+    ...(inR2 > 10e9 ? { warning: `R2 would hold ${sizeOf(inR2)} of this studio's media, over the 10 GB-month free tier: about US$${(((inR2 - 10e9) / 1e9) * 0.015).toFixed(2)} a month more, billed by Cloudflare to the account` } : {}),
+  };
+  if (!bucket) {
+    return { ok: false, ...base, needs: 'storage', why: 'this studio has no storage yet, so its media stays on the site (files up to 25 MiB each). `npx --no-install homie-studio storage add` adds an R2 bucket; Cloudflare asks for a payment method on the account before R2 works, so ask the person first. Games never need it.' };
+  }
+  if (auto && over === null && !named) return { ok: true, ...base, off: true, moved: [], failed: [], why: 'studio.json media.r2Over is false: nothing moves on its own' };
+  if (dryRun || (!todo.length && !verify)) return { ok: true, ...base, dryRun, moved: [], failed: [], next: todo.length ? 'npx --no-install homie-studio media move   (then npm run deploy)' : null };
+  const bin = wranglerBin(root);
+  if (!bin) return { ok: false, ...base, why: 'Wrangler is not installed in this studio yet: run `npm install` in the studio folder first' };
+  const account = accountId || process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || null;
+  const opts = { cwd: workerDir(root), env: { ...process.env, ...(account ? { CLOUDFLARE_ACCOUNT_ID: account } : {}), WRANGLER_SEND_METRICS: 'false', CI: '1' } };
+  const moved = [];
+  const failed = [];
+  const verified = [];
+  if (verify) {
+    for (const r of held) {
+      const key = r.held?.key ?? r.path;
+      const got = await hashRemote(bin, `${bucket}/${key}`, opts);
+      const ok = got.code === 0 && got.sha256 === r.held?.sha256 && got.bytes === Number(r.held?.bytes);
+      verified.push({ path: r.path, key, ok, bytes: got.bytes, ...(ok ? {} : { why: got.code !== 0 ? `could not read it back: ${got.err.trim().split('\n').slice(-2).join(' ')}` : 'R2 returned different bytes than were recorded' }) });
+      log(`${ok ? 'verified' : 'MISMATCH'} ${r.path} in R2 ${bucket}/${key}`);
+    }
+  }
+  for (const r of todo) {
+    const key = r.path;
+    const url = `/${key.split('/').map(encodeURIComponent).join('/')}`;
+    const sha256 = sha256File(r.abs);
+    log(`uploading ${r.path} (${sizeOf(r.bytes)}) to R2 ${bucket}/${key}`);
+    const put = await wranglerRun(bin, ['r2', 'object', 'put', `${bucket}/${key}`, '--file', r.abs, '--content-type', r.type, '--remote'], opts);
+    // Where the file is meanwhile: on the site when it fits; a bigger one keeps an older R2 copy, or waits.
+    const meanwhile = r.bytes <= MAX_ASSET_BYTES ? ' It stays on the site.' : r.held ? ' Its page keeps playing the older copy in R2.' : ' At this size the site cannot carry it, so its page waits until it is in R2.';
+    if (put.code !== 0) {
+      failed.push({ path: r.path, bytes: r.bytes, why: `${explainCloudflare(put.out, account)?.why ?? `the upload failed: ${put.out.trim().split('\n').slice(-3).join(' ')}`}${meanwhile}` });
+      continue;
+    }
+    const got = await hashRemote(bin, `${bucket}/${key}`, opts);
+    if (got.code !== 0 || got.sha256 !== sha256 || got.bytes !== r.bytes) {
+      failed.push({ path: r.path, bytes: r.bytes, why: `${got.code !== 0 ? `uploaded, but it could not be read back to check it (${got.err.trim().split('\n').slice(-2).join(' ')}); nothing recorded.` : `R2 returned ${got.bytes} bytes with a different SHA-256 from this file's ${r.bytes}; nothing recorded.`}${meanwhile}` });
+      continue;
+    }
+    const at = new Date().toISOString();
+    const manifests = recordMove(root, r.path, { key, sha256, bytes: r.bytes, at });
+    moved.push({ path: r.path, key, bytes: r.bytes, sha256, url, manifests });
+    log(`checked ${r.path} in R2 by SHA-256 (${sha256.slice(0, 12)}…); its address stays ${url}`);
+  }
+  const bad = verified.filter((v) => !v.ok);
+  return {
+    ok: !failed.length && !bad.length, ...base, moved, failed, ...(verify ? { verified } : {}),
+    ...(moved.length ? { next: 'npm run deploy: the site stops carrying these files and serves them from R2 at the same addresses. The files stay in this folder; commit the manifests (they name each file\'s R2 copy), never the media.' } : {}),
+  };
 }

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/media.mjs

@@ -1,9 +1,18 @@
 /**
  * A studio's music/ and videos/ manifests (media/MEDIA.md): what the site shows,
- * and where each file's bytes come from (R2 key, a file in the repository copied
- * into the site, or an absolute https address).
+ * and where each file's bytes come from (the studio's R2, a file in the repository
+ * copied into the site, or an absolute https address).
+ *
+ * BIG MEDIA LIVES IN R2 (0.18.0). Once a studio has storage (`homie-studio storage add`), every public file of a
+ * published song or video that is over `R2_OVER` bytes (studio.json `media.r2Over`), or that git leaves out of the
+ * repository, goes to the studio's own bucket: `homie-studio media move` (and every `deploy`) uploads it, reads it
+ * back and compares SHA-256, and only then records `r2: { key, sha256, bytes, at }` on the manifest's file. A deploy
+ * build then stops carrying that file in the site's static assets, and the Worker serves the very same address
+ * (`/<path>`) from R2, with byte ranges and the same cache headers. The local file is never deleted.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, normalize, relative, resolve, sep } from 'node:path';
 
 export const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -13,6 +22,15 @@ export const KINDS = {
 };
 /** Cloudflare Workers static assets: one file may be at most 25 MiB. */
 export const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+/**
+ * Over this many bytes a public file of a published entry is kept in the studio's R2 once it has storage (the
+ * default for studio.json `media.r2Over`; `false` there keeps every file on the site unless `media move` names it).
+ */
+export const R2_OVER = 1024 * 1024;
+/** Wrangler uploads one object of at most 300 MiB (`wrangler r2 object put`). */
+export const MAX_PUT_BYTES = 300 * 1024 * 1024;
+/** What R2 costs, said the same way everywhere (Cloudflare's R2 pricing page, read 2026-10-01). */
+export const R2_COST = 'R2 is on the studio\'s own Cloudflare account. Serving its files costs nothing in bandwidth (R2 has no egress fees). Storage is free up to 10 GB-month, then US$0.015 per GB-month; uploads (Class A) are free up to 1 million a month and reads (Class B) up to 10 million a month. Cloudflare asks for a payment method on the account before R2 works, even inside the free tier.';
 const TYPES = {
   '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.wav': 'audio/wav', '.flac': 'audio/flac',
   '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime',
@@ -40,15 +58,64 @@ function inside(root, rel) {
   const abs = resolve(root, normalize(rel));
   return abs.startsWith(`${resolve(root)}${sep}`) ? abs : null;
 }
+/** A file's address on the site: its path in the studio, each part encoded (the same before and after it moves to R2). */
+const siteUrlOf = (root, abs) => `/${relative(root, abs).split(sep).map(encodeURIComponent).join('/')}`;
+const relOf = (root, abs) => relative(root, abs).split(sep).join('/');
+const fileOf = (abs) => { try { const st = statSync(abs); return st.isFile() ? st.size : null; } catch { return null; } };
+
+/** studio.json `media.r2Over`: bytes over which a public file goes to R2, or null (`false`: only `media move <file>`). */
+export function r2OverOf(studio) {
+  const v = studio?.media?.r2Over;
+  if (v === false || v === 'off') return null;
+  return Number.isFinite(v) && v >= 0 ? v : R2_OVER;
+}
+
+/** Sizes for people: "45.4 MB", "1.20 GB". */
+export const sizeOf = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(2)} GB` : n >= 1e6 ? `${(n / 1e6).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1e3))} KB`);
+/** A size line as it was set: "1 MiB" for 1048576, else as sizeOf says it. */
+export const lineOf = (n) => (n > 0 && n % 1048576 === 0 ? `${n / 1048576} MiB` : n > 0 && n % 1024 === 0 && n < 1048576 ? `${n / 1024} KiB` : sizeOf(n));
+
+const hashes = new Map();
+/** SHA-256 of a file, read in 8 MiB pieces; remembered per path, size and modified time for the life of the command. */
+export function sha256File(abs) {
+  const st = statSync(abs);
+  const memo = `${abs}\0${st.size}\0${st.mtimeMs}`;
+  if (hashes.has(memo)) return hashes.get(memo);
+  const h = createHash('sha256');
+  const fd = openSync(abs, 'r');
+  const buf = Buffer.allocUnsafe(8 << 20);
+  try {
+    for (;;) { const n = readSync(fd, buf, 0, buf.length, null); if (!n) break; h.update(buf.subarray(0, n)); }
+  } finally { closeSync(fd); }
+  const hex = h.digest('hex');
+  hashes.set(memo, hex);
+  return hex;
+}
+
+/** The R2 record `media move` wrote on a manifest file (its key and the SHA-256 it read back from R2), or null. */
+export function heldOf(f) {
+  const r = f?.r2;
+  return r && typeof r === 'object' && typeof r.key === 'string' && r.key && !r.key.startsWith('players/') && /^[0-9a-f]{64}$/.test(String(r.sha256 ?? '')) ? r : null;
+}
+
+/** Whether R2 has exactly this file: the size and the SHA-256 that `media move` read back from it. */
+export function sameAsHeld(abs, held) {
+  const bytes = fileOf(abs);
+  return bytes !== null && held && Number(held.bytes) === bytes && sha256File(abs) === held.sha256;
+}
 
 /**
  * Every entry of one manifest with its files resolved, and why anything is left out.
- * `r2`: the studio has its own bucket (so a `key` is served at /media/<key>).
+ * `r2`: the studio has its own bucket (so a `key` is served at /media/<key>, and a file `media move` put there at its
+ * own address). `deploy`: a build that goes live (`homie-studio deploy`, or Workers Builds): a file whose exact bytes
+ * are in R2 is not copied into the site. Without it (a local `build`, `dev`), a file that is also on this computer is
+ * still copied when it fits, because `wrangler dev`'s own R2 is empty.
  */
-export function resolveMedia(root, kind, { r2 = false } = {}) {
+export function resolveMedia(root, kind, { r2 = false, deploy = false } = {}) {
   const manifest = readManifest(root, kind);
   const entries = [];
   const skipped = [];
+  const notes = [];
   const seen = new Set();
   // The manifest's own picture (music: `cover`, videos: `poster`): an album cover for every song that has none of
   // its own. A path in the studio (copied into the site) or an https:// address, like any file.
@@ -68,20 +135,45 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
     for (const f of list) {
       if (!f || f.public === false) continue;
       let src = null;
+      // A key from `media put` (before 0.18.0): served at /media/<key>, as it always was.
       if (typeof f.key === 'string' && f.key && r2) src = { from: 'r2', url: `/media/${f.key.split('/').map(encodeURIComponent).join('/')}` };
+      // A file `media move` put in R2: served at its own address, from R2 once the site no longer carries it.
+      const held = heldOf(f);
+      if (!src && held && r2 && f.path) {
+        const abs = inside(root, f.path);
+        if (!abs) { skipped.push({ kind, item: item.slug, file: f.path, why: 'the path is outside the studio' }); continue; }
+        const url = siteUrlOf(root, abs);
+        const local = fileOf(abs);
+        const fromR2 = { from: 'r2', url, key: held.key, bytes: Number(held.bytes) || null };
+        if (local === null) src = fromR2;
+        else if (!deploy) src = local <= MAX_ASSET_BYTES ? { from: 'site', url, abs, rel: relative(root, abs), bytes: local } : fromR2;
+        else if (sameAsHeld(abs, held)) src = { ...fromR2, bytes: local };
+        else if (local <= MAX_ASSET_BYTES) {
+          src = { from: 'site', url, abs, rel: relative(root, abs), bytes: local };
+          notes.push({ kind, item: item.slug, file: f.path, why: 'changed since it went to R2: the site carries this copy until `homie-studio media move` uploads it again (deploy does it when the studio has storage)' });
+        } else {
+          src = fromR2;
+          notes.push({ kind, item: item.slug, file: f.path, why: `changed since it went to R2 (${held.at ?? 'earlier'}), and at ${sizeOf(local)} it is too big for the site: the page plays the copy in R2 until \`homie-studio media move ${f.path}\` uploads this one` });
+        }
+      }
       if (!src && f.path) {
         const abs = inside(root, f.path);
         if (!abs) { skipped.push({ kind, item: item.slug, file: f.path, why: 'the path is outside the studio' }); continue; }
-        if (existsSync(abs) && statSync(abs).isFile()) {
-          const bytes = statSync(abs).size;
-          if (bytes <= MAX_ASSET_BYTES) src = { from: 'site', url: `/${relative(root, abs).split(sep).map(encodeURIComponent).join('/')}`, abs, rel: relative(root, abs), bytes };
-          else skipped.push({ kind, item: item.slug, file: f.path, why: `${Math.round(bytes / 1048576)} MiB is over the 25 MiB the site serves itself: make it smaller, or give the studio storage (homie-studio storage add; Cloudflare asks for a payment method first, so ask the person) and upload it (homie-studio media put ${f.path})` });
-        } else if (f.key && !r2) skipped.push({ kind, item: item.slug, file: f.path, why: `the file is not on this computer and its storage key "${f.key}" needs the studio's storage (homie-studio storage add)` });
-        else if (!f.key && !f.url) skipped.push({ kind, item: item.slug, file: f.path, why: 'the file is not on this computer and has no R2 key or url' });
+        const bytes = fileOf(abs);
+        if (bytes !== null) {
+          if (bytes <= MAX_ASSET_BYTES) src = { from: 'site', url: siteUrlOf(root, abs), abs, rel: relative(root, abs), bytes };
+          else skipped.push({ kind, item: item.slug, file: f.path, why: `${Math.round(bytes / 1048576)} MiB is over the 25 MiB the site serves itself: give the studio storage (homie-studio storage add; Cloudflare asks for a payment method first, so ask the person) and the next deploy moves it to R2 (or homie-studio media move ${f.path} now), or make it smaller` });
+        } else if ((f.key || held) && !r2) skipped.push({ kind, item: item.slug, file: f.path, why: `the file is not on this computer and its copy in R2 ("${f.key ?? held.key}") needs the studio's storage (homie-studio storage add)` });
+        else if (!f.key && !held && !f.url) skipped.push({ kind, item: item.slug, file: f.path, why: 'the file is not on this computer and has no R2 copy or url' });
       }
       if (!src && typeof f.url === 'string' && /^https:\/\//.test(f.url)) src = { from: 'url', url: f.url };
       if (!src) continue;
-      files.push({ role: String(f.role ?? 'file'), name: f.name ?? null, type: f.type ?? typeOf(f.path ?? f.key ?? f.url), bytes: f.bytes ?? src.bytes ?? null, bars: f.bars ?? null, url: src.url, from: src.from, ...(src.abs ? { abs: src.abs, rel: src.rel } : {}) });
+      files.push({
+        role: String(f.role ?? 'file'), name: f.name ?? null, type: f.type ?? typeOf(f.path ?? f.key ?? f.url), bytes: f.bytes ?? src.bytes ?? null, bars: f.bars ?? null, url: src.url, from: src.from,
+        // The Worker serves this address from R2 (the site does not carry it): the catalogue says which key.
+        ...(src.from === 'r2' && src.key ? { r2: src.key } : {}),
+        ...(src.abs ? { abs: src.abs, rel: src.rel } : {}),
+      });
     }
     const main = kind === 'music' ? 'audio' : 'video';
     if (!files.some((f) => f.role === main)) { skipped.push({ kind, item: item.slug, why: `no playable "${main}" file reachable (see the file lines above)` }); continue; }
@@ -94,27 +186,104 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
       files,
     });
   }
-  return { entries, skipped };
+  return { entries, skipped, notes };
 }
 
 /** Copy the site-served files into site/dist and return the catalogue rows (no local paths in them). */
-export function buildMedia(root, dist, { r2 = false, log = () => {} } = {}) {
+export function buildMedia(root, dist, { r2 = false, deploy = false, log = () => {} } = {}) {
   const out = {};
   const skipped = [];
+  const notes = [];
+  let inR2 = 0;
   for (const kind of ['music', 'videos']) {
-    const r = resolveMedia(root, kind, { r2 });
+    const r = resolveMedia(root, kind, { r2, deploy });
     skipped.push(...r.skipped);
+    notes.push(...r.notes);
     out[kind] = r.entries.map((e) => ({
       ...e,
       files: e.files.map(({ abs, rel, from, ...f }) => {
         if (from === 'site') { const dest = join(dist, rel); mkdirSync(dirname(dest), { recursive: true }); cpSync(abs, dest); }
+        if (from === 'r2' && f.r2) inR2++;
         return f;
       }),
     }));
     if (out[kind].length) log(`${kind}: ${out[kind].map((e) => e.slug).join(', ')}`);
   }
+  if (inR2) log(`${inR2} file(s) served from the studio's R2 at their own addresses (not in the site's files)`);
   for (const s of skipped) log(`${s.kind}/${s.item}${s.file ? ` ${s.file}` : ''}: ${s.why}`);
-  return { songs: out.music, videos: out.videos, skipped };
+  for (const s of notes) log(`note: ${s.kind}/${s.item} ${s.file}: ${s.why}`);
+  return { songs: out.music, videos: out.videos, skipped, notes };
+}
+
+/** The files git leaves out of the repository (its .gitignore): a deploy from another computer, or Workers Builds, would not have them. */
+export function gitIgnored(root, rels) {
+  if (!rels.length) return new Set();
+  const r = spawnSync('git', ['check-ignore', '--stdin'], { cwd: root, input: `${rels.join('\n')}\n`, encoding: 'utf8' });
+  if (r.status !== 0 && r.status !== 1) return new Set();
+  return new Set(String(r.stdout ?? '').split('\n').map((l) => l.trim()).filter(Boolean));
+}
+
+/**
+ * What `media move` would do, file by file: every public file of a published song or video (or exactly the files
+ * named), with its state:
+ *   move       it goes to R2 (over the size, git leaves it out, or it was named; or it changed since it went there)
+ *   r2         R2 already has these exact bytes (size and SHA-256 match the record)
+ *   site       it stays on the site (small enough, and in the repository)
+ *   media      it has a /media/<key> address from `media put` (left as it is)
+ *   too-big    over the 300 MiB one Wrangler upload takes
+ *   missing    not on this computer
+ *   unlisted   named, but in no manifest
+ */
+export function mediaPlan(root, { over = R2_OVER, paths = null } = {}) {
+  const want = paths ? new Set(paths.map((p) => { const abs = inside(root, relative(root, resolve(String(p)))); return abs ? relOf(root, abs) : String(p); })) : null;
+  const found = [];
+  const seen = new Set();
+  for (const kind of ['music', 'videos']) {
+    for (const item of readManifest(root, kind).items) {
+      if (!item || typeof item !== 'object') continue;
+      for (const f of Array.isArray(item.files) ? item.files : []) {
+        if (!f || f.public === false || typeof f.path !== 'string') continue;
+        const abs = inside(root, f.path);
+        if (!abs) continue;
+        const rel = relOf(root, abs);
+        if (seen.has(rel) || (want ? !want.has(rel) : item.published !== true)) continue;
+        seen.add(rel);
+        found.push({ kind, slug: item.slug ?? null, role: String(f.role ?? 'file'), path: rel, abs, type: f.type ?? typeOf(rel), f });
+      }
+    }
+  }
+  const ignored = gitIgnored(root, found.map((r) => r.path));
+  const rows = found.map(({ f, ...row }) => {
+    const held = heldOf(f);
+    if (typeof f.key === 'string' && f.key) return { ...row, state: 'media', why: `in R2 at /media/${f.key} since \`media put\`; left as it is` };
+    if (row.path.startsWith('players/')) return { ...row, state: 'site', why: 'players/ is the players\' own part of the bucket' };
+    const bytes = fileOf(row.abs);
+    if (bytes === null) return { ...row, state: held ? 'r2' : 'missing', bytes: held ? Number(held.bytes) : null, ...(held ? { held } : { why: 'not on this computer' }) };
+    const reason = want ? 'named' : over !== null && bytes > over ? `over ${lineOf(over)}` : ignored.has(row.path) ? 'git leaves it out of the repository' : null;
+    if (held && sameAsHeld(row.abs, held)) return { ...row, bytes, state: 'r2', held };
+    if (!reason && !held) return { ...row, bytes, state: 'site' };
+    if (bytes > MAX_PUT_BYTES) return { ...row, bytes, state: 'too-big', why: `${sizeOf(bytes)} is over the 300 MiB one Wrangler upload takes: make a smaller delivery (the video skill's cuts are far smaller), or upload it with an S3 tool and record it by hand` };
+    return { ...row, bytes, state: 'move', reason: held ? 'changed since it went to R2' : reason, ...(held ? { held } : {}) };
+  });
+  if (want) for (const p of want) if (!seen.has(p)) rows.push({ path: p, state: 'unlisted', why: 'not a public file of any entry in music/manifest.json or videos/manifest.json: add it to an entry first' });
+  return rows;
+}
+
+/** After R2 has the file and its SHA-256 matched: record it on every manifest file with that path. */
+export function recordMove(root, rel, { key, sha256, bytes, at = new Date().toISOString() }) {
+  const touched = [];
+  for (const kind of ['music', 'videos']) {
+    const m = readManifest(root, kind);
+    let hit = false;
+    for (const item of m.items) {
+      for (const f of Array.isArray(item?.files) ? item.files : []) {
+        const abs = typeof f?.path === 'string' ? inside(root, f.path) : null;
+        if (abs && relOf(root, abs) === rel) { f.bytes = bytes; f.r2 = { key, sha256, bytes, at }; hit = true; }
+      }
+    }
+    if (hit) { writeManifest(root, kind, m); touched.push(relative(root, manifestPath(root, kind))); }
+  }
+  return touched;
 }
 
 /** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */

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,