@homie-rocks/studio 0.24.2 → 0.24.4

package/worker/chat.mjs

@@ -14,12 +14,15 @@
  *               links, swears, and the studio's own words. It always runs, and it needs nothing.
  *   review      typed text the floor let through, on the studio's own Workers AI: Cloudflare's Clef decision model
  *               (`@cf/cloudflare/clef-flash`, launched 2026-10-01: a probability for each answer, about 40 ms), within a
- *               day's budget of neurons. No binding, no budget left or an error: the floor alone decides.
+ *               day's budget of neurons. Under `homie-studio dev` with no binding, the same questions go to the person's
+ *               own Ollama (clef-flash) when dev found it there: free. No model, no budget left or an error: the floor
+ *               alone decides.
  *
  * Emoji and quick lines are the studio's own words: they never need a review, so they reach every screen at once.
  * NOTHING is stored here: the relay keeps a short window in memory (section 19), and a report keeps only the message.
  */
 import { WORDS_B64 } from './chat-words.mjs';
+import { clefRun, localAiOf } from './brain.mjs';
 
 export const CHAT_MODES = Object.freeze(['off', 'emoji', 'lines', 'text']);
 export const CHAT_WHO = Object.freeze(['anyone', 'signed-in', 'members']);
@@ -387,9 +390,11 @@ const timeout = (p, ms) => Promise.race([p, new Promise((_, no) => setTimeout(()
  * (`why` is the most likely other answer). Throws when there is no binding, the model fails or it takes too long:
  * the caller lets the floor decide.
  */
-export async function reviewChat(env, text, { model = env?.HOMIE_CHAT_MODEL || CHAT_MODEL, ms = CHAT_LIMITS.reviewMs, threshold = REVIEW_THRESHOLD, links = 'block', now = () => Date.now() } = {}) {
-  if (!env?.AI || typeof env.AI.run !== 'function') throw new Error('this Worker has no Workers AI binding (AI)');
-  const spec = CHAT_MODELS[model] ?? CHAT_MODELS[CHAT_MODEL];
+export async function reviewChat(env, text, { model = env?.HOMIE_CHAT_MODEL || CHAT_MODEL, ms = CHAT_LIMITS.reviewMs, threshold = REVIEW_THRESHOLD, links = 'block', now = () => Date.now(), fetch: fetchImpl = null } = {}) {
+  // No binding: the person's own Ollama (`homie-studio dev` found clef-flash there), with the same question. Free.
+  const local = env?.AI && typeof env.AI.run === 'function' ? null : localAiOf(env);
+  if (!local && (!env?.AI || typeof env.AI.run !== 'function')) throw new Error('this Worker has no Workers AI binding (AI)');
+  const spec = local ? { kind: 'clef', name: local.model, input: 0, output: 0 } : CHAT_MODELS[model] ?? CHAT_MODELS[CHAT_MODEL];
   const at = now();
   if (spec.kind === 'guard') {
     const r = await timeout(env.AI.run(model, { messages: [{ role: 'user', content: text }], temperature: 0, max_tokens: 16, response_format: { type: 'json_object' } }), ms);
@@ -402,7 +407,9 @@ export async function reviewChat(env, text, { model = env?.HOMIE_CHAT_MODEL || C
   }
   // A room that allows links says so, so a plain link is not read as spam.
   const verdict = links === 'allow' ? { ...VERDICT, criteria: { ...VERDICT.criteria, spam: 'Ads, scams or spam (a plain link is fine here)' } } : VERDICT;
-  const r = await timeout(env.AI.run(model, { model: spec.name, state: text, questions: { verdict } }), ms);
+  const r = local
+    ? await clefRun(env, { state: text, questions: { verdict }, ms: Math.max(ms, 4000), local, fetch: fetchImpl })
+    : await timeout(env.AI.run(model, { model: spec.name, state: text, questions: { verdict } }), ms);
   const a = r?.answers?.verdict;
   if (!a || typeof a !== 'object') throw new Error('the review answered nothing it could use');
   const probs = a.probabilities && typeof a.probabilities === 'object' ? a.probabilities : null;
@@ -415,5 +422,5 @@ export async function reviewChat(env, text, { model = env?.HOMIE_CHAT_MODEL || C
     why = why ?? 'held';
   }
   const input = Number(r?.usage?.input_tokens ?? r?.usage?.prompt_tokens) || Math.ceil((text.length + VERDICT_CHARS) / 4);
-  return { ok: pOk >= threshold, why, p: Math.round(pOk * 1000) / 1000, neurons: (input * spec.input) / 1e6, ms: now() - at, model };
+  return { ok: pOk >= threshold, why, p: Math.round(pOk * 1000) / 1000, neurons: (input * spec.input) / 1e6, ms: now() - at, model: local ? local.model : model, ...(local ? { local: true } : {}) };
 }

package/worker/index.mjs

@@ -86,7 +86,7 @@ import {
   setMembership,
 } from './servers.mjs';
 import { BRAIN_BUDGET, HouseAgents, agentFacts, aiName, decodeFacts, encodeFacts, passById, passRefusal, sitRoute } from './agents.mjs';
-import { talks } from './brain.mjs';
+import { CLEF, DECIDE, clefRun, costOf, localAiOf, picksOf, talks } from './brain.mjs';
 import { REACTIONS, reviewChat } from './chat.mjs';
 import { REPORT_REASONS, chatDay, chatOf, chatRowsOf, fileReport } from './chat-store.mjs';
 import { doorPage, serverPage, serversPage } from './site.mjs';
@@ -1163,16 +1163,71 @@ export class Table {
     this.vocabRead = this.readVocab(game).catch(() => false);
     // Room chat (section 19): typed text the floor let through waits for the studio's own Workers AI.
     this.room.review = (text, opts) => this.reviewChat(text, opts);
+    // A game's own decisions (section 20): the host's typed questions, for a game whose game.json opts in.
+    this.room.decider = (state, questions, opts) => this.decide(state, questions, opts);
     return this.room;
   }
 
+  /** Whether this game asked for decisions (game.json "decide": true, in the built catalogue), read once a minute. */
+  async decideOn() {
+    if (this.decideRead && Date.now() - this.decideRead.at < 60_000) return this.decideRead.on;
+    let on = false;
+    try {
+      const res = this.env.ASSETS ? await this.env.ASSETS.fetch(new Request('https://assets.local/games.json')) : null;
+      const cat = res?.ok ? await res.json() : null;
+      const g = (cat?.games ?? []).find((x) => x.id === this.game);
+      on = Boolean(g && (g.decide === true || (g.decide && typeof g.decide === 'object' && g.decide.on !== false)));
+    } catch { on = false; }
+    this.decideRead = { at: Date.now(), on };
+    return on;
+  }
+
+  /**
+   * One of a game's own decisions (worker/brain.mjs checkDecide, picksOf): Clef on the studio's Workers AI (model
+   * HOMIE_DECIDE_MODEL, else clef-flash), or the person's own Ollama under `homie-studio dev`, within the AI brains' day
+   * (the same budget the guides spend: decisions and guides are one day of neurons). Not opted in, no AI, over budget, too
+   * slow or failed: `{ ok: false, why }`, and the host's floor answers.
+   */
+  async decide(state, questions) {
+    if (!(await this.decideOn())) return { ok: false, why: 'off' };
+    const local = this.env.AI ? null : localAiOf(this.env);
+    if (!this.env.AI && !local) return { ok: false, why: 'no-ai' };
+    if (this.env.AI) {
+      if (!this.brainDay || Date.now() - this.brainReadAt > 60_000) await this.readBrainDay().catch(() => {});
+      if (this.brainCap.neurons - this.brainUsed.neurons <= 0) return { ok: false, why: 'budget' };
+    }
+    const model = CLEF.models[this.env.HOMIE_DECIDE_MODEL] ? this.env.HOMIE_DECIDE_MODEL : '@cf/cloudflare/clef-flash';
+    const t0 = Date.now();
+    try {
+      const r = await clefRun(this.env, { state, questions, model, ms: DECIDE.ms, local });
+      const ms = Date.now() - t0;
+      const usage = r.usage ?? { input_tokens: Math.ceil(JSON.stringify({ state, questions }).length / 4) + 400, output_tokens: 0 };
+      const cost = costOf({ provider: r.engine === 'local' ? 'local' : 'workers-ai', model: r.model, usage });
+      this.brainSpend({ neurons: cost.neurons, micros: 0, provider: r.engine === 'local' ? 'decide-local' : 'decide' });
+      this.flushSoon();
+      const { picks, p } = picksOf(r.answers, questions);
+      return { ok: true, by: r.engine === 'local' ? 'local' : 'ai', picks, p, ms, neurons: cost.neurons };
+    } catch (error) {
+      return { ok: false, why: /took over/.test(String(error?.message ?? error)) ? 'slow' : 'error' };
+    }
+  }
+
+  /** The day's counters go to D1 on an alarm: set one a minute out when none is set (a house guide's alarm also flushes). */
+  flushSoon() {
+    this.ctx.waitUntil((async () => { if ((await this.ctx.storage.getAlarm()) === null) await this.ctx.storage.setAlarm(Date.now() + 60_000); })().catch(() => {}));
+  }
+
   /**
    * One typed chat message, reviewed by the studio's decision model (worker/chat.mjs reviewChat) within the day's
    * budget for the whole studio. No binding (`homie-studio dev` without --remote-ai), no budget left, or an error: the
    * floor alone has decided (`by` says which), and the message goes out.
    */
   async reviewChat(text, { links = 'block' } = {}) {
-    if (!this.env.AI) return { ok: true, by: 'none' };
+    // Under `homie-studio dev` with no binding, the person's own Ollama reviews (free, so no budget).
+    if (!this.env.AI) {
+      if (!localAiOf(this.env)) return { ok: true, by: 'none' };
+      try { const v = await reviewChat(this.env, text, { links }); return { ok: v.ok, by: 'local', why: v.why, ms: v.ms, p: v.p }; } catch { return { ok: true, by: 'error' }; }
+    }
     if (this.chatCap === null || Date.now() - this.chatReadAt > 60_000) await this.readChatDay().catch(() => {});
     if (this.chatUsed >= (this.chatCap ?? 0)) return { ok: true, by: 'budget' };
     try {

package/worker/office.mjs

@@ -56,9 +56,9 @@
  */
 import { SEAT_MAX, seatsOf } from './seats.mjs';
 import { PUBLIC_SERVER, SERVER_LIMITS, checkServer, levelName, narrows, policyOf, roomServer, rowFor, serverView, serversOf, serverPassCookie, writeServer } from './servers.mjs';
-import { BRAIN_BUDGET, aiName, fillSpot, passById, passCreate, passList, passRevoke } from './agents.mjs';
-import { DEFAULT_MODEL, OWNER_MODEL } from './brain.mjs';
-import { OWNER_COOKIE, cookieValues, ownerAllowed, ownerSession, today } from './stats.mjs';
+import { BRAIN_BUDGET, aiName, brainFor, fillSpot, passById, passCreate, passList, passRevoke, think } from './agents.mjs';
+import { DEFAULT_MODEL, NEURONS_PER_M, OWNER_MODEL, vocabularyOf } from './brain.mjs';
+import { OWNER_COOKIE, cookieValues, counter, ownerAllowed, ownerSession, today } from './stats.mjs';
 import { esc, layout, notFoundPage } from './site.mjs';
 import { confirmPage, lockedPage, officePage } from './office-page.mjs';
 import { licenseOf } from './license.mjs';
@@ -473,6 +473,8 @@ async function roomRow(env, meta, room, max) {
     clients, bans: office.bans ?? [], mutes: office.mutes ?? [],
     // Room chat (0.23.0): the room's last minutes, with who sent each line (a client id and account; never an address).
     chat: office.chat ? { mode: office.chat.rules?.mode ?? null, pending: office.chat.pending ?? 0, lines: (office.chat.lines ?? []).slice(-50).map((l) => ({ id: l.id, at: l.at, t: l.t, kind: l.kind, name: oneLine(l.name, 40), seat: l.seat ?? null, by: l.by, text: l.text ?? null, glyph: l.glyph ?? null, react: l.react ?? null, say: l.say ?? null, acct: Boolean(l.acct), owner: Boolean(l.owner), client: l.client ?? null, player: l.player ?? null, browser: l.browser ?? null, ...(l.review ? { review: l.review } : {}) })) } : null,
+    // A game's own decisions (0.24.4, net.decide): how many, who answered, the model's median time, the neurons.
+    ...(office.decides && typeof office.decides === 'object' ? { decides: { n: Number(office.decides.n) || 0, by: office.decides.by ?? {}, msP50: office.decides.msP50 ?? null, neurons: Number(office.decides.neurons) || 0 } } : {}),
     // The house guides' brains (0.17.0): which brain, why not when it is not, and the last decisions (seats and ids).
     ...(f.brains && typeof f.brains === 'object' ? { brains: {
       brain: String(f.brains.brain ?? ''), why: f.brains.why ? oneLine(f.brains.why, 120) : null, calls: Number(f.brains.calls) || 0,
@@ -482,6 +484,62 @@ async function roomRow(env, meta, room, max) {
   };
 }
 
+/**
+ * `agents try` (0.24.4): a guide's brain on one moment the owner gives, with no seat taken and nobody in a room: the
+ * game's own vocabulary, the view, the asks and the party's lines in; the decision out, with the brain's own pick
+ * before the fixed rules, Clef's probabilities, the model's time and the neurons. It runs exactly what a house guide
+ * runs (agents.mjs think) and spends from the same day's budget, so a creator can test an agents.json, and compare a
+ * model (`model`: one of the models this toolkit prices) before setting it.
+ */
+export async function agentsTry(env, cat, body) {
+  const bad = (message) => ({ ok: false, error: 'bad-request', message });
+  const meta = (cat.games ?? []).find((g) => g.id === body.game);
+  if (!meta) return bad('game is one of this studio\'s game ids');
+  const mode = body.mode ?? 'workers-ai';
+  if (!['workers-ai', 'owner-key', 'script'].includes(mode)) return bad('mode is workers-ai, owner-key or script');
+  if (body.model !== undefined && !(typeof body.model === 'string' && NEURONS_PER_M[body.model])) return bad(`model is one of ${Object.keys(NEURONS_PER_M).join(', ')}`);
+  const view = body.view && typeof body.view === 'object' && !Array.isArray(body.view) ? body.view : null;
+  if (!view || JSON.stringify(view).length > 2048) return bad('view is the game state a guide sees (an object, under 2 KB)');
+  const int = (v) => Number.isInteger(v) && v >= 0 && v < 64;
+  const asks = (Array.isArray(body.asks) ? body.asks : []).slice(0, 3).filter((a) => a && typeof a.k === 'string' && int(a.from)).map((a, i) => ({ k: a.k, args: a.args && typeof a.args === 'object' ? a.args : {}, from: a.from, at: Date.now() - i }));
+  const party = (Array.isArray(body.party) ? body.party : []).slice(-3).filter((p) => p && int(p.seat) && typeof p.line === 'string').map((p) => ({ seat: p.seat, line: p.line, args: p.args ?? {} }));
+  const seats = (list) => (Array.isArray(list) ? list.filter(int).slice(0, 32) : []);
+  let vocab = null;
+  try {
+    const res = env.ASSETS ? await env.ASSETS.fetch(new Request(`https://assets.local/games/${meta.id}/agents.json`)) : null;
+    if (res?.ok) vocab = vocabularyOf(await res.json()).vocab;
+  } catch { vocab = null; }
+  if (!vocab) return { ok: false, error: 'no-vocabulary', message: `${meta.name} has no agents.json in this build: its guides have nothing to choose from.` };
+  const day = await brainDay(env);
+  const budget = { left: (k) => (k === 'neurons' ? day.budget.neurons - day.used.neurons : day.budget.usd * 1e6 - day.used.usd * 1e6) };
+  const e = body.model ? { ...env, HOMIE_BRAIN_MODEL: body.model } : env;
+  const brain = brainFor(mode, e, { budget });
+  const ctx = {
+    view, me: { seat: int(body.seat) ? body.seat : 7 }, goal: view.goal ?? null, asks, party, speech: ['game', 'lines', 'off'].includes(body.speech) ? body.speech : 'lines',
+    kids: body.kids === true, quiet: body.quiet === true, players: seats(body.players ?? (Array.isArray(view.party) ? view.party.map((p) => p?.seat) : [])), avoid: seats(body.avoid),
+    // What a house guide remembers: who is new to it, and its own last lines (ids, arguments, how long ago).
+    newHere: seats(body.newHere),
+    said: (Array.isArray(body.said) ? body.said : []).slice(-4).filter((x) => x && typeof x.line === 'string' && vocab.lines[x.line]).map((x) => ({ line: x.line, args: x.args && typeof x.args === 'object' ? x.args : {}, ago: Math.max(0, Number(x.agoMs) || 0) })),
+  };
+  const t = await think(vocab, { mode, brain, ctx });
+  if (t.engine && env.DB) {
+    const rows = [counter(env, { metric: 'brain-calls', subject: meta.id, source: 'try' })];
+    const n = Math.round(t.cost.neurons);
+    if (n > 0) rows.push(counter(env, { metric: 'brain-neurons', subject: meta.id, n }));
+    if (t.cost.micros >= 1) rows.push(counter(env, { metric: 'brain-microdollars', subject: meta.id, n: Math.round(t.cost.micros) }));
+    await env.DB.batch(rows.filter(Boolean)).catch(() => {});
+  }
+  return {
+    ok: true, game: meta.id, mode, model: t.model ?? (mode === 'workers-ai' ? e.HOMIE_BRAIN_MODEL || DEFAULT_MODEL : null), engine: t.engine, provider: t.provider,
+    decision: t.decision, own: t.own, overruled: /\+floor$/.test(t.provider), why: t.why, p: t.p, ms: t.ms,
+    // A decision model's whole answer: every option's probability, per question (ids and numbers only).
+    ...(t.answers ? { answers: Object.fromEntries(Object.entries(t.answers).map(([k, a]) => [k, a?.probabilities ? Object.fromEntries(Object.entries(a.probabilities).map(([o, v]) => [o, Math.round(Number(v) * 100) / 100])) : a?.noul ?? a?.score ?? null])) } : {}),
+    ...(t.usage ? { tokens: { input: Number(t.usage.input_tokens ?? t.usage.prompt_tokens) || null, output: Number(t.usage.output_tokens ?? t.usage.completion_tokens) || 0 } } : {}),
+    neurons: Math.round(t.cost.neurons * 1000) / 1000, micros: Math.round(t.cost.micros),
+    budget: { neurons: day.budget.neurons, usedBefore: Math.round(day.used.neurons) },
+  };
+}
+
 /** The AI brains' day for the whole studio: the budget (meta brain_budget) and what today used (stats_daily). */
 export async function brainDay(env) {
   const budget = { neurons: BRAIN_BUDGET.neurons, usd: BRAIN_BUDGET.usd };
@@ -1163,6 +1221,8 @@ async function api(request, env, url, cat) {
       return json({ ok: true, game, server, members });
     } catch (error) { return json({ ok: false, error: 'not-migrated', message: `Servers need migration 0006_studio_servers.sql (npm run deploy). (${String(error?.message ?? error).slice(0, 120)})` }, 503); }
   }
+  // A guide's brain on a moment the owner gives (0.24.4): what it would decide, why, how sure, how long and what it cost.
+  if (path === '/_studio/api/agents/try' && request.method === 'POST') return json(await agentsTry(env, cat, body));
   // Room chat (0.23.0): every game's rules, every live room's last minutes, the reports, the review's day.
   if (path === '/_studio/api/chat' && request.method === 'GET') {
     const metas = (cat.games ?? []).filter((g) => !url.searchParams.get('game') || g.id === url.searchParams.get('game'));
@@ -1213,7 +1273,8 @@ async function api(request, env, url, cat) {
     }
   }
   const result = await perform(env, cat, action);
-  return json({ ...result, what: describe(cat, action), by: who }, result.ok ? 200 : result.error === 'no-player' ? 404 : 400);
+  // A refund Stripe holds for a person's approval (an Agent-tagged key) is accepted, not refused: it happens there.
+  return json({ ...result, what: describe(cat, action), by: who }, result.ok ? 200 : result.held ? 202 : result.error === 'no-player' ? 404 : 400);
 }
 
 /** /_studio/office, /_studio/confirm/<ask> and /_studio/api/*; null for any other path. */

package/worker/room.mjs

@@ -44,7 +44,7 @@
  * =============================================================================
  */
 import { aiName, skillPreset, stripAi } from './agents.mjs';
-import { checkArgs, talks, vocabularyOf } from './brain.mjs';
+import { DECIDE, checkArgs, checkDecide, talks, vocabularyOf } from './brain.mjs';
 import { CHAT_LIMITS, CHAT_RATES, HELD_WORDS, allows, cleanText, floor, normalizeChat, publicChat } from './chat.mjs';
 
 export const NET_VERSION = 1;
@@ -103,6 +103,8 @@ export const LIMITS = Object.freeze({
   hello: 2048, snap: 16384, in: 2048, ev: 4096, ckpt: 65536, state: 8192, round: 8192, roster: 4096, ping: 256, other: 512,
   // Room chat (revision 8): a typed line (280 characters, emoji count double), a reaction.
   say: 1536, react: 256,
+  // A game's own decision (section 20): a few typed questions about its state.
+  decide: DECIDE.bytes,
 });
 /**
  * What grows with the seats (every body, every result, every slot): the checkpoint, round and roster caps double
@@ -112,7 +114,7 @@ export const LIMITS = Object.freeze({
 export const GROWS = Object.freeze(['ckpt', 'round', 'roster']);
 export const capOf = (t, seats) => (LIMITS[t] ?? LIMITS.other) * (GROWS.includes(t) && seats > 16 ? 2 : 1);
 /** Rate caps (messages per rolling second, per client). Over the cap a message is dropped, counted and reported. */
-export const RATES = Object.freeze({ snap: 30, in: 60, ev: 30, ckpt: 4, state: 64, round: 4, roster: 8, ping: 8, other: 8, say: 4, react: 10 });
+export const RATES = Object.freeze({ snap: 30, in: 60, ev: 30, ckpt: 4, state: 64, round: 4, roster: 8, ping: 8, other: 8, say: 4, react: 10, decide: 2 });
 /** `ev` per second by the sender's role: a screen is a spectator, and the host is somebody's phone. */
 export const EV_RATES = Object.freeze({ host: 30, replica: 10, screen: 2 });
 /** The keyed state channel: at most this many keys and bytes per room. */
@@ -274,7 +276,7 @@ export class NetRoom {
     this.stats = {
       snaps: 0, ins: 0, evs: 0, ckpts: 0, states: 0, rounds: 0, drops: 0, oversize: 0, stFixed: 0, reclaimed: 0, seated: 0,
       kicked: 0, refused: 0, persists: 0, restoredFrom: null, bytesIn: 0, bytesOut: 0, elections: [], promotions: 0,
-      speechDrops: 0, agentDrops: 0, labelled: 0, votes: 0,
+      speechDrops: 0, agentDrops: 0, labelled: 0, votes: 0, decides: 0, decided: {}, decideMs: [],
     };
     this.snapTimes = [];
     /** The owner's controls (section 15): who is held out of this room until when, who is muted, the banner, a closed door. */
@@ -299,6 +301,13 @@ export class NetRoom {
     this.chatReacts = [];
     this.chatPending = 0;
     this.review = null;
+    /**
+     * A game's own decisions (section 20): the host's typed questions, answered by the studio's decision model (the Table
+     * sets `decider`; null: the host's floor answers), at most one every 3 s and 20 a minute a room, two at a time.
+     */
+    this.decider = null;
+    this.decideTimes = [];
+    this.decidePending = 0;
     this.watchIds = new WeakMap();
     this.defaultChat = null;
   }
@@ -403,6 +412,39 @@ export class NetRoom {
   peers() { return this.live().map((c) => this.peer(c)); }
   stateObject() { const o = {}; for (const [k, v] of this.state) o[k] = v.d; return o; }
 
+  /**
+   * A game's own decision (section 20): the host's typed questions about its state, answered by the studio's decision
+   * model through the Table (`decider`). Only the host asks; the answer (`decided`, option ids and numbers only) goes
+   * back to that socket alone. Off, paced, over budget, too slow or wrong: `ok: false` with why, and the host's own floor
+   * answers. `n` is the host's own id for the request.
+   */
+  onDecide(c, m, isHost) {
+    const n = typeof m.n === 'string' || Number.isInteger(m.n) ? String(m.n).slice(0, 16) : '';
+    const reply = (o) => this.send(c, { t: 'decided', n, ...o });
+    if (!isHost || this.lite(c)) return reply({ ok: false, why: 'not-host' });
+    if (typeof this.decider !== 'function') return reply({ ok: false, why: 'off' });
+    const now = this.now();
+    while (this.decideTimes.length && this.decideTimes[0] <= now - 60_000) this.decideTimes.shift();
+    const last = this.decideTimes.at(-1) ?? -Infinity;
+    if (now - last < DECIDE.gapMs - 100 || this.decideTimes.length >= DECIDE.perMinute) return reply({ ok: false, why: 'pace', retryMs: Math.max(DECIDE.gapMs - (now - last), this.decideTimes.length >= DECIDE.perMinute ? this.decideTimes[0] + 60_000 - now : 0) });
+    if (this.decidePending >= DECIDE.inFlight) return reply({ ok: false, why: 'busy' });
+    const q = checkDecide(m.state, m.questions);
+    if (!q.ok) return reply({ ok: false, why: 'bad', message: q.why });
+    this.decideTimes.push(now);
+    this.decidePending += 1;
+    this.stats.decides += 1;
+    Promise.resolve()
+      .then(() => this.decider(q.state, q.questions, { room: this.code, kids: this.policy.kids }))
+      .then((r) => {
+        const by = r?.ok ? r.by ?? 'ai' : r?.why ?? 'error';
+        this.stats.decided[by] = (this.stats.decided[by] ?? 0) + 1;
+        if (r?.ok) { this.stats.decideMs.push(r.ms ?? 0); if (this.stats.decideMs.length > 40) this.stats.decideMs.shift(); this.stats.decideNeurons = (this.stats.decideNeurons ?? 0) + (Number(r.neurons) || 0); }
+        reply(r?.ok ? { ok: true, by: r.by ?? 'ai', picks: r.picks ?? {}, p: r.p ?? {}, ms: r.ms ?? null } : { ok: false, why: r?.why ?? 'error' });
+      })
+      .catch(() => { this.stats.decided.error = (this.stats.decided.error ?? 0) + 1; reply({ ok: false, why: 'error' }); })
+      .finally(() => { this.decidePending -= 1; });
+  }
+
   /** Drop the socket from the room and close it. */
   kick(c, why, code = 1008) {
     this.stats.kicked += 1;
@@ -515,6 +557,7 @@ export class NetRoom {
         }
         return;
       }
+      case 'decide': return this.onDecide(c, m, isHost);
       case 'ckpt': {
         if (!isHost) return;
         this.lastCkpt = { k: Number(m.k) || 0, st: this.stamp(m.st), d: m.d ?? null, ...(Array.isArray(m.c) ? { c: m.c.slice(0, 64) } : {}) };
@@ -1821,6 +1864,8 @@ export class NetRoom {
           pending: this.chatPending,
           lines: this.recentChat(now).map((r) => ({ ...this.wireLine(r), kind: r.kind, client: r.from?.client ?? null, player: r.from?.player ?? null, browser: browserTag(r.from?.browser), ...(r.review ? { review: r.review } : {}) })),
         },
+        // A game's own decisions (section 20): how many, who answered, the model's time and neurons (never a state).
+        ...(this.stats.decides ? { decides: { n: this.stats.decides, by: { ...this.stats.decided }, msP50: [...this.stats.decideMs].sort((x, y) => x - y)[Math.floor(this.stats.decideMs.length / 2)] ?? null, neurons: Math.round((this.stats.decideNeurons ?? 0) * 100) / 100 } } : {}),
       },
     };
   }

package/worker/shop-rules.mjs

@@ -206,16 +206,32 @@ export function checkShop(raw, { games = null, audience = 'general' } = {}) {
     }
   }
 
+  // Where `homie-studio shop catalog` made the items' Products in Stripe (0.24.3): the Worker's checkouts then name them.
+  let catalog = [];
+  if (raw.catalog !== undefined && raw.catalog !== null) {
+    if (!Array.isArray(raw.catalog) || raw.catalog.some((m) => m !== 'test' && m !== 'live')) err('catalog', 'catalog lists where the items are Products in Stripe: ["test"], ["test", "live"] (homie-studio shop catalog writes it)');
+    else catalog = [...new Set(raw.catalog)].sort();
+  }
+
   const kids = audience === 'kids';
   const finalTill = kids ? 'off' : TILLS.includes(till) ? till : 'off';
   if (kids && till !== 'off') warnings.push({ at: 'till', message: 'studio.json says "audience": "kids": the studio sells nothing in its games (the till is off whatever shop.json says).' });
   const shop = {
     v: 1, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items, referrals,
-    open: finalTill !== 'off' && items.length > 0, ...(kids ? { audience: 'kids' } : {}),
+    open: finalTill !== 'off' && items.length > 0, ...(kids ? { audience: 'kids' } : {}), ...(catalog.length ? { catalog } : {}),
   };
   return { ok: errors.length === 0, shop, errors, warnings };
 }
 
+/**
+ * The Stripe product tax code an item gets when shop.json names none: video games, downloaded, permanent rights
+ * (txcd_10201000), or limited rights for an item that lasts a number of days or ends on a date (txcd_10201001).
+ * Managed Payments needs one of its eligible codes on every product; these two are.
+ */
+export function defaultTaxCode(item) {
+  return item?.taxCode ?? (item?.days || item?.ends ? 'txcd_10201001' : 'txcd_10201000');
+}
+
 /** studio.json "audience": "general" (the default), "teens" or "kids". */
 export function audienceOf(studio) {
   const a = studio?.audience;

package/worker/shop.mjs

@@ -22,17 +22,23 @@
  * player's account: it changes nothing until it is decided, and a lost one is a refund of that one item.
  *
  * SECRETS (Worker secrets, put there by `homie-studio shop connect` from a page on the owner's own computer):
- * STRIPE_KEY (a restricted key: Checkout Sessions write, Charges write for refunds, PaymentIntents and Disputes read)
- * and STRIPE_WEBHOOK_SECRET. Never in a file, a chat, a log or a page.
+ * STRIPE_KEY (a restricted key: Checkout Sessions write, Charges write for refunds, PaymentIntents and Disputes read;
+ * from 0.24.3 also Webhook Endpoints write, which only the connect page on the owner's computer uses) and
+ * STRIPE_WEBHOOK_SECRET. Never in a file, a chat, a log or a page.
+ *
+ * THE CATALOG (0.24.3): once `homie-studio shop catalog` has made the items' Products in Stripe (shop.json `catalog`
+ * names the modes), a checkout names its item's Product, so the Dashboard, Stripe's reports and Stripe's MCP see sales
+ * by product. The price is always shop.json's (the rules checked it), never one read from Stripe. A Product missing
+ * in this mode falls back to the item described inline, so a sale never fails over the catalog.
  */
 import { players } from './players.mjs';
 import { serversOf } from './servers.mjs';
-import { CAP_CEILING, audienceOf, bandOf, checkShop, money, wayFor } from './shop-rules.mjs';
+import { CAP_CEILING, audienceOf, bandOf, checkShop, defaultTaxCode, money, wayFor } from './shop-rules.mjs';
 import {
   bandOfPlayer, forgetPlayerShop, grantStatements, migrated, newOrderId, orderById, orderByPayment, orderBySession, orderView, ownsOf, restoreStatement, revokeStatement,
   setBand, shopDataOf, spentThisMonth,
 } from './shop-store.mjs';
-import { KEY_SHAPE, StripeError, WEBHOOK_SECRET_SHAPE, createCheckoutSession, createRefund, dashboardLink, modeOf, verifyWebhook } from './stripe.mjs';
+import { KEY_SHAPE, StripeError, WEBHOOK_SECRET_SHAPE, createCheckoutSession, createRefund, dashboardLink, isApprovalRequired, isMissingProduct, modeOf, productIdOf, verifyWebhook } from './stripe.mjs';
 import { arrivalOf, booksOf, lineFor, receiveStatement, referrerOk, sendStatements, settle, statementFor, statementsIn, voidLineStatements } from './referrals.mjs';
 import { SHOP_JS, officeShopPage, parentPage, refundsPage, shopPage, thanksPage } from './shop-page.mjs';
 import { notFoundPage } from './site.mjs';
@@ -270,11 +276,10 @@ async function ageRoute(request, env) {
   return json({ ok: true, asked: true });
 }
 
-function sessionParams(shop, item, order, { origin, amount, player, game, parent = false, studio }) {
+export function sessionParams(shop, item, order, { origin, amount, player, game, parent = false, studio, product = null }) {
   const managed = shop.till === 'stripe-managed';
-  const limited = Boolean(item.days || item.ends);
   // Managed Payments needs an eligible digital-goods tax code on every product (video games, downloaded).
-  const taxCode = item.taxCode ?? (managed ? (limited ? 'txcd_10201001' : 'txcd_10201000') : undefined);
+  const taxCode = item.taxCode ?? (managed ? defaultTaxCode(item) : undefined);
   const back = game ? `&game=${encodeURIComponent(game)}` : '';
   return {
     mode: 'payment',
@@ -282,7 +287,8 @@ function sessionParams(shop, item, order, { origin, amount, player, game, parent
       quantity: 1,
       price_data: {
         currency: shop.currency, unit_amount: amount, tax_behavior: 'exclusive',
-        product_data: { name: item.name.slice(0, 120), ...(item.blurb ? { description: item.blurb.slice(0, 300) } : {}), ...(taxCode ? { tax_code: taxCode } : {}), metadata: { item: item.id } },
+        // The catalog's Product (its name and tax code are Stripe's copy of shop.json's), or the item described inline.
+        ...(product ? { product } : { product_data: { name: item.name.slice(0, 120), ...(item.blurb ? { description: item.blurb.slice(0, 300) } : {}), ...(taxCode ? { tax_code: taxCode } : {}), metadata: { item: item.id } } }),
       },
     }],
     client_reference_id: player,
@@ -306,8 +312,18 @@ async function startCheckout(env, url, cat, shop, item, { player, game, via, amo
   await env.DB.prepare("INSERT INTO shop_orders (id, player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'started', ?9, ?10, ?11, ?11)")
     .bind(order.id, player.id, item.id, game ?? item.game ?? null, amount, shop.currency, shop.till, modeOf(env.STRIPE_KEY), parent ? 1 : 0, order.via, now).run();
   let session = null;
+  const mode = modeOf(env.STRIPE_KEY);
+  const product = Array.isArray(shop.catalog) && shop.catalog.includes(mode) ? productIdOf(cat.studio?.slug, item.id) : null;
+  const params = (p) => sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name, product: p });
   try {
-    session = await createCheckoutSession(env, sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name }), { idempotencyKey: `checkout-${order.id}` });
+    try {
+      session = await createCheckoutSession(env, params(product), { idempotencyKey: `checkout-${order.id}` });
+    } catch (error) {
+      // shop.json says the catalog is made in this mode, but Stripe has no such Product (made in the sandbox only, or
+      // archived by hand): the item described inline still sells, and `homie-studio shop catalog` says what to make.
+      if (!product || !isMissingProduct(error)) throw error;
+      session = await createCheckoutSession(env, params(null), { idempotencyKey: `checkout-${order.id}-inline` });
+    }
   } catch (error) {
     await env.DB.prepare("UPDATE shop_orders SET status = 'failed', note = ?2, updated_at = ?3 WHERE id = ?1").bind(order.id, String(error?.code ?? 'stripe').slice(0, 60), Date.now()).run();
     const why = error instanceof StripeError ? error.message : 'Stripe did not answer';
@@ -441,6 +457,7 @@ async function selfRefundRoute(request, env, shop, ready) {
   if (!refundableNow(orderView(o), Number(used?.n) ? [{ item: o.item, used: true }] : [], shop)) return fail(403, 'not-refundable', `Only an unused item, within ${shop.refundDays} days. Ask the studio for anything else.`);
   if (!KEY_SHAPE.test(String(env.STRIPE_KEY ?? ''))) return fail(503, 'closed', MISSING_WORDS['stripe-key']);
   const r = await refundOrder(env, o, { reason: 'requested_by_customer', by: 'player' });
+  if (r.held) return json({ ok: false, held: true, error: 'held', message: 'The studio approves this refund in Stripe first. Your money comes back once they do, and the item leaves your account then.' }, 202);
   return json(r, r.ok ? 200 : 502);
 }
 
@@ -553,6 +570,9 @@ async function disputeClosed(env, payment, status) {
   return 'kept';
 }
 
+/** What the owner reads when Stripe holds a refund for approval (the shop's key is an Agent key). */
+export const REFUND_HELD = 'Stripe is holding this refund until a person approves it in Stripe (Settings, Approvals, Requests): the shop\'s Stripe key is marked as an Agent key, and Stripe asks a person before an agent\'s refund. Approve it there; Stripe then refunds, and the item leaves the player\'s account when Stripe says so. To refund with one tap again, connect the shop with a plain restricted key (homie-studio shop connect), not one made for "Authorizing agent access".';
+
 /** Refund one order in full with Stripe, then take back that one item. The webhook confirms the same (idempotent). */
 export async function refundOrder(env, o, { reason = 'requested_by_customer', by = 'owner' } = {}) {
   if (o.status !== 'paid') return { ok: false, error: 'state', message: o.status === 'disputed' ? 'This order is disputed: the card network decides it now (answer it in Stripe).' : `This order is ${o.status}, not paid.` };
@@ -561,6 +581,9 @@ export async function refundOrder(env, o, { reason = 'requested_by_customer', by
   try {
     refund = await createRefund(env, { payment_intent: o.payment, reason: ['duplicate', 'fraudulent', 'requested_by_customer'].includes(reason) ? reason : 'requested_by_customer', metadata: { order: o.id, by } }, { idempotencyKey: `refund-${o.id}` });
   } catch (error) {
+    // An Agent-tagged key: Stripe holds an agent's refund for a person's approval. Nothing happened yet; once someone
+    // approves it in Stripe, Stripe refunds and the webhook (refund.created, charge.refunded) takes the item back.
+    if (isApprovalRequired(error)) return { ok: false, error: 'approval', held: true, message: REFUND_HELD };
     return { ok: false, error: 'stripe', message: `Stripe did not refund it (${error instanceof StripeError ? error.message : 'no answer'}). Nothing changed.` };
   }
   const now = Date.now();

package/worker/stripe.mjs

@@ -4,6 +4,10 @@
  *
  *   createCheckoutSession(env, params)   POST /v1/checkout/sessions (Stripe's hosted page; the TV never calls it)
  *   createRefund(env, params)            POST /v1/refunds (only ever from the owner's tap, or a confirmed ask)
+ *   webhook endpoints                    list, create and turn off: only `homie-studio shop connect` calls these, on the
+ *                                        owner's computer with the key the owner pasted there (0.24.3), so a new
+ *                                        endpoint's signing secret goes straight to the Worker secret
+ *   productIdOf(slug, item)              the catalog Product a shop item is (`homie-studio shop catalog`, 0.24.3)
  *   verifyWebhook(payload, header, secret)   the `Stripe-Signature` header: t=<seconds>,v1=<hex HMAC-SHA256 of
  *                                        "<t>.<payload>"> with the endpoint's whsec_ secret, within 5 minutes
  *
@@ -54,9 +58,30 @@ export class StripeError extends Error {
     this.status = status;
     this.code = e.code ?? e.type ?? 'stripe';
     this.type = e.type ?? null;
+    this.param = typeof e.param === 'string' ? e.param.slice(0, 120) : null;
   }
 }
 
+/** Stripe has no such Product (a catalog Product the shop names, in a mode the catalog was never made in). */
+export const isMissingProduct = (error) => error instanceof StripeError && error.code === 'resource_missing' && /product/.test(String(error.param ?? error.message));
+/**
+ * Stripe is holding the call for a person's approval: an Agent-tagged key's refund meets Stripe's approval rules
+ * (docs.stripe.com/account/approvals). Nothing happened yet; it happens when someone approves it in Stripe.
+ */
+export const isApprovalRequired = (error) => error instanceof StripeError && error.code === 'approval_required';
+/** The key may not do this (a restricted key without the permission). */
+export const isPermissionError = (error) => error instanceof StripeError && (error.status === 403 || error.status === 401 || /permission|restricted key/i.test(error.message));
+
+/**
+ * The catalog Product a shop item is, the same id in a sandbox and in live mode: `homie_<studio slug>_<item id>`
+ * (Stripe takes a product id of our choosing). Null without a slug or an item id.
+ */
+export function productIdOf(slug, item) {
+  const s = String(slug ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 48);
+  const i = String(item ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 40);
+  return s && i ? `homie_${s}_${i}` : null;
+}
+
 /** One call with the studio's key. `idempotencyKey` makes a retried POST do the work once (Stripe keeps it 24 h). */
 export async function stripeCall(env, method, path, params = null, { idempotencyKey = null, fetcher = fetch } = {}) {
   const key = String(env?.STRIPE_KEY ?? '');
@@ -83,6 +108,11 @@ export async function stripeCall(env, method, path, params = null, { idempotency
 export const createCheckoutSession = (env, params, opts) => stripeCall(env, 'POST', '/v1/checkout/sessions', params, opts);
 export const retrieveCheckoutSession = (env, id, opts) => stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(id)}`, null, opts);
 export const createRefund = (env, params, opts) => stripeCall(env, 'POST', '/v1/refunds', params, opts);
+export const expireCheckoutSession = (env, id, opts) => stripeCall(env, 'POST', `/v1/checkout/sessions/${encodeURIComponent(id)}/expire`, {}, opts);
+export const listWebhookEndpoints = (env, opts) => stripeCall(env, 'GET', '/v1/webhook_endpoints', { limit: 100 }, opts);
+/** The answer carries the endpoint's signing secret (`secret`), once: the caller puts it in the Worker and drops it. */
+export const createWebhookEndpoint = (env, params, opts) => stripeCall(env, 'POST', '/v1/webhook_endpoints', params, opts);
+export const updateWebhookEndpoint = (env, id, params, opts) => stripeCall(env, 'POST', `/v1/webhook_endpoints/${encodeURIComponent(id)}`, params, opts);
 
 /* ------------------------------------------------------------------ webhooks */
 

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.24.2';
+export const STUDIO_VERSION_TAG = '0.24.4';