@homie-rocks/studio 0.24.3 → 0.24.5

package/lib/local-ai.mjs

@@ -0,0 +1,66 @@
+/**
+ * THE PERSON'S OWN AI (@homie-rocks/studio 0.24.4): Cloudflare's Clef decision model on this computer, through Ollama.
+ * The same typed questions the studio's Workers AI answers, at /v1/systemone, free and offline:
+ *
+ *   homie-studio dev        finds it and hands it to the local Worker (HOMIE_LOCAL_AI), so AI guides, room chat's review
+ *                           and a game's own decisions (net.decide) need no Cloudflare while building
+ *   agents sit --brain local / the MCP's agent_sit { brain: "local" }
+ *                           a guide's seat that thinks on this computer every few seconds, with no AI turn per decision
+ *   homie-studio doctor     says what is there, and what one sentence gets the rest
+ *
+ * It never downloads a model. `ollama pull clef-flash` is about 11 GB (clef, the 27B, about 18 GB): the person says yes
+ * first, every time (the studio skill asks and names the size). It needs Ollama 0.35.1 or later (the first with Clef).
+ */
+
+export const OLLAMA_BASE = 'http://127.0.0.1:11434';
+export const OLLAMA_MIN = '0.35.1';
+/** The models Homie uses, smallest first, and what each costs the disk (ollama.com/library, 2026-10-02). */
+export const LOCAL_MODELS = Object.freeze([
+  Object.freeze({ name: 'clef-flash', size: 'about 11 GB', params: '9B' }),
+  Object.freeze({ name: 'clef', size: 'about 18 GB', params: '27B' }),
+]);
+
+const newer = (a, b) => {
+  const pa = String(a).split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i += 1) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  return true;
+};
+
+/** Only a loopback address: Homie never sends a game's state to another machine's Ollama. */
+export const loopbackBase = (raw) => {
+  const s = String(raw ?? '').trim().replace(/\/+$/, '');
+  return /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\]):\d{2,5}$/.test(s) ? s : null;
+};
+
+/**
+ * Is Clef on this computer? `{ ok, base, model, version }`, or `{ ok: false, why, say, version?, base }` with why one of
+ * no-ollama, old-ollama, no-model. `HOMIE_OLLAMA` names another loopback port. Two quick local requests, nothing else.
+ */
+export async function detectLocalAi({ env = process.env, fetchFn = globalThis.fetch, ms = 1500 } = {}) {
+  const base = loopbackBase(env.HOMIE_OLLAMA) ?? OLLAMA_BASE;
+  const get = async (path) => {
+    const res = await fetchFn(`${base}${path}`, { signal: AbortSignal.timeout(ms) });
+    if (!res.ok) throw new Error(`${path} answered ${res.status}`);
+    return res.json();
+  };
+  let version = null;
+  try { version = String((await get('/api/version'))?.version ?? ''); } catch {
+    return { ok: false, base, why: 'no-ollama', say: `Ollama is not running on this computer (${base}). With it and clef-flash, AI guides, chat review and game decisions run here for free while building; without it they play from the game's script under dev.` };
+  }
+  if (!newer(version, OLLAMA_MIN)) return { ok: false, base, version, why: 'old-ollama', say: `Ollama ${version} is here; Clef needs ${OLLAMA_MIN} or later. Updating Ollama is the person's to do (its own app updates itself, or ollama.com/download).` };
+  let names = [];
+  try { names = ((await get('/api/tags'))?.models ?? []).map((m) => String(m?.name ?? m?.model ?? '')).filter(Boolean); } catch { names = []; }
+  for (const want of LOCAL_MODELS) {
+    const hit = names.find((n) => n === want.name || n.startsWith(`${want.name}:`));
+    if (hit) return { ok: true, base, version, model: hit };
+  }
+  const flash = LOCAL_MODELS[0];
+  return {
+    ok: false, base, version, why: 'no-model', models: names.length,
+    say: `Ollama ${version} is here without Clef. Downloading it is the person's choice: ask first. \`ollama pull ${flash.name}\` downloads ${flash.size} (the ${flash.params} model; ${LOCAL_MODELS[1].name} is ${LOCAL_MODELS[1].size}). Then run dev again.`,
+  };
+}
+
+/** The Worker variables that hand a found model to `wrangler dev` (`--var` pairs), or none. */
+export const localAiVars = (found) => (found?.ok ? ['--var', `HOMIE_LOCAL_AI:${found.base}`, '--var', `HOMIE_LOCAL_AI_MODEL:${found.model}`] : []);

package/lib/mcp-tools.mjs

@@ -33,6 +33,7 @@ import { STUDIO_VERSION } from './version.mjs';
 import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
 import { pinnedVersion } from './upgrade.mjs';
 import { AgentSeat } from './agent-seat.mjs';
