@homie-rocks/studio 0.16.0 → 0.17.0

package/lib/servers.mjs

@@ -14,14 +14,23 @@
  *   homie-studio agents pass <game|any> --label "<Name>" [--server <id>] [--hands self|host] [--role party|guide|player] [--days 7]
  *   homie-studio agents passes [<game>]                  every pass (never a secret)
  *   homie-studio agents revoke <pass id>
- *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key
+ *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key [--budget <neurons a day | dollars a day>]
+ *   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)
  *
  * 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
  * change that narrows who may come in, closing a server, removing a member, and the first time AI guides may talk are
  * only ASKED for: the answer is a one-time link that opens the ask in the owner's own browser (one tap does it).
  */
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
 import { askedFor, withKey } from './office.mjs';
+import { runner } from './cloudflare.mjs';
+import { readStudio } from './studio.mjs';
 
 const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const SERVER = /^[a-z0-9][a-z0-9-]{1,19}$/;
@@ -111,12 +120,65 @@ export async function agentsRevoke(root, id, { url } = {}) {
   return r.ok ? { ok: true, command: 'agents revoke', revoked: id, left: r.left ?? 0, message: `Pass ${id} revoked${r.left ? `: its AI left ${r.left} room(s)` : ''}.` } : { ok: false, command: 'agents revoke', why: r.message ?? r.why };
 }
 
-export async function agentsBrain(root, game, server, mode, { url } = {}) {
-  if (!GAME.test(String(game ?? '')) || !server || !['off', 'script', 'workers-ai', 'owner-key'].includes(mode)) return { ok: false, command: 'agents brain', why: 'usage: homie-studio agents brain <game> <server> off|script|workers-ai|owner-key' };
-  const r = await withKey(root, url, (call) => call('/_studio/api/agents/brain', { game, server, mode }));
+export async function agentsBrain(root, game, server, mode, { url, budget } = {}) {
+  if (!GAME.test(String(game ?? '')) || !server || !['off', 'script', 'workers-ai', 'owner-key'].includes(mode)) return { ok: false, command: 'agents brain', why: 'usage: homie-studio agents brain <game> <server> off|script|workers-ai|owner-key [--budget <neurons a day for workers-ai | dollars a day for owner-key>]' };
+  const b = budget === undefined || budget === true ? undefined : Number(budget);
+  if (b !== undefined && !(b >= 0)) return { ok: false, command: 'agents brain', why: '--budget is a number: Workers AI neurons a day (workers-ai; the free allocation is 10,000 an account), or dollars a day (owner-key)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/brain', { game, server, mode, ...(b !== undefined ? { budget: b } : {}) }));
   return askedFor(root, url, r, 'agents brain');
 }
 
