@homie-rocks/studio 0.24.3 → 0.24.4

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,45 @@
      }
     }
    }
+  },
+  "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"
+      }
+     }
+    }
+   }
   }
  }
 }

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
@@ -1344,3 +1366,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.4",
   "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/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": [

package/starters/ember-vale/src/main.ts

@@ -43,7 +43,7 @@
  * The take "strike" (lab.json) stands a big training slime in front of the hero (lab.stage "dummy"). Outside the lab
  * every lab call is a no-op.
  */
-import { AI_MARK, BUBBLE_FONT, createBubbles, createControls, createLabels, createRoom, paintBubbles, type BubbleIn, type BubbleOut, createSaves, easeView, exposePort, fitView, jitter, q, standoff, stripAi, type BodyBase, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
+import { AI_MARK, BUBBLE_FONT, createBubbles, createControls, createLabels, createRoom, paintBubbles, type BubbleIn, type BubbleOut, createSaves, easeView, exposePort, fitView, jitter, q, standoff, stripAi, type BodyBase, type DecidePicks, type Fit, type LabelIn, type LabelOut, type NetEvent, type Skill } from '@homie-rocks/studio/port';
 import { useAgents, type Goal, type Vocabulary } from '@homie-rocks/studio/agents';
 import vocabulary from '../agents.json';
 // The Game Lab: tunables, phases, tracks and overlays (no-ops outside the lab).
@@ -376,12 +376,66 @@ function stepHost(dt: number): void {
     b.flags = now - b.strikeAt < T.flashMs ? STRIKING : 0;
     if (wants && live && now - b.atkAt > T.strikeMs) strike(b, now);
   }
-  if (live) stepSlimes(dt, now);
+  if (live) { stepDirector(now); stepSlimes(dt, now); }
   // Every browser's ask buttons offer the quests open now (slow keyed state: sent only when it changes).
   net.state('quests', openQuests());
   room.update();
 }
 
+/* ------------------------------------------------------------------ the slimes' director (section 20, opt-in) */
+/**
+ * Every 6 s of a live night the host asks the studio's decision model how the slimes should hunt (`net.decide`: Clef,
+ * three typed questions, never text): a tactic, whether a wave comes now, how hard to push. It runs only when game.json
+ * says "decide": true (the room answers "off" otherwise, and asks are spent from the studio's AI brains' day); without it,
+ * over budget or slow, the floor answers: chase, no wave, steady, which is how the vale always played. On a kids server
+ * the slimes never gang up on the most hurt hero and the vale never pushes past steady. The heroes' dial is untouched:
+ * this is the slimes' mind, not the bots'.
+ */
+type Tactic = 'chase' | 'surround' | 'weakest' | 'regroup';
+const TACTICS: Record<Tactic, string> = {
+  chase: 'Rush the nearest hero',
+  surround: 'Spread out and close in on a hero from every side',
+  weakest: 'Gang up on the most hurt hero',
+  regroup: 'Fall back to the King Slime and gather before the next push',
+};
+/** How often a slime comes, by pressure (0 a breather .. 4 fierce). 1100 ms at 2 is the vale as it always was. */
+const SPAWN_MS = [1900, 1450, 1100, 850, 700];
+const DIRECTOR_MS = 6000;
+const director = { tactic: 'chase' as Tactic, pressure: 2, waveLeft: 0, by: 'floor', at: 0, asking: false, log: [] as Record<string, unknown>[] };
+const directorFloor = (): DecidePicks => ({ tactic: 'chase', wave: false, pressure: 2 });
+function stepDirector(now: number): void {
+  if (!room.hosting || director.asking || now < director.at) return;
+  director.at = now + DIRECTOR_MS;
+  director.asking = true;
+  const kidsRoom = kids();
+  const king = slimes.find((o) => o.size === 3);
+  const heroes = [...room.bodies.values()].filter((b) => !b.bot && b.seat !== null);
+  const state = {
+    heroes: heroes.map((b) => ({ hp: Math.round((100 * b.hp) / Math.max(1, b.maxHp)), down: Boolean(b.flags & DOWN), level: b.level, nearKing: king ? Math.round(Math.hypot(king.x - b.x, king.y - b.y)) : null })),
+    slimes: { count: slimes.length, big: slimes.filter((o) => o.size === 2).length, king: king ? Math.round((100 * king.hp) / king.maxHp) : null },
+    night: { secondsLeft: room.clock().secondsLeft }, now: { tactic: director.tactic, pressure: director.pressure },
+    ...(kidsRoom ? { note: 'Young players: keep it gentle' } : {}),
+  };
+  const tactics = Object.fromEntries(Object.entries(TACTICS).filter(([k]) => !(kidsRoom && k === 'weakest')));
+  const asked = performance.now();
+  void net.decide(state, {
+    tactic: { type: 'choice', instructions: 'How should the slimes hunt the heroes for the next few seconds? A fun fight, not a massacre: hurt heroes deserve a breather.', criteria: tactics },
+    wave: { type: 'noul', instructions: 'Should a wave of extra slimes come now?', criteria: { true: 'The heroes are healthy and it has gone quiet', false: 'The heroes are hurt, down or few' } },
+    pressure: { type: 'score', instructions: 'How hard should the vale push the heroes right now?', criteria: ['A breather', 'Easy', 'Steady', 'Hard', 'Fierce'] },
+  }, { floor: directorFloor }).then((d) => {
+    director.asking = false;
+    const t = String(d.picks['tactic'] ?? 'chase') as Tactic;
+    director.tactic = t in tactics ? t : 'chase';
+    director.pressure = clamp(Math.round(Number(d.picks['pressure'] ?? 2)), 0, kidsRoom ? 2 : 4);
+    if (d.picks['wave'] === true && director.waveLeft === 0) director.waveLeft = 3;
+    director.by = d.by;
+    director.log.push({ at: Date.now(), by: d.by, why: d.why ?? null, ms: Math.round(performance.now() - asked), tactic: director.tactic, pressure: director.pressure, wave: d.picks['wave'] === true });
+    if (director.log.length > 40) director.log.shift();
+    // Every screen sees what the slimes are up to (only when a model decided; the floor is the vale as always).
+    net.state('slimes', d.by === 'floor' ? null : { tactic: director.tactic, pressure: director.pressure });
+  });
+}
+
 /* ------------------------------------------------------------------ the guides' hands */
 const bodyOfSeat = (seat: unknown): Body | null => { for (const o of room.bodies.values()) if (!o.bot && o.seat === seat) return o; return null; };
 const people = (): Body[] => [...room.bodies.values()].filter((o) => !o.bot && o.seat !== null && !(o.flags & DOWN));
@@ -498,8 +552,11 @@ function stepSlimes(dt: number, now: number): void {
   if (lab.stage === 'dummy') return; // the lab's training slime stands still and never bites
   const bodies = [...room.bodies.values()].filter((b) => !(b.flags & DOWN));
   const people = bodies.filter((b) => !b.bot).length;
-  if (now >= spawnAt && slimes.length < 6 + people * 2) {
-    spawnAt = now + 1100;
+  // The director's pressure (0 a breather .. 4 fierce; 2 is how the vale always played) sets how fast and how many.
+  const cap = Math.max(4, 6 + people * 2 + (director.pressure - 2) * 2) + (director.waveLeft > 0 ? 3 : 0);
+  if ((now >= spawnAt || director.waveLeft > 0) && slimes.length < cap) {
+    spawnAt = now + SPAWN_MS[director.pressure]!;
+    if (director.waveLeft > 0) director.waveLeft -= 1;
     const edge = Math.floor(Math.random() * 4);
     const x = edge === 0 ? 30 : edge === 1 ? W - 30 : Math.random() * W;
     const y = edge === 2 ? 30 : edge === 3 ? H - 30 : Math.random() * H;
@@ -517,10 +574,18 @@ function stepSlimes(dt: number, now: number): void {
     if (struck.has(s.id)) continue;
     let target: Body | null = null; let bd = Infinity;
     for (const b of prey) { const d = Math.hypot(b.x - s.x, b.y - s.y); if (d < bd) { bd = d; target = b; } }
+    // The director's tactic (section 20; chase is how the vale always played): the most hurt hero, a ring round the
+    // nearest, or back to the King to gather (a hero close by is still bitten).
+    if (director.tactic === 'weakest' && prey.length > 1) target = prey.reduce((a, b) => (b.hp / b.maxHp < a.hp / a.maxHp ? b : a));
     const speed = s.size === 3 ? 70 : 95 - s.size * 10;
     if (target) {
-      const dx = target.x - s.x; const dy = target.y - s.y; const dist = Math.hypot(dx, dy) || 1;
-      s.x += (dx / dist) * speed * dt; s.y += (dy / dist) * speed * dt;
+      let gx = target.x; let gy = target.y;
+      const king = slimes.find((o) => o.size === 3);
+      if (director.tactic === 'surround' && bd > 90) { const a = s.id * 2.39996; gx += Math.cos(a) * 80; gy += Math.sin(a) * 80; }
+      if (director.tactic === 'regroup' && king && s !== king && bd > 140) { gx = king.x + Math.cos(s.id) * 70; gy = king.y + Math.sin(s.id) * 70; }
+      const dx = gx - s.x; const dy = gy - s.y; const dist = Math.hypot(target.x - s.x, target.y - s.y) || 1;
+      const step = Math.hypot(dx, dy) || 1;
+      if (step > 4) { s.x += (dx / step) * speed * dt; s.y += (dy / step) * speed * dt; }
       if (dist < R + 10 + s.size * 10 && now - s.hitAt > 800) {
         s.hitAt = now;
         target.hp -= 5 * s.size + (s.size === 3 ? 10 : 0);
@@ -919,6 +984,13 @@ function hud(t: number): void {
   // Top centre; on a narrow screen where that would touch the panel, just under it.
   if (x0 + pw + 10 > cw / 2 - ctx.measureText(clock).width / 2) { ctx.textAlign = 'left'; ctx.fillText(clock, x0 + 10, y0 + 62 + 20); }
   else { ctx.textAlign = 'center'; ctx.fillText(clock, cw / 2, 30); }
+  // What the slimes are up to, when the studio's decision model chose it (section 20; nothing shows on the floor).
+  const mind = c.phase === 'live' ? net.stateOf<{ tactic: string; pressure: number }>('slimes') : null;
+  if (mind) {
+    const words: Record<string, string> = { chase: 'rushing you', surround: 'closing in from every side', weakest: 'hunting the hurt', regroup: 'gathering round the King' };
+    ctx.font = SMALL; ctx.fillStyle = '#e7a86b'; ctx.textAlign = 'center';
+    ctx.fillText(`Slimes: ${words[mind.tactic] ?? mind.tactic}`, cw / 2, x0 + pw + 10 > cw / 2 - 80 ? y0 + 62 + 40 : 50);
+  }
   ctx.textAlign = 'center';
   if (c.phase === 'over') {
     const rows = room.results().slice(0, 5);
@@ -1144,6 +1216,8 @@ net.expose({
     me: me.has ? { x: Math.round(me.x), y: me.y | 0 } : null,
     log: guideLog.slice(),
   }),
+  // The slimes' director (section 20): its tactic now, and each decision (who answered, how long it took).
+  director: () => ({ tactic: director.tactic, pressure: director.pressure, by: director.by, log: director.log.slice(), net: net.stats().decides ?? null }),
   // Where the camera looks, and the names as drawn (the e2e probe counts overlaps, checks your own, and reads them).
   camera: () => (cam ? { x: cam.x, y: cam.y, scale: cam.scale, follow: cam.follow } : null),
   labels: () => shownLabels.map((l) => ({ text: l.text, self: Boolean(l.self), alpha: l.alpha, moved: l.moved, left: Math.round(l.left), top: Math.round(l.top), right: Math.round(l.right), bottom: Math.round(l.bottom) })),