+import { detectLocalAi } from './local-ai.mjs';
 import { LAB_PORT, runningLab } from './lab.mjs';
 import { pictureFor } from './pictures.mjs';
 import { ART_UI, artToolDefs } from './art-tools.mjs';
@@ -1050,17 +1051,24 @@ export function toolDefs(ctx, avail = {}) {
     {
       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'] },
+      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)'), brain: { type: 'string', enum: ['local'], description: 'Optional: "local" lets Cloudflare\'s Clef decision model on this computer (Ollama with clef-flash) choose every few seconds instead of you, free; agent_look shows what it chose and agent_do still overrides it. Never downloads a model: if Ollama has no clef-flash this says what the download costs, and the person decides.' }, ...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 });
+        let local = null;
+        if (a.brain === 'local') {
+          const found = await detectLocalAi();
+          if (!found.ok) return fail(`No local brain: ${found.say}`, { kind: 'agent', ok: false, error: found.why });
+          local = found;
+        }
+        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) : local ? 'Clef' : 'Claude', root, brain: local ? 'local' : null, local });
         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;
+        if (local) return ok(`Seated as ${r.name} in ${r.room} (seat ${r.seat}), thinking with ${local.model} on this computer every few seconds (free; nothing sent to Cloudflare). agent_look shows its last decisions; agent_do overrides; agent_stand ends it.`, { kind: 'agent', ...r });
         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 });
       },
     },

package/lib/scaffold.mjs

@@ -221,10 +221,16 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Import it as \`import { createNetplay } from '@homie-rocks/studio/netplay'\`.
 - Phones and computers: touch controls on phones only, keys on computers; keep the
   centre of the screen clear during play.
-- The play page's small room button (Invite, Big screen, the room code) sits top right. If the game's
-  scoreboard or a bar is there, move it in game.json \`"screen": { "share": … }\`: a corner or \`top-center\`, per
-  device (\`desk\`, \`phone\`, \`sideways\`), with an \`x\` / \`y\` offset in pixels, and \`"label": false\` to keep it
-  a small icon (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Look at it on a phone and a computer.
+- The play page's small room button (Invite, Big screen, the room code) sits top right, with the Chat pill
+  beside it (a round icon on a phone, as the room button is). If the game's scoreboard or a bar is there, move
+  both in game.json \`"screen": { "share": … }\`: a corner or \`top-center\`, per device (\`desk\`, \`phone\`,
+  \`sideways\`), with an \`x\` / \`y\` offset in pixels, and \`"label": false\` to keep them small icons
+  (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Room chat's strip of new lines shows for a moment at the
+  bottom left: if the game's HUD or controls are there, \`"screen": { "chat": … }\` puts it where the game has
+  room (\`at\`: a corner, \`top-center\` or \`bottom-center\`; \`x\` / \`y\`; per device, and \`tv\` for the big
+  screen), or \`"lines": "sheet-only"\` keeps new lines in the Chat sheet, the pill counting them, so a game with
+  a busy HUD keeps typed chat (\`node_modules/@homie-rocks/studio/chat/CHAT.md\`). Look at both on a phone and a
+  computer while a round is on and somebody says something.
 - **Watch any player.** Every live room can be watched at \`/<id>/watch?room=<room>\` (each room on the Rooms page
   and the landing has a Watch button): the game itself, drawn by the watcher's own browser, which never takes a
   seat, with a strip of the players to switch between (a tap, keys 1-9, A for Auto, O for the whole room). Point the
@@ -342,6 +348,13 @@ studio's pinned copy, never a registry lookup of the bare name.
   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.
+- **Clef (0.24.4):** Workers AI's guides think with Cloudflare's decision model \`@cf/cloudflare/clef-flash\` (it
+  picks among the vocabulary's goals, values and lines; it never writes text; about 9 neurons a decision).
+  \`agents try <id> --view <file> [--ask …] [--model …]\` shows what the brain would decide in one moment. Under
+  \`npm run dev\`, Clef on this computer (Ollama with \`clef-flash\`) runs the guides, chat review and game
+  decisions for free when it is here; **never download it without the person's yes** (\`ollama pull clef-flash\` is
+  about 11 GB). A game whose game.json says \`"decide": true\` may ask \`net.decide(state, questions, { floor })\`
+  on the host (\`NETPLAY.md\` section 20): per beat or per turn, never per frame.
 
 ## Selling things (the shop)
 

package/lib/servers.mjs

@@ -18,8 +18,14 @@
  *   homie-studio agents brain key [--remove]          the owner's own AI key (owner-key brains), from a page on this
  *                                                     computer only: it goes straight to the Worker secret
  *                                                     HOMIE_BRAIN_KEY, never through a chat, a file or a log
- *   homie-studio agents sit <game> [--server <id>] [--pass hap_…] [--label Claude]
- *                                                     sit in a guide's seat from this terminal (the local MCP's agent_sit)
+ *   homie-studio agents sit <game> [--server <id>] [--pass hap_…] [--label Claude] [--brain local]
+ *                                                     sit in a guide's seat from this terminal (the local MCP's agent_sit);
+ *                                                     --brain local: Clef on this computer (Ollama) decides, free
+ *   homie-studio agents try <game> --view <file.json> [--ask <ask>[:<arg>=<value>,…] --from <seat>] [--model <id>]
+ *                       [--mode workers-ai|owner-key|script] [--quiet] [--avoid <seat>,…]
+ *                                                     what the studio's guide brain would decide in that moment, with
+ *                                                     no seat taken: the decision, the brain's own pick, how sure, how
+ *                                                     long and what it cost (spent from the guides' day)
  *
  * The proof of ownership is the studio's own Cloudflare login, as for the office: a ten-minute office key is minted
  * and dropped around each call. Making a server, a widening change, a pass and a room's level happen at once. A
@@ -128,6 +134,29 @@ export async function agentsBrain(root, game, server, mode, { url, budget } = {}
   return askedFor(root, url, r, 'agents brain');
 }
 
+/**
+ * `homie-studio agents try`: the studio's guide brain on one moment (a view file, asks), from its live Worker (or
+ * `homie-studio dev`). The answer is the office's (worker/office.mjs agentsTry).
+ */
+export async function agentsTry(root, game, { url, view, ask, from, model, mode, quiet, avoid, players, readFile } = {}) {
+  const usage = 'usage: homie-studio agents try <game> --view <file.json> [--ask <ask>[:<arg>=<value>,…] --from <seat>] [--model <id>] [--mode workers-ai|owner-key|script] [--quiet] [--avoid <seat>,…]';
+  if (!GAME.test(String(game ?? '')) || typeof view !== 'string') return { ok: false, command: 'agents try', why: usage };
+  let v;
+  try { v = JSON.parse(readFile(view)); } catch (error) { return { ok: false, command: 'agents try', why: `--view is a JSON file of the game state a guide sees (${String(error?.message ?? error).slice(0, 80)})` }; }
+  const seats = (x) => (x === undefined || x === true ? undefined : String(x).split(',').map(Number).filter((n) => Number.isInteger(n) && n >= 0));
+  const asks = [];
+  if (typeof ask === 'string') {
+    const [k, rest = ''] = ask.split(':');
+    const args = Object.fromEntries(rest.split(',').filter(Boolean).map((kv) => { const [a, val = ''] = kv.split('='); return [a, /^\d+$/.test(val) ? Number(val) : val]; }));
+    asks.push({ k, args, from: Number.isInteger(Number(from)) ? Number(from) : 0 });
+  }
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/try', {
+    game, view: v, asks, ...(typeof model === 'string' ? { model } : {}), ...(typeof mode === 'string' ? { mode } : {}),
+    ...(quiet ? { quiet: true } : {}), ...(seats(avoid) ? { avoid: seats(avoid) } : {}), ...(seats(players) ? { players: seats(players) } : {}),
+  }));
+  return r.ok ? { ok: true, command: 'agents try', ...r } : { ok: false, command: 'agents try', why: r.message ?? r.why };
+}
+
 /**
  * `homie-studio agents brain key`: the owner's own AI provider key (owner-key brains: claude-haiku-4-5), typed once
  * into a page on this computer (127.0.0.1, one use, ten minutes) and handed straight to `wrangler secret put