+/**
+ * `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
+ * HOMIE_BRAIN_KEY` on its standard input. It never passes through a chat, a file, an argument or a log, and this
+ * command never prints it. `--remove` deletes the secret.
+ */
+export async function agentsBrainKey(root, { remove = false, log = () => {}, port = 0, wait = 10 * 60_000 } = {}) {
+  const studio = readStudio(root);
+  const env = studio.cloudflare?.accountId ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {};
+  const w = runner(root, env);
+  if (remove) {
+    const r = w(['secret', 'delete', 'HOMIE_BRAIN_KEY'], { input: 'y\n' });
+    return r.code === 0 ? { ok: true, command: 'agents brain key', removed: true, message: 'The key is gone from the Worker: owner-key guides answer from the game\'s script.' } : { ok: false, command: 'agents brain key', why: r.out.trim().split('\n').slice(-2).join(' ') };
+  }
+  const nonce = randomBytes(16).toString('hex');
+  const page = `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Your AI key</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:34rem;margin:3rem auto;padding:0 1rem;color:#1b1b1b}input{width:100%;box-sizing:border-box;font:inherit;padding:.6rem;border:1px solid #999;border-radius:8px}button{margin-top:1rem;font:inherit;font-weight:700;padding:.6rem 1.2rem;border:0;border-radius:8px;background:#1b1b1b;color:#fff}small{color:#555}</style>
+<h1>Your AI key for the guides</h1><p>Paste your Anthropic API key. It goes from this page to your studio's Worker as the secret <code>HOMIE_BRAIN_KEY</code>, and nowhere else: not to the chat, not to a file. Your guides then think with claude-haiku-4-5, on your account, within the daily dollar cap in your office.</p>
+<form method="post" action="/key"><input type="hidden" name="n" value="${nonce}"><input name="key" type="password" autocomplete="off" placeholder="sk-ant-…" required><button>Save to my Worker</button></form><p><small>This page works once and closes in ten minutes.</small></p>`;
+  return await new Promise((done) => {
+    let finished = false;
+    const server = createServer((req, res) => {
+      if (req.method === 'GET' && req.url === `/${nonce}`) { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }); res.end(page); return; }
+      if (req.method === 'POST' && req.url === '/key') {
+        let body = '';
+        req.on('data', (c) => { body += c; if (body.length > 4096) req.destroy(); });
+        req.on('end', () => {
+          const form = new URLSearchParams(body);
+          const key = String(form.get('key') ?? '').trim();
+          if (form.get('n') !== nonce || finished) { res.writeHead(403); res.end('This page was used already.'); return; }
+          if (!/^sk-ant-[A-Za-z0-9_-]{20,}$/.test(key)) { res.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' }); res.end('That does not look like an Anthropic API key (sk-ant-…). Go back and try again.'); return; }
+          finished = true;
+          const r = w(['secret', 'put', 'HOMIE_BRAIN_KEY'], { input: `${key}\n` });
+          const okay = r.code === 0;
+          res.writeHead(okay ? 200 : 500, { 'content-type': 'text/plain; charset=utf-8' });
+          res.end(okay ? 'Saved to your Worker. You can close this page.' : 'Wrangler could not save it (is this computer signed in to Cloudflare? npx wrangler login). Nothing was kept.');
+          server.close();
+          done(okay ? { ok: true, command: 'agents brain key', saved: true, message: 'Saved as the Worker secret HOMIE_BRAIN_KEY (never shown). Owner-key guides use it from their next decision.' } : { ok: false, command: 'agents brain key', why: 'wrangler secret put failed (sign in with npx wrangler login, then run this again)' });
+        });
+        return;
+      }
+      res.writeHead(404); res.end();
+    });
+    server.listen(port, '127.0.0.1', () => {
+      const link = `http://127.0.0.1:${server.address().port}/${nonce}`;
+      log(`Open this page on this computer and paste the key there (not in a chat): ${link}`);
+    });
+    setTimeout(() => { if (!finished) { finished = true; server.close(); done({ ok: false, command: 'agents brain key', why: 'nothing was saved in ten minutes; run it again when ready' }); } }, wait).unref?.();
+  });
+}
+
 /** One line per server for a person (the CLI's print). */
 export function serversLines(r) {
   const lines = [];

package/lib/template-history.json

@@ -462,6 +462,62 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.16.1": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "e579cd6ce3ce342a",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "961ac5e8ccc2a548",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.17.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "e579cd6ce3ce342a",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/netplay/NETPLAY.md

@@ -1,10 +1,28 @@
-# Homie netplay contract, v1 (revision 6)
+# Homie netplay contract, v1 (revision 7)
 
-Status: **v1, revision 6** (2026-10-01, `@homie-rocks/studio` 0.16.0). The wire version is
-`v: 1`. Everything revisions 2 to 6 added is either an optional field, a new message type,
+Status: **v1, revision 7** (2026-10-02, `@homie-rocks/studio` 0.17.0). The wire version is
+`v: 1`. Everything revisions 2 to 7 added is either an optional field, a new message type,
 a new refusal, or a change of pace inside the old caps, and both sides ignore types they do
 not know. A change to the contract bumps `v` and keeps v1 working.
 
+**What revision 7 added** (a game that knows none of it plays on every server; its AI guide
+seats are the game's own bots, silent):
+- **Agent hands and brains** (section 18): an AI with no game client of its own (hands
+  `host`) sees the game through `agent:view` events its host sends that seat (at most one
+  every 2 s, under 2 KB) and moves through `agent:do` goals (at most one every 3 s). It
+  speaks only `say:<lineId>` lines of the game's own vocabulary (`agents.json`), with typed
+  arguments, and only on a server whose AI may talk (the owner's `agents_brain`). The relay
+  checks every one of those again and drops anything else an AI says.
+- **The lite feed** carries the party's `say:`/`emote:` lines (free `chat` only on a
+  `speech: game` server) and an `ask:<id>` a person made of that AI.
+- **House guides**: on a beginner server whose AI may talk, the room's own Table seats the
+  server's guides as loopback peers, with brains that run on Durable Object alarms (Workers
+  AI or the owner's own key), and the scripted floor when there is no AI.
+- `@homie-rocks/studio/agents` (`useAgents`): the host's side (views, the floor, goals for
+  the hands, lines rendered from `agents.json`) and every browser's asks and lines.
+- `NETPLAY_REVISION` 7 and the build mark `homie-netplay-rev:7`; Quiet AI also hides a line a
+  host relays for an AI (`d.ai`).
+
 **What revision 6 added** (a v1 game that knows none of it plays on every server; its AI
 is labelled by name, its people are capped, and its play page shows no vote):
 - **Servers and agent seats** (section 17): a server is a named, lasting pool of rooms with
@@ -76,6 +94,9 @@ the notices and the banner):
 | `worker/room.mjs` | The relay's rules, with no transport. It needs no Node built-ins. |
 | `worker/index.mjs` | The studio's site Worker: `room.mjs` inside the `Table` Durable Object, and the `Lobby` that puts strangers in the same public room. `homie-studio dev` runs the same code under `wrangler dev`. |
 | `starters/gem-rush/` | Gem Rush, the reference game (canvas, about 700 lines). It has both movement modes. |
+| `agents/agents.ts` | `useAgents`, the AI guides' host side and every browser's asks and lines (section 18), imported as `@homie-rocks/studio/agents`. |
+| `worker/brain.mjs` | The vocabulary, prompts, `parseDecision`, the scripted floor and the providers (section 18). |
+| `starters/ember-vale/` | Ember Vale: saves (a hero that lasts), and the AI guides' reference (`agents.json`, section 18). |
 
 ---
 
@@ -1000,6 +1021,136 @@ age is ever asked.
 **Cost.** An agent is one more socket, like a phone. Agents never keep a room alive (60 s
 alone at most). A lite agent gets no snapshots, so it costs a few frames a minute.
 
-**Revision 7 (a later version)** adds an AI's brain: hands in the host (`agent:view`,
-`agent:do`), lines only from the game's own `agents.json` vocabulary (`say:<lineId>`, checked
-by the relay), and guides that answer the party. Nothing in revision 6 needs to change for it.
+**Revision 7** (section 18) adds an AI's brain: hands in the host (`agent:view`, `agent:do`),
+lines only from the game's own `agents.json` vocabulary (`say:<lineId>`, checked by the relay),
+and guides that answer the party. Nothing in revision 6 changed for it.
+
+---
+
+## 18. Agent hands and brains (revision 7)
+
+An AI guide has two layers. Its **hands** are the game's own bot code, in the host, every
+frame, at the dial the party agreed: they walk to the goal and do what it says. Its **brain**
+picks a goal every few seconds and, when the server lets its AI talk, one line to say. The
+brain never runs in the frame loop, and it can only choose: goals and lines are ids from the
+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.
+
+### The vocabulary: `games/<id>/agents.json`
+
+The only words an AI in the game's rooms has. `homie-studio build` checks it (an unknown
+argument type, a text over 120 characters, a `{placeholder}` that is not an argument, a goal
+aimed at a player, an ask naming a goal or line that is not there: the build stops) and serves
+it at `/games/<id>/agents.json`, where the Table reads it once.
+
+```json
+{ "v": 1,
+  "persona": "A patient guide for new heroes in Ember Vale. Short, kind, never sarcastic.",
+  "names": ["Wren", "Ash", "Moss"],
+  "labels": { "king-slime": "King Slime", "camp": "camp", "king": "the King's hill" },
+  "goals": {
+    "follow": { "about": "stay with a player", "args": { "seat": "player" } },
+    "quest":  { "about": "do a quest with the party", "args": { "quest": "view.quests" } },
+    "lead":   { "about": "lead the party to a place", "args": { "place": ["camp", "king", "east-woods"] } },
+    "guard":  { "about": "hold here and protect the party" },
+    "back":   { "about": "pull back to safety at camp" } },
+  "lines": {
+    "hello":      { "text": "Hi {player}! I'm {me}, an AI guide. Tap me if you want help.", "args": { "player": "player" } },
+    "quest_help": { "text": "Let's take on {quest} together.", "args": { "quest": "view.quests" } },
+    "bye":        { "text": "Okay! I'll give you some space." } },
+  "asks": {
+    "ask_help":  { "text": "Help me with {quest}", "args": { "quest": "view.quests" }, "goal": "quest", "say": "quest_help" },
+    "no_thanks": { "text": "No thanks", "goal": "back", "say": "bye", "leave": true } } }
+```
+
+| Field | Meaning |
+|---|---|
+| `persona` | Up to 400 characters: who the guide is, in the game's own voice. The system prompt starts with it. |
+| `names` | Up to 8 names (16 characters each); a guide plays as `<name> · AI`. |
+| `labels` | How a value reads aloud (`king-slime` → "King Slime"); else its dashes become spaces. |
+| `goals` | Up to 16: `about` (what it is, 80 characters) and `args`. A goal with a `player` argument means *with or near* that player; one that reads as acting against a player is refused. |
+| `lines` | Up to 32: `text` (120 characters; `{arg}` and `{me}` placeholders) and `args`. |
+| `asks` | Up to 8 buttons a game draws for a person: `text`, `args`, and how the scripted floor answers (`goal`, `say`: arguments carry over by name, a `player` argument is the asker). `leave: true` is "no thanks": the guide leaves that player alone for 10 minutes. |
+| argument types | `"player"` (a seat in the room, drawn with the room's name for it), a list of values, or `"view.<key>"` (a value present in the AI's latest `agent:view`). |
+
+### Frames (all `ev`, with the relay's checks)
+
+| `k` | From → to | `d` | The relay |
+|---|---|---|---|
+| `agent:view` | host → one AI's seat (`to: seat`) | the game's view of that guide (below) | Only the host, only to an AI's seat, under 2 KB, at most one every 2 s per AI; kept as that AI's latest view. |
+| `agent:do` | AI → host | `{ goal, args }` | A goal of the vocabulary whose arguments fit the AI's latest view and the seats people hold; at most one every 3 s. |
+| `say:<lineId>` | AI → host | `{ args }` | A line of the vocabulary with fitting arguments, on a server whose AI may talk (`policy.brain` is `workers-ai` or `owner-key`), at most one every 4 s and 8 a minute. The host renders it and relays it to everyone as `say:<lineId>` `{ slot, seat, args, ai: true }`, which the relay checks again (a line of the vocabulary; a view argument from the speaking AI's latest view, or only an id for a guide no AI holds): a host cannot put its own words in an AI's line. |
+| `ask:<askId>` | a person → host | `{ slot, seat, args }` | Copied to the AI in `seat` (an ask id of the vocabulary). |
+| anything else from an AI with no game client, `chat`, `emote`, `agent:view` | | | Dropped and counted (`stats.agentDrops`). An AI never types. |
+
+The lite feed (hands `host`) carries `join`/`leave`, `roster`, `round`, `policy`, `vote`, events
+addressed to its seat, the party's `say:`/`emote:` lines (`chat` only on a `speech: game`
+server), and the asks made of it; never `snap`, `ckpt` or `state`.
+
+### The host's side: `@homie-rocks/studio/agents`
+
+```ts
+import vocab from '../agents.json';
+import { useAgents, type Vocabulary } from '@homie-rocks/studio/agents';
+
+const agents = useAgents(room.net, vocab as unknown as Vocabulary, {
+  // Host: what a guide sees (<= 1 per 2 s, < 2 KB). Game state only: never an account, an address or typed text.
+  view: (slot) => ({ me: bodyView(slot), zone: zoneOf(slot), danger: dangerNear(slot), party: partyNear(slot), quests: openQuests() }),
+  // The scripted floor: runs with no AI, over budget, and between AI decisions. Synchronous; never waits.
+  decide: (v) => v.asks?.[0]?.k === 'ask_help' ? { goal: 'quest', args: { quest: v.asks[0].args.quest }, say: 'quest_help', sayArgs: { quest: v.asks[0].args.quest } }
+             : { goal: 'follow', args: { seat: v.party[0]?.seat } },
+});
+// Hands, every host frame: the goal in force at the party's dial. Never awaits a brain.
+for (const b of room.bodies.values()) { const g = b.agent?.role === 'guide' ? agents.goalOf(b.slot) : null; if (g) steerTo(b, g, room.skillOf(b), dt); }
+agents.done(slot, true);                                   // that goal finished: the brain thinks again
+agents.on('say', ({ slot, text }) => bubble(slot, text));  // a guide's line, from agents.json
+agents.ask(slot, 'ask_help', { quest: 'king-slime' });     // a person's button (agents.askButtons(slot, offer))
+```
+
+| Call | Meaning |
+|---|---|
+| `useAgents(net, vocab, { view, decide, roles?, holdMs?, askWaitMs? })` | Every browser. On the host: sends each AI-held guide its view every 2 s, runs the floor for the rest (once a second), takes `agent:do` and AI lines, answers asks. |
+| `goalOf(slot)` | `{ goal, args, from: 'brain' \| 'floor', at, state, asked? }` or null (the game's own bot code drives). An AI's decision holds for `holdMs` (45 s) or until it is done; a goal that answered a person's ask (`asked`) is carried through until done (or 60 s), whatever a brain says. A brain's decision that does not answer an open ask leaves it open, and the floor answers it after `askWaitMs`. |
+| `done(slot, ok?)` | The goal finished (or failed): the next view says so (a brain thinks again); a guide no AI holds decides at once. |
+| `ask(slot, k, args)`, `askButtons(slot, offer)`, `asksFor(slot)` | A person's ask (a button); the buttons to draw (one per value its argument may take); the asks made of a guide in the last 30 s. An ask of a held guide waits `askWaitMs` (4 s) for its brain, then the floor answers it. |
+| `on('say' \| 'goal' \| 'ask', fn)` | A guide's line (text from the vocabulary; never on a browser with Quiet AI on), a goal change (with `askAt`, the ask that led to it), an ask. |
+| `talking`, `render(id, args, slot)`, `stats()`, `stop()` | Whether the server's AI may talk; a line's text; counters. |
+
+A view adds `goal` (`{ goal, args, state }`) and `asks` itself. The brain also thinks again when
+the view's `zone` or `danger` changes.
+
+### House guides and their brains
+
+On a beginner server whose AI may talk, with a vocabulary, a person seated and a host whose game
+moves AI bodies (`caps: ['agents']`), the Table seats `guides` house guides: loopback peers with
+hands `host`, role `guide`, named from `names`. They are agents like any other: never players,
+never hosts, closed 60 s after the last person, held out by a kick, silent when muted. An AI
+with a pass (the owner's own Claude) takes a guide's seat from a house guide (`agent-yield`).
+
+| Rule | Value |
+|---|---|
+| A decision | 0.8 s after an ask of this guide; at once on a goal done or failed, a `zone` or `danger` change; else every 12 s while people are near (the view's `party`). |
+| 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. |
+| 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. |
+
+**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.
+
+**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
+text ever reaches a brain. The owner's controls work on AI, and "AI talk off" (agents_brain
+`script`) silences every AI at once. Quiet AI hides every AI line on a player's own screen.
+

package/netplay/netplay.ts

@@ -39,6 +39,11 @@
  *     an AI's seat is marked (`peer.agent`, `net.isAgent(seat)`, every name
  *     ends in " · AI"); `Roster` keeps a hybrid server's AI seats; `net.hushed`
  *     is the player's "Quiet AI".
+ *   - Agent hands and brains (revision 7, NETPLAY.md section 18): an AI with no
+ *     game client of its own sees the game through `agent:view` events the host
+ *     sends its seat and moves through `agent:do` goals; it speaks only the
+ *     game's `agents.json` lines (`say:<lineId>`). `@homie-rocks/studio/agents`
+ *     (`useAgents`) is the host's side of it; this file only carries the frames.
  *
  * WHAT IT DOES NOT DO: rendering, physics, input devices, bots. `Roster` below
  * is the bot-yield bookkeeping a host needs; the bots themselves are the game's.
@@ -47,9 +52,9 @@
 
 export const NETPLAY_VERSION = 1;
 /** The contract revision this helper speaks (NETPLAY.md): its hello says so (`rev`), and so does every build of it. */
-export const NETPLAY_REVISION = 6;
+export const NETPLAY_REVISION = 7;
 /** In every bundle that includes the helper: `homie-studio build` reads it to tell the office which revision a build speaks. */
-export const NETPLAY_MARK = 'homie-netplay-rev:6';
+export const NETPLAY_MARK = 'homie-netplay-rev:7';
 
 export type Role = 'host' | 'replica' | 'screen';
 export type Device = 'phone' | 'desk' | 'tv';
@@ -1235,8 +1240,9 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       case 'ev': {
         const k = String(m['k'] ?? '');
         const from = typeof m['from'] === 'number' ? m['from'] : null;
-        // Quiet AI (section 17): this browser does not hear an AI's speech.
-        if (hushed && SPEECH_KIND.test(k) && from !== null && api.isAgent(from)) return;
+        // Quiet AI (section 17): this browser does not hear an AI's speech, its own or relayed by the host (section 18:
+        // a host relays an AI's line with `d.ai`).
+        if (hushed && SPEECH_KIND.test(k) && ((from !== null && api.isAgent(from)) || (m['d'] && typeof m['d'] === 'object' && (m['d'] as { ai?: unknown }).ai === true))) return;
         emit('event', { k, d: m['d'], from, ...(typeof m['id'] === 'string' ? { id: m['id'] } : {}) });
         return;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "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, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,6 +30,10 @@
       "types": "./saves/saves.ts",
       "default": "./saves/saves.ts"
     },
+    "./agents": {
+      "types": "./agents/agents.ts",
+      "default": "./agents/agents.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -41,6 +45,7 @@
     "worker/",
     "mcp/",
     "saves/",
+    "agents/",
     "starters/",
     "media/",
     "site/",
@@ -52,6 +57,7 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "0.131.0",
     "esbuild": "0.28.1",
     "puppeteer-core": "25.8.0"
   },

package/site/SITE.md

@@ -157,6 +157,8 @@ where the game has room, per device:
 - It shows the room's name ("Room 7") for a few seconds, then shrinks to a round icon until it is touched;
   `"label": false` keeps it the icon always (the code is in its sheet), for a corner with little room.
 - 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.
 
 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
@@ -219,17 +221,27 @@ its **Quick play** server (`public`), so every old link keeps working.
   the same door, except that watching a beginner room needs no new account.
 - **When the owner hides Quick play** (`homie-studio servers close <id> public`), Play shows the servers to pick
   from, and a named `?room=` is off (except for the owner).
-- **The play shell** on a server: a pill beside the room button ("First Light · Beginner"; tap: the policy's line,
-  "AI level: Steady" with **Change** when the game's bots read the dial, and **Quiet AI**, which hides AI chat on
-  this screen only); the chip says "4 playing · 2 AI"; every AI row and result carries an AI pill.
+- **The play shell** on a server: a pill beside the room button, in the same band at the room button's place
+  (`screen.share`), never under it ("First Light · Beginner", then a dot after a few seconds; on a phone held
+  upright, the dot from the start; tap: the server's name, the policy's line, "AI level: Steady" with **Change**
+  when the game's bots read the dial, and **Quiet AI**, which hides AI chat on this screen only). A server room's
+  button says "Room 2", as Quick play's does. The chip says "First Light · 4 playing · 2 AI"; every AI row and result
+  carries an AI pill. A game's HUD keeps that band clear (Gem Rush starts its scores under it).
 - **The vote card** ("How strong should the AI be?", five levels, "the middle vote wins") opens by itself at a
   party's first round with AI seats, from the pill's Change, or from the game; a lone player's tap decides at once,
-  every seated person's vote closes it early, else 15 s. Keys 1-5 on a computer; a bottom sheet on a phone. The
+  every seated person's vote closes it early, else 15 s. Keys 1-5 on a computer; a bottom sheet on a phone. The card
+  is opaque: nothing of the game shows through it. The
   result is a toast ("The party set the AI to Steady (3 votes)."). A game that draws its own card says game.json
   `"agents": { "vote": "game" }` (`false`: none).
 - `/<id>/api/servers` is the servers with their live counts (cacheable 15 s). `/api/rooms` rows say their
   `server`, `policy` and `ai`.
 
+**AI guides that talk** (0.17.0, `netplay/NETPLAY.md` section 18): a guide's line is the game's own text
+(its `agents.json`), drawn by the game (Ember Vale: a bubble over the guide); **Quiet AI** hides it on that
+screen. Asking a guide is buttons the game draws, never a text box. The page itself adds nothing for guides.
+The office shows each server's brain, today's Workers AI neurons or dollars against the day's budget, and each
+room's last guide decisions (seats and ids only).
+
 **An AI's seat** (an agent pass from `homie-studio agents pass`): `POST /<id>/api/agent` with `Authorization:
 Bearer <pass>` and `{ "server": "<id>" }` answers a room with people in it (never an empty one), a ticket, its
 socket and (an AI that runs the game itself) the frame to load. A humans-only server answers 403 "This server is

package/starters/ember-vale/agents.json

@@ -0,0 +1,34 @@
+{
+  "v": 1,
+  "persona": "A patient guide for new heroes in Ember Vale. Short, kind, never sarcastic. You help a hero find their feet: you stay close, you point the way, and you take on the hard fights with them.",
+  "names": ["Wren", "Ash", "Moss"],
+  "labels": {
+    "king-slime": "King Slime",
+    "slime-hunt": "a slime hunt",
+    "big-slime": "the big slime",
+    "camp": "camp",
+    "king": "the King's hill",
+    "east-woods": "the east woods"
+  },
+  "goals": {
+    "follow": { "about": "stay with a player", "args": { "seat": "player" } },
+    "quest": { "about": "do a quest with the party", "args": { "quest": "view.quests" } },
+    "lead": { "about": "lead the party to a place", "args": { "place": ["camp", "king", "east-woods"] } },
+    "guard": { "about": "hold here and protect the party" },
+    "back": { "about": "pull back to safety at camp" }
+  },
+  "lines": {
+    "hello": { "text": "Hi {player}! I'm {me}, an AI guide. Tap me if you want help.", "args": { "player": "player" } },
+    "follow_me": { "text": "Follow me to {place}!", "args": { "place": ["camp", "king", "east-woods"] } },
+    "quest_help": { "text": "Let's take on {quest} together.", "args": { "quest": "view.quests" } },
+    "careful": { "text": "Careful, {thing} ahead!", "args": { "thing": ["slimes", "the King Slime"] } },
+    "nice": { "text": "Nice strike, {player}!", "args": { "player": "player" } },
+    "wait": { "text": "I'll wait here for you." },
+    "bye": { "text": "Okay! I'll give you some space." }
+  },
+  "asks": {
+    "ask_help": { "text": "Help me with {quest}", "args": { "quest": "view.quests" }, "goal": "quest", "say": "quest_help" },
+    "lead_me": { "text": "Take me to {place}", "args": { "place": ["camp", "king", "east-woods"] }, "goal": "lead", "say": "follow_me" },
+    "no_thanks": { "text": "No thanks", "goal": "back", "say": "bye", "leave": true }
+  }
+}

package/starters/ember-vale/index.html

@@ -21,12 +21,20 @@
   .panel li { margin: 4px 0; color: #e7d9b4; }
   .panel li small { color: #a39a80; }
   .panel .close { float: right; background: none; border: 0; color: #c9c0a6; font-size: 20px; cursor: pointer; }
+  /* Asking a guide: buttons (agents.json "asks"), never a text box. Bottom centre, clear of the stick and STRIKE. */
+  .asks { left: 50%; transform: translateX(-50%); bottom: calc(14px + env(safe-area-inset-bottom)); max-width: min(560px, calc(100vw - 200px)); box-sizing: border-box; padding: 8px 10px; border-radius: 14px; background: rgba(10,20,18,.84); border: 1px solid rgba(127,216,200,.45); text-align: center; }
+  .asks .who { font: 700 12.5px/1.2 inherit; font-family: inherit; color: #7fd8c8; margin: 0 0 6px; }
+  .asks .list { display: flex; flex-wrap: wrap; gap: 6px; justify-content: center; }
+  .asks button { min-height: 34px; padding: 0 12px; border-radius: 999px; border: 1px solid rgba(127,216,200,.5); background: rgba(127,216,200,.12); color: #e9fff9; font: 600 13px/1 inherit; font-family: inherit; cursor: pointer; }
+  .asks button.sent { background: #7fd8c8; color: #0b1512; }
+  @media (max-width: 540px) { .asks { max-width: calc(100vw - 168px); bottom: calc(10px + env(safe-area-inset-bottom)); } .asks button { min-height: 40px; padding: 0 10px; } }
   [hidden] { display: none !important; }
 </style>
 </head>
 <body>
 <canvas id="c"></canvas>
 <div class="ui pill"><button type="button" id="who"></button><button type="button" id="hall-btn">Hall of the Fallen</button></div>
+<div class="ui asks" id="asks" hidden aria-live="polite"><p class="who" id="asks-who"></p><div class="list" id="asks-list"></div></div>
 <div class="ui panel" id="make" hidden>
   <h2>A new hero</h2>
   <p>Your hero keeps every level and coin, on every device you play on.</p>