package/lib/template-history.json

@@ -1117,6 +1117,84 @@
      }
     }
    }
+  },
+  "0.24.4": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "124772c374de7390",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
+  },
+  "0.24.5": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "abf2f0d59341512d",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "124772c374de7390",
+     "## Running live games (the back office)": "4aa5f513a7cd2c3b",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "7e8458adc1b81ece",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -309,6 +309,7 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 | `roster` | host | `slots` | Labels it (section 17: a host cannot hide an AI), stores it, forwards it, and tells the shell's watchers. |
 | `caps` | host (revision 6) | `caps: ('skill'\|'agents')[]` | What the host's game does with servers: its bots read the dial, and it moves AI bodies. Stored as the room's (the play page offers the vote; a lite agent may sit) and in the watch feed. |
 | `vote` | a seated person, or the host (revision 6) | `of: 'skill'`, `n?: 1..levelMax`, `open?: true`, `reason?` | `open` starts the party's vote on the dial (a player may open one every 2 minutes); `n` casts or changes this seat's vote. Agents and watchers never vote. The shell's watch socket may send it too, counted as the seat of the client with the same browser key. |
+| `decide` | host (0.24.4) | `n`, `state`, `questions` | A game's own decision (section 20): checked, paced (one every 3 s and 20 a minute per room), handed to the Table's decision model; answered with `decided` to that socket only. |
 | `ping` | everyone | `c`, `hid` | Replies `pong`. A host whose `hid` turns true yields. |
 | `yield` / `bye` | host / anyone | — | `yield` elects another host if one is available. `bye` is a close. |
 
@@ -328,6 +329,7 @@ browser (an `ev` to its seat); only that browser changes and saves the player's
 | `round` / `roster` | everyone but the host | `round` / `slots` |
 | `pong` | the pinger | `c`, `st` |
 | `error` | the offender | `code`, `message`, `of?`, `until?` |
+| `decided` | the host that asked (0.24.4) | `n`, `ok`, and `by`, `picks`, `p`, `ms`; or `why` (`off`, `no-ai`, `budget`, `pace` and `retryMs`, `busy`, `bad`, `slow`, `error`, `not-host`) |
 | `announce` | everyone (and in `welcome.announce`) | `id`, `text` (`null`: taken down), `at`, `until`, `from: 'studio'` (section 15) |
 | `mute` | everyone | `id`, `seat`, `until` (`0`: unmuted) (section 15) |
 | `watch` | one watcher | `follow`, `why?` (`overview`, `seated-here`): whether it may follow one player now (section 16) |
@@ -396,6 +398,7 @@ so `ev.origin` is `"null"`.
 | `ckpt` | < 32 KB | 64 KB (128 KB for 17–32 seats) | 1 Hz | 4 |
 | `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB (16 / 8 KB for 17–32 seats) | on change | 4 / 8 |
 | `ping` | — | 256 B | every 2 s | 8 |
+| `decide` | < 2 KB | 6 KB (state 2 KB) | per beat (section 20) | 2; and per room one every 3 s, 20 a minute |
 
 **Sockets.**
 - At most `maxPlayers + 16` per room, and per client address per room **12, or every seat
@@ -1057,12 +1060,29 @@ brain never runs in the frame loop, and it can only choose: goals and lines are
 game's own vocabulary, never free text.
 
 **Where a brain runs.** In the room's own Table, on the studio owner's Worker (a *house
-guide*): Workers AI through the `AI` binding (model var `HOMIE_BRAIN_MODEL`, default
-`@cf/meta/llama-3.1-8b-instruct-fp8-fast`), or the owner's own key (Worker secret
-`HOMIE_BRAIN_KEY`, `claude-haiku-4-5` through the official `@anthropic-ai/sdk`). Or in the
-owner's own AI through the local MCP (`agent_sit`, about 30 s a decision). With none of them,
-over the day's budget, or between decisions: the game's scripted floor (`decide`). homie.rocks
-runs nothing and stores nothing.
+guide*): Workers AI through the `AI` binding (model var `HOMIE_BRAIN_MODEL`, default since
+0.24.4 `@cf/cloudflare/clef-flash`, Cloudflare's **Clef** decision model; `@cf/cloudflare/clef`,
+the 27B, or a chat model such as `@cf/meta/llama-3.1-8b-instruct-fp8-fast` also work), or the
+owner's own key (Worker secret `HOMIE_BRAIN_KEY`, `claude-haiku-4-5` through the official
+`@anthropic-ai/sdk`). Under `homie-studio dev` with no binding: Clef on the person's own computer
+(Ollama with `clef-flash`, which dev finds; free). Or in the owner's own AI through the local MCP
+(`agent_sit`, about 30 s a decision), or a seat that thinks with Clef on the owner's computer
+(`agent_sit { brain: "local" }`). With none of them, over the day's budget, or between decisions:
+the game's scripted floor (`decide`). homie.rocks runs nothing and stores nothing.
+
+**Clef asks the decision as the questions it is.** A decision model never writes text: it takes a
+state and typed questions and returns a probability for every allowed answer, in one pass. A guide's
+decision is a Choice of goal (only goals whose every argument has a value to take), a Choice per set
+of argument values (one question for a goal's quest and a line's quest, so what the guide does and
+says agree; a seat that said "no thanks" and the guide's own seat are never options), a Choice of
+line or none (only when the guide may speak), and, with no ask open, a yes/no "anything to say at
+all?" that a line also needs. The newest ask is in the goal question itself, with the answer
+agents.json gives it. The state is the sanitized view, the open asks, who said no thanks, the
+guide's own last lines and who is new to it. The answers are composed back into one decision, which
+parseDecision and every fixed rule still check. Measured 2026-10-03 on 64 recorded Ember Vale
+moments (`homie-studio agents try`, a throwaway studio): Clef answered 36 of 40 open asks itself
+(Llama 3.1 8B: 0 of 40), blind judges preferred its decisions in 51 of 64 (Llama in none), model time
+p50 259 ms, p90 433 ms (Llama 303 / 364 ms).
 
 ### The vocabulary: `games/<id>/agents.json`
 
@@ -1161,14 +1181,16 @@ with a pass (the owner's own Claude) takes a guide's seat from a house guide (`a
 | Pace | At least 3 s between AI calls per guide, at most 10 a minute; one alarm per room at a time, at most one every 3 s. Never `setInterval`. |
 | Prompt | System: the persona, the goals, the lines, the asks (about 400 tokens, stable). User: the view (sanitized: no key that names a person, an account, a ticket, an address or an age; nothing that looks like a secret; seats, never names), the asks, and the last three party lines as ids and arguments (free text only on a `speech: game` server: quoted, 120 characters, labelled as data). |
 | Output | One JSON object `{ goal, args, say, sayArgs }` (a JSON schema where the provider takes one). Anything else (prose, a code fence, an unknown id, a wrong or extra argument, a player who said no thanks) is no decision: the scripted floor answers instead. |
-| Fixed rules | A person's ask is answered the way agents.json says (its `goal`): a model's other choice is overruled, and the asked-for goal is carried through until it is done (or 60 s) with no model call meanwhile but for a new ask. A line at most every 8 s. "No thanks" holds the guide off that player for 10 minutes. No goal aims at a player. |
+| Fixed rules | A person's ask is answered the way agents.json says (its `goal`, with the values the person asked for): a model's other goal, or the asked goal with another value, is overruled, and the asked-for goal is carried through until it is done (or 60 s) with no model call meanwhile but for a new ask. A line at most every 8 s. "No thanks" holds the guide off that player for 10 minutes. No goal aims at a player. |
 | Budget | A day, for the whole studio (meta `brain_budget`): 8,000 Workers AI neurons (the free allocation is 10,000 an account), $1 of the owner's key. Counted in `stats_daily` (`brain-calls`, `brain-neurons`, `brain-microdollars`), written at most once a minute. Over it: the scripted floor until 00:00 UTC. |
-| Log | The last 50 decisions per room (seat, goal, line, provider, time, why), in memory, in the office. |
+| Log | The last 50 decisions per room (seat, goal, line, provider, time, why; the model, Clef's probability for the goal and line, and the brain's own pick when a rule overruled it), in memory, in the office. |
+| Try | `homie-studio agents try <game> --view <file> [--ask …] [--model …]` (office API `/_studio/api/agents/try`): the same brain and rules on one moment, no seat taken, spent from the same day. |
 
 **Cost.** A house guide costs no request of its own beyond the alarm: one per room per due
-decision, at most one every 3 s. A decision is about 4.3 Workers AI neurons
-(`@cf/meta/llama-3.1-8b-instruct-fp8-fast`: 700 tokens in, 40 out), or $0.0009 of the owner's
-key.
+decision, at most one every 3 s. A Clef decision is about 9 Workers AI neurons (clef-flash: about
+1,000 tokens in at $0.09 a million, nothing for output), so the default day of 8,000 is about 900
+decisions; a Llama decision is about 4.1 (700 tokens in, 40 out); the owner's key about $0.0009.
+Under dev, Clef on the person's own computer costs nothing.
 
 **Kids and safety.** The AI never types: it picks ids, the game renders the creator's text.
 A beginner server's chat is quick lines only; on a kids server names are handles and no free
@@ -1270,7 +1292,7 @@ and reach every screen at once.
 | Review | |
 |---|---|
 | Budget | A day, for the whole studio (meta `chat_budget`): 2,000 neurons by default. With the AI guides' 8,000 that is the 10,000 Workers AI gives an account free a day. A short message measured about 2.3 neurons (clef-flash: $0.09 per million input tokens, no output charge; the question and its answers are most of the input), so about 850 reviewed messages a day. Counted in `stats_daily` (`chat-reviews`, `chat-neurons`). |
-| No review | No `AI` binding (`homie-studio dev` without `--remote-ai`), the day's budget used, the model failing or slower than 1.5 s, more than 8 messages waiting: the floor alone decides, the message goes out, and the office counts it. |
+| No review | No `AI` binding (`homie-studio dev` without `--remote-ai`, unless Clef is on the person's own computer: then it reviews there, free), the day's budget used, the model failing or slower than 1.5 s, more than 8 messages waiting: the floor alone decides, the message goes out, and the office counts it. |
 | The owner | The studio's owner is never reviewed or held by slow mode (their lines are marked `owner`). |
 
 ### The owner's tools
@@ -1318,16 +1340,20 @@ ticker.
 ### What the page does (worker/chat-page.mjs)
 
 - **Play:** a Chat pill in the room button's band (game.json `screen.share` already keeps that
-  corner clear of the game's HUD), with a count of unread lines; its sheet: the room's last
+  corner clear of the game's HUD; a round icon on a phone and beside a room button kept an icon,
+  and on a computer wherever its word would reach the middle third of the top), with a count of
+  unread lines; its sheet: the room's last
   minutes, a row of reactions (2.5 rem circles that pop), the quick lines, typing where the rules
   allow it (and why not where they do not: "Sign in to type here. Emoji are open to everyone."),
   Report on a line, and two switches kept in this browser: **Show my messages over my character**
-  and **Show chat on this screen** (off: no ticker, no float, no bubbles in this game). New lines
-  show for a moment where the status chip sits (game.json `"screen": { "chat": "bottom-right" }`
-  moves them; `false` keeps only the pill's count).
+  and **Show chat on this screen** (off: no strip, no float, no bubbles in this game). New lines
+  show for a moment where the status chip sits; game.json `"screen": { "chat": … }` moves that
+  strip per device (`at`, `x` / `y`, `desk`, `phone`, `sideways`, `tv`) or keeps new lines in the
+  sheet (`"lines": "sheet-only"`, or `false`: only the pill's count). chat/CHAT.md has the fields.
 - **Float:** every reaction rises up every screen in the room, as on the television: at most six
   a second and eighteen at once, 2.4 s each with a little sway. The sender's own floats at once.
-- **TV** (`/<game>/tv`): the room's lines in the corner the QR card does not use, no typing.
+- **TV** (`/<game>/tv`): the room's lines in the corner the QR card does not use (or game.json
+  `screen.chat`'s corner), no typing.
 - **Watch:** a Chat button in the band; its panel over the stage (a bottom sheet on a phone).
 
 **Privacy.** Nothing a person says is stored: the room keeps the last 50 lines of the last 15
@@ -1344,3 +1370,55 @@ about 2.3 neurons a typed line, inside the free allocation by default.
 **Old games and old relays.** A game built before revision 8 has the panel, the float, the ticker
 and the TV corner; it draws no bubbles and its own UI cannot send. A revision-8 helper on an older
 relay never hears a `line` and has `chatRules` null.
+
+---
+
+## 20. A game's own decisions (0.24.4)
+
+Clef answers in about a tenth of a second and never writes text, so a game can ask it what to do
+next about its own state: a tactic for its opponents, an NPC's reaction from a fixed set, a
+director's call (a wave now? push harder?), a turn-based move. The host asks; the room's own
+Durable Object asks the studio's Workers AI (or Clef on the person's own computer under `dev`);
+the answer comes back as option ids, yes or no, and numbers. Nothing a player reads comes from a
+model.
+
+```ts
+const d = await net.decide(
+  { heroes: [{ hp: 40 }, { hp: 90 }], slimes: { count: 9 } },           // the game's state (sanitized; seats, never names)
+  {
+    tactic: { type: 'choice', instructions: 'How should the slimes hunt?', criteria: { chase: 'Rush the nearest hero', surround: 'Close in from every side' } },
+    wave: { type: 'noul', instructions: 'Should a wave come now?' },
+    pressure: { type: 'score', instructions: 'How hard should the vale push?', criteria: ['A breather', 'Steady', 'Fierce'] },
+  },
+  { floor: () => ({ tactic: 'chase', wave: false, pressure: 1 }) },  // the game's own answer, synchronous
+);
+// d.by: 'ai' | 'local' | 'floor'; d.picks: { tactic: 'surround', wave: false, pressure: 1.4 }; d.p: probabilities
+```
+
+| | |
+|---|---|
+| Opt-in | game.json `"decide": true` (the build carries it into games.json; deploy binds Workers AI for it). Without it the room answers `off` and the floor plays. |
+| Questions | 1 to 8: Choice (2 to 26 option ids), yes/no (`noul`), Score (2 to 10 levels, lowest first; the pick is the probability-weighted level). Instructions and descriptions at most 160 characters. The state at most 2 KB after the same sanitizing as a guide's view. |
+| Frames | Host to relay `{ t: 'decide', n, state, questions }`; relay to that host only `{ t: 'decided', n, ok, by, picks, p, ms }` or `{ t: 'decided', n, ok: false, why }` (`off`, `no-ai`, `budget`, `pace` with `retryMs`, `busy`, `bad`, `slow`, `error`, `not-host`). |
+| Pace | One ask every 3 s and 20 a minute per room, two at a time; the helper waits 2.5 s (at most 5) and then answers from the floor. After `off`, `no-ai` or `budget` it asks again only after a minute. |
+| Budget | The AI brains' day (meta `brain_budget`, 8,000 neurons by default): decisions and guides share it, counted as `brain-calls` source `decide`. About 4 neurons for three short questions. |
+| Office | Each room's decisions: how many, who answered, the model's median time, the neurons. Never a state. |
+
+**What rate is real.** Measured 2026-10-03 on a throwaway studio (Ember Vale's slimes' director,
+three questions every 6 s): the host's round trip p50 160 to 253 ms, p90 347 to 497 ms; the model's
+time in the room p50 115 ms; about 4.1 neurons a decision. So never per frame; per second is fast
+enough but one room asking every second would spend about 15,000 neurons an hour, more than the free
+allocation's whole day; **per beat (every 5 to 10 s), per turn, or on an event** is the rate that fits
+the free plan (a room asking every 6 s: about 2,500 neurons an hour). Clef on the person's own
+computer costs nothing; its time depends on the computer.
+
+**Kids and the dial.** A decision moves the game's own world (its opponents, its director), never a
+person, and never the party's skill dial: the bots' level stays the room's. On a kids server the game
+keeps its decisions gentle (Ember Vale's slimes never gang up on the most hurt hero there, and the vale
+never pushes past steady). The state follows a view's rules: game state and seats, never a name, an
+account or typed text.
+
+**Ember Vale** (the starter, opt-in: its game.json ships `"decide": false`): every 6 s of a live night
+the host asks how the slimes hunt (chase, surround, gang up on the most hurt, regroup at the King),
+whether a wave comes, and how hard to push; every screen shows what the slimes are up to when a model
+chose it. The floor is the vale as it always played.

package/netplay/netplay.ts

@@ -402,6 +402,8 @@ export interface NetStats {
   reconnects: number;
   promotions: number;
   round: number | null;
+  /** Section 20: the host's decisions: asked, answered by the studio's model ('ai'), the person's own Ollama ('local'), or the floor; median ms. */
+  decides?: { asked: number; ai: number; local: number; floor: number; msP50: number | null };
 }
 
 export interface Vec { x: number; y: number; z?: number }
@@ -497,6 +499,29 @@ export interface NetHandlers<S, A, C> {
   held: (h: ChatHeld) => void;
 }
 
+/**
+ * A GAME'S OWN DECISIONS (section 20): typed questions about the game's state that the studio's decision model (Clef)
+ * answers with a probability for every option, never with text. A Choice picks one option id (2 to 26), a yes/no
+ * (`noul`) is true or false, a Score is a level (2 to 10, lowest first; the answer is the probability-weighted level).
+ */
+export type DecideQuestion =
+  | { type: 'choice'; instructions: string; criteria: Record<string, string | null> }
+  | { type: 'noul'; instructions: string; criteria?: { true?: string; false?: string } }
+  | { type: 'score'; instructions: string; criteria: string[] };
+export type DecidePicks = Record<string, string | boolean | number>;
+/**
+ * What `decide` resolves to, always: `by` 'ai' (the studio's Workers AI) or 'local' (the person's own Ollama under dev),
+ * or 'floor' (the game's own answer: no AI, not opted in, over budget, paced, slow, not the host); `why` says which.
+ * `p`: the model's probability for each option (a choice), `{ yes }` (a yes/no), or each level (a score).
+ */
+export interface Decided { by: 'ai' | 'local' | 'floor'; picks: DecidePicks; p?: Record<string, Record<string, number>>; ms: number; why?: string }
+export interface DecideOptions {
+  /** The game's own answer, synchronous: used whenever the model's is not there in time. Missing picks fall back to it one by one. */
+  floor?: (state: unknown) => DecidePicks;
+  /** How long to wait for the model (default 2500 ms; at most 5000). */
+  ms?: number;
+}
+
 export interface Netplay<S = unknown, A = unknown, C = unknown> {
   readonly role: Role;
   readonly isHost: boolean;
@@ -640,6 +665,13 @@ export interface Netplay<S = unknown, A = unknown, C = unknown> {
   /** Interpolation pair for rendering remote entities. */
   sample(delayMs?: number): Sample<S> | null;
   latest(): Snapshot<S> | null;
+  /**
+   * Host: ask the studio's decision model (Clef) a few typed questions about the game's state, for a game whose
+   * game.json says "decide": true. Always resolves: with the model's picks, or the floor's when it cannot answer in
+   * time (no AI, over the day's budget, at most one ask every 3 s a room, a replica, offline). Never per frame: per
+   * beat (every few seconds), and the game keeps playing while it waits.
+   */
+  decide(state: unknown, questions: Record<string, DecideQuestion>, opts?: DecideOptions): Promise<Decided>;
   stats(): NetStats;
   expose(probes: Probes): void;
   close(): void;
@@ -1069,6 +1101,12 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   /** Wall times of the input frames sent in the last second, and until when the slow cap holds. */
   const inSent: number[] = [];
   let inSlowUntil = 0;
+  /** Section 20: decisions waiting for the room's answer (by request id), and how long the room said it is off. */
+  const deciding = new Map<string, { done: (d: Decided) => void; timer: ReturnType<typeof setTimeout>; at: number; floor: () => Decided }>();
+  let decideSeq = 0;
+  let decideOffUntil = 0;
+  let decideNextAt = 0;
+  const decideStats = { asked: 0, ai: 0, local: 0, floor: 0, ms: [] as number[] };
   let idleSkipped = 0;
   /** Why this client stopped for good (a FINAL_ERRORS refusal), or null while it plays or reconnects. */
   let closedWhy: string | null = null;
@@ -1460,6 +1498,29 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
         resolveView('policy');
         return;
       }
+      case 'decided': {
+        const n = String(m['n'] ?? '');
+        const w = deciding.get(n);
+        if (!w) return;
+        deciding.delete(n);
+        clearTimeout(w.timer);
+        const ms = Math.round(wall() - w.at);
+        if (m['ok'] === true && m['picks'] && typeof m['picks'] === 'object') {
+          const base = w.floor();
+          const by = m['by'] === 'local' ? 'local' : 'ai';
+          decideStats[by] += 1;
+          decideStats.ms.push(ms); if (decideStats.ms.length > 40) decideStats.ms.shift();
+          w.done({ by, picks: { ...base.picks, ...(m['picks'] as DecidePicks) }, p: (m['p'] as Decided['p']) ?? {}, ms });
+          return;
+        }
+        const why = String(m['why'] ?? 'error');
+        // Not opted in, no AI or out of budget: ask again only after a minute. Paced: at the room's next slot.
+        if (why === 'off' || why === 'no-ai' || why === 'budget') decideOffUntil = wall() + 60_000;
+        if (why === 'pace' && Number.isFinite(Number(m['retryMs']))) decideNextAt = wall() + Number(m['retryMs']);
+        decideStats.floor += 1;
+        w.done({ ...w.floor(), why, ms });
+        return;
+      }
       case 'error': {
         const code = String(m['code'] ?? '');
         // Inputs over the relay's cap were dropped: send fewer for a while (the newest frame still goes out).
@@ -1748,6 +1809,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       interpDelay: Math.round(interpDelay()), snapAgeP90: Math.round(ageP90), starvedPct: +starvedPct.toFixed(3), rejectedSnaps,
       owned: api.owned, pending: sentHist.length, stateKeys: stateMap.size,
       peers: peers.size, reconnects, promotions, round: roundInfo ? roundInfo.n : null,
+      decides: { asked: decideStats.asked, ai: decideStats.ai, local: decideStats.local, floor: decideStats.floor, msP50: [...decideStats.ms].sort((x, y) => x - y)[Math.floor(decideStats.ms.length / 2)] ?? null },
     };
   }
   function notifyStats(force: boolean): void {
@@ -2185,6 +2247,26 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       return { a: newest, b: newest, alpha: 1, renderT, starved: 0 };
     },
     latest() { return buf.length ? buf[buf.length - 1] as Snapshot<S> : null; },
+    decide(state, questions, o = {}) {
+      const t0 = wall();
+      const floor = (): Decided => {
+        let picks: DecidePicks = {};
+        try { picks = o.floor ? o.floor(state) ?? {} : {}; } catch { picks = {}; }
+        return { by: 'floor', picks, ms: Math.round(wall() - t0) };
+      };
+      decideStats.asked += 1;
+      const now0 = wall();
+      const why = role !== 'host' ? 'not-host' : offline || !connected ? 'offline' : now0 < decideOffUntil ? 'off' : now0 < decideNextAt ? 'pace' : null;
+      if (why) { decideStats.floor += 1; return Promise.resolve({ ...floor(), why }); }
+      decideNextAt = now0 + 3000;
+      const n = `d${(decideSeq += 1).toString(36)}`;
+      return new Promise<Decided>((done) => {
+        const ms = Math.max(200, Math.min(5000, Number(o.ms) || 2500));
+        const timer = setTimeout(() => { if (deciding.delete(n)) { decideStats.floor += 1; done({ ...floor(), why: 'slow' }); } }, ms);
+        deciding.set(n, { done, timer, at: t0, floor });
+        if (!raw({ t: 'decide', n, state, questions })) { deciding.delete(n); clearTimeout(timer); decideStats.floor += 1; done({ ...floor(), why: 'offline' }); }
+      });
+    },
     stats: statsNow,
     expose(p) { probes = { ...probes, ...p }; },
     close() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.24.3",
+  "version": "0.24.5",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/site/SITE.md

@@ -169,6 +169,10 @@ where the game has room, per device:
 - A button at the bottom left sends the "finding a room" chip to the bottom right.
 - On a server, the server's pill sits beside the button, on its inner side in the same band, never under it: on a
   phone held upright it is one more dot; elsewhere its name shows for a few seconds, then it is a dot too.
+- Room chat's Chat pill sits in the same band: a round icon on a phone (either way up) and beside a button kept an
+  icon; on a computer it says "Chat" unless the word would take the band off the screen or into the middle third of
+  its width, where games keep a clock or a title. Its strip of new lines (bottom left by default) moves with
+  `"screen": { "chat": … }`, per device, or stays in the Chat sheet (`"lines": "sheet-only"`): chat/CHAT.md.
 
 Look at the play page on a computer and a phone (both ways up) once a round is on: the button must not sit on a
 score, a timer or a bar. A room code the relay cannot use (1 to 32 letters, digits, `-` or `_`) is refused

package/starters/ember-vale/game.json

@@ -7,6 +7,7 @@
   "entry": "src/main.ts",
   "netplay": { "v": 1, "public": true, "movement": "owner" },
   "saves": true,
+  "decide": false,
   "landing": {
     "pitch": "Your hero keeps every level. The night does not.",
     "howToPlay": [