@genex-ai/cli-demo 1.34.9-dev.735 → 1.35.0-dev.736

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.34.9-dev.735",
+  "version": "1.35.0-dev.736",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "start": "node src/index.ts",
     "dev": "node --watch src/index.ts",
     "typecheck": "tsc --noEmit",
-    "test": "node --test --test-concurrency=1 test/*.test.ts"
+    "test": "GENEX_NO_BROWSER=1 node --test --test-concurrency=1 test/*.test.ts"
   },
   "keywords": [
     "cli",

package/templates/skills/genex-game-director/SKILL.md

@@ -156,6 +156,7 @@ vendored code from memory of another engine.
 | sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
 | requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
 | selling anything for platform coin: a shop, an item catalog, boosts, cosmetics, "make it earn"; also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
+| the game calls a language model AT RUNTIME on the player's money: NPCs that answer in their own words, dialogue or quests written per save, a judge reading what the player typed — one-time calls, or a standing budget the player approves once. Check the lane with `npx genex llm models` before designing it in | `$genex-llm-in-games` |
 | cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
 | drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
 | the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |

package/templates/skills/genex-llm-in-games/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: genex-llm-in-games
+description: Call a language model from inside a running game — an NPC that answers in its own words, a quest written for this save, a judge that reads what the player typed. The PLAYER pays and approves, on a Genex surface the game cannot forge. Covers the two modes (a popup per call, or one standing budget then many silent calls), benchmarking the price before declaring it, the receiver pattern, and honest handling of every refusal.
+---
+
+# Genex LLM in Games
+
+A Genex game can call a language model **while the player is playing** and get
+back text or JSON. Nothing else: no images, no code execution, no tools.
+
+**The player pays, and the player approves.** Funding is coin from their Genex
+wallet or their own Claude / ChatGPT plan, chosen on a Genex-drawn surface your
+game cannot render, skin or bypass. The game holds no provider key, sees no
+credential, and never talks to a model vendor.
+
+Two modes. Picking the wrong one is the most expensive mistake on this lane:
+
+| | One-time | Standing budget |
+| --- | --- | --- |
+| Shape | `generate()` — one approval popup per call | `requestSpendGrant()` once, then `generate({ grantId })` many times, no popup |
+| Fits | a rare, deliberate moment the player asked for | a loop — NPCs thinking, a director reacting, anything per-wave or per-minute |
+| Ends | when that call settles | at the player's limit, a Stop, or 24h |
+| Gesture | must run inside a click handler | none needed once the grant is active |
+
+A popup per NPC turn is not a feature, it is an interruption. More than a call
+or two per session means a grant.
+
+## Step 0 — is the lane live on this stand?
+
+```bash
+npx genex llm models
+```
+
+- **live** — it prints the models this stand serves. Build the feature.
+- **off on this stand** — the routes answer 404. Build the feature behind a
+  graceful `unavailable` state (the NPC uses its authored lines, the quest falls
+  back to the written one) and **say so plainly in the handoff**. Never promise
+  the player something that 404s.
+- **misconfigured** — say that too; it is an operator fix, not a game bug.
+
+Model ids come from that command and from `getGenerationModels()` at runtime.
+Never write one into the game's source: they differ per stand, and a hardcoded
+id is a feature that dies on somebody else's environment.
+
+## The SDK surface (exact — do not invent methods)
+
+From `@genex-ai/embed-sdk`, already installed. `initEmbed()` must have run and
+identity must be resolved first — `$genex-threejs-embed-auth`.
+
+- `getGenerationModels()` — the models this stand serves. Any picker renders
+  from this, never from a list you wrote.
+- `generate({ modelId, prompt, outputFormat, schema?, estimateCoins,
+  allowExternal?, idempotencyKey?, grantId?, timeoutMs? })` →
+  `{ status, generationId, output, source, error }` plus billing fields
+  (`billingStatus`, `reservedCoins`, `chargedCoins`, their display-USD twins).
+- `requestSpendGrant({ models, perCallMaxCoins, perCallEstimateCoins,
+  disclosure: { periodLabel, estimatedCallsPerPeriod, estimatedCoinsPerPeriod },
+  maxConcurrent?, maxCallsPerMinute?, allowExternal?, idempotencyKey? })` →
+  `{ status, grantId, … the limits the player approved }`; status is `active` |
+  `canceled` | `expired` | `failed` | `pending`.
+- `getSpendGrant(grantId)` — live state and counters; the ONE source for an
+  in-game budget readout.
+- `stopSpendGrant(grantId)` — the game's own stop door. Prospective: no further
+  calls are admitted, anything in flight drains and settles.
+- `waitForGeneration(id)` / `getGeneration(id)` — re-attach to a call already
+  started, including after a reload.
+- `generationErrorMessage(code)` — one player-facing sentence for an error code.
+
+```ts
+askButton.addEventListener('click', async () => {   // a real click
+  const res = await generate({                      // FIRST statement, no await before it
+    modelId, outputFormat: 'json', schema: ANSWER_SCHEMA,
+    prompt: askPrompt(npc, playerLine),
+    estimateCoins: NPC_CALL_PRICE,                  // benchmarked — see below
+    idempotencyKey: `npc:${npc.id}:${turnId}`,
+  });
+  applyGeneration(res);                             // the one writer — see below
+});
+```
+
+**`generate()` and `requestSpendGrant()` are the first statement of the click
+handler, before any `await`.** The approval popup is reserved synchronously off
+the gesture; an `await` in front of it loses the gesture and nothing opens.
+`generate({ grantId })` needs no gesture at all — that is what a grant buys.
+
+## `estimateCoins` is a price, not an estimate
+
+You declare it; the platform charges it. Declare 5 and 5 is charged — on a
+success, a failure, a cancel, and when the model stops at its budget. Only an
+attempt with no model work at all costs nothing. A number picked by feel is
+money taken from your players for nothing, or a call that cannot fund itself.
+
+**Benchmark, then declare:**
+
+```bash
+npx genex llm bench "<the real prompt, with a real example filled in>" \
+  --schema ./answer.schema.json --samples 3 --max-coins <n> --user-approved
+```
+
+It runs on **your own coins**, on the development lane, and prints what each
+sample actually charged plus the recommendation to declare: p95 of the charged
+coins with the server's own recommended headroom already applied. Declare that
+printed number. Never guess it, never work it out from a vendor's price list,
+never add a margin of your own. For a standing budget the run prints a second
+line, `Grant perCallMaxCoins`, and that one is `perCallMaxCoins` — declare it
+verbatim as well rather than deriving a ceiling from `max`, which lands under
+the price and makes `requestSpendGrant()` refuse before it reaches the network. Full procedure — reading p50/p95, turning the
+loop into disclosure numbers, re-benchmarking after a prompt change — is in
+[references/pricing.md](references/pricing.md).
+
+## Standing budgets
+
+```ts
+const grant = await requestSpendGrant({          // inside the click handler
+  models: [modelId],
+  perCallMaxCoins: NPC_CALL_CEILING,
+  perCallEstimateCoins: NPC_CALL_PRICE,
+  disclosure: {
+    periodLabel: 'minute',
+    estimatedCallsPerPeriod: 10,                 // 5 NPCs, one decision each per 30s
+    estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE,
+  },
+  maxConcurrent: 2,
+  maxCallsPerMinute: 30,
+});
+if (grant.status !== 'active') { runWithAuthoredLines(); return; }
+await savePlayerState({ ...state, grantId: grant.grantId });
+```
+
+**The disclosure is computed from this game's own loop, never wished for.** Five
+NPCs deciding once every thirty seconds is ten calls a minute — write that
+arithmetic into `DESIGN.md` beside the feature. The player sees your estimate
+attributed to the game, beside the platform's own worst case; an estimate that
+is transparently low is a grant that dies mid-session.
+
+**Then keep the burn low, because you wrote the loop:** batch those five NPCs
+into ONE call returning five decisions, cache a decision until the situation
+that caused it changes, pick the cheapest model that passes your own check, and
+never fire on a timer the player cannot see.
+
+Grant endings are ordinary game states with in-fiction copy, never an error toast:
+
+| code | what happened | what the game does |
+| --- | --- | --- |
+| `grant_limit_reached` | the approved limit is spent | authored behaviour returns; a button offers to re-request |
+| `grant_stopped` | the player pressed Stop | accept silently, keep playing |
+| `grant_expired` | 24h passed, or the session ended | as stopped; re-request on the next deliberate click |
+| `waiting_for_plan` | their own plan is rate-limited | wait out the stated time — not a failure, and there is no paid fallback |
+| `grant_insufficient_funds` | the wallet cannot fund the next call | pause the thinking NPCs, say it once, stay playable |
+
+Draw the readout from `getSpendGrant(grantId)` — calls made, coins settled, what
+remains — never from a counter the game keeps itself. A finished grant may be
+re-requested, but only from a **fresh deliberate click**: a silent auto-renew is
+the exact shape a standing approval exists to prevent.
+
+## The receiver pattern — one writer, two entry points
+
+A generation outlives the frame that asked for it; reloads and closed tabs land
+in the middle of one.
+
+```ts
+function applyGeneration(res) {     // THE only place output becomes game state
+  if (res.status !== 'succeeded') return showLine(generationErrorMessage(res.error));
+  const parsed = ANSWER.safeParse(res.output);   // validated against YOUR expectation
+  if (!parsed.success) return showLine("The voice trails off.");
+  speak(parsed.data.line);
+  savePlayerState({ ...state, pendingGenerationId: null });
+}
+```
+
+- The click path writes `generationId` into player state **before** awaiting.
+- Boot reads any stored id, calls `waitForGeneration(savedId)`, and passes the
+  result to the **same** `applyGeneration`. One writer, two entry points, is the
+  difference between "works once" and "survives a reload".
+- Output is **data, never authority**: it may not grant coin, items,
+  entitlements, scores or progression by saying so. `source: 'external'` carries
+  `modelProvenance: 'unverified'` because it is user-supplied — check it exactly
+  as you would check typed player input.
+
+## Errors land on the player's wallet
+
+There is no compensation lane, so this is all work you do before the call:
+
+- **Validate inputs first** — a malformed prompt is still charged.
+- **Always set `schema` for `outputFormat: 'json'`** — unschema'd JSON is the
+  commonest way a call is charged and the result is unusable.
+- **Keep prompts short.** Long context is the price.
+- **Never loop `generate()` without a grant**, and never retry in a loop — each
+  attempt is a separate charge.
+- **Map every code through `generationErrorMessage(code)`** into in-fiction
+  copy. A player should never read a raw error code inside your game.
+- **`status: 'unknown'` is not a failure.** It means the charge is not known
+  yet, billing pending. Say "still settling", keep the reserved figure in the
+  readout, re-read with `getGeneration(id)` — never call it failed, never retry.
+
+## What the Genex side already does — do not rebuild it
+
+The approval sheet shows the model, the prompt, the price and the terms; the
+game renders no price sheet. **Subscription funding is chosen only there** —
+never add a "Your plan" row to the game's model picker, because a game cannot
+offer a funding source. When the player's own watcher is online the personal-plan
+answer arrives by itself and the game just waits, exactly as it waits for a
+coin-funded call. The Genex dashboard header shows progress, active grants with
+their spend, and a Stop; a Stop pressed there reaches the game as `grant_stopped`.
+
+## Never
+
+- **Never execute returned output** — no `eval`, no dynamic import, no scene
+  graph or shader built from model text, no URL fetched because the output said so.
+- **Never bundle a creator credential in a game.** Benchmarking is a CLI action
+  on your machine, never something a shipped build does.
+- **Never hand-roll fetch to the runtime API** — the SDK owns the approval
+  handshake, and a hand-rolled call cannot obtain one.
+- **Never hardcode a price, a model id, a stand URL, or a margin.**
+- **Never let the model be an authority over money, items or rewards**
+  (`$genex-monetization` owns what may move a wallet).
+
+These are source contracts, not a claim that every stand runs this lane —
+`npx genex llm models` is what tells you.
+
+## Checklist
+
+- [ ] `npx genex llm models` was run and its verdict is in the handoff
+- [ ] Model ids come from `getGenerationModels()`, never from source
+- [ ] `estimateCoins` came from `npx genex llm bench`, not from judgement
+- [ ] `generate()` / `requestSpendGrant()` is the first statement of a click handler
+- [ ] A repeated-call feature uses a grant; a one-off uses `generate()`
+- [ ] Disclosure numbers derive from the real loop and are written in `DESIGN.md`
+- [ ] Calls are batched and cached; nothing fires on an invisible timer
+- [ ] Every grant-ending code has in-fiction copy and a playable fallback
+- [ ] The in-game readout comes from `getSpendGrant()`
+- [ ] Exactly one `applyGeneration()` writer; boot re-attaches with `waitForGeneration()`
+- [ ] `generationId` is saved BEFORE the await
+- [ ] Output is schema-validated and grants nothing by itself
+- [ ] `unknown` reads as "still settling", never as a failure
+- [ ] The game renders no price sheet and no funding picker
+
+## Troubleshooting
+
+**Everything on this lane 404s** — runtime generation is off on this stand.
+Nothing to fix in the game: ship the fallback and say so.
+
+**Nothing opens when the player clicks** — an `await` ran before `generate()`
+and the gesture was lost. Move the call to the first line of the handler.
+
+**`guest_no_wallet`** — guests play but hold no wallet. Show the feature as
+sign-in-to-use rather than hiding it (`$genex-threejs-embed-auth`).
+
+**`staging_no_generation`** — a `genex preview` build cannot spend real coin.
+Check the layout on the draft; check the call itself after `genex promote`.
+
+**`grant_price_unreasonable`** — the declared per-call price is far above what
+that prompt can cost on that model. Re-benchmark and declare what it prints.
+
+**`grant_concurrency` / `grant_rate_limited`** — the game calls faster than the
+grant's own limits. Batch and cache; do not raise the limits to hide it.
+
+**`grant_not_active`** — the saved `grantId` is finished. Clear the stored id
+and re-request from a fresh click.
+
+**`external_request_active`** — that player already has one personal-plan
+request running. Wait for it; never fall back to charging coin instead.
+
+**The call is charged but the result is unusable** — `outputFormat: 'json'`
+without a `schema`. Add one; the charge already happened.
+
+**A reload lost the answer** — `generationId` was not saved before the await, or
+boot never calls `waitForGeneration()`. Both halves are required.
+
+**The in-game readout disagrees with the Genex header** — the game is counting
+calls itself. Read `getSpendGrant()` instead.

package/templates/skills/genex-llm-in-games/references/pricing.md

@@ -0,0 +1,153 @@
+# Calibrate, then declare
+
+`estimateCoins` is the **fixed price of a started attempt**, not a guess about
+one. The platform charges exactly what you declare, whether the call succeeds,
+fails, is canceled, or stops at its own budget. There is one honest way to pick
+it: run the real prompt on your own coins, read what it charged, and declare the
+number the benchmark recommends.
+
+Never derive it from a model vendor's published rates. Three layers sit between
+that rate and what the player is charged — the provider's cost, the platform's
+tariff, and the headroom a declared price needs — and only the benchmark sees
+all three. A number worked out from the vendor's page silently drops the middle
+layer and under-prices every call you will ever make.
+
+## 1. Freeze the prompt first
+
+Benchmark the prompt you are actually shipping, with a realistic example filled
+in: the longest NPC memory you will pass, the fullest world snapshot, a player
+line of the length people really type. Short test prompts produce a cheap number
+that the real game then cannot fund.
+
+If the feature returns structured data, write the schema to a file now
+(`./answer.schema.json`) and benchmark with it. Schema'd JSON and free text do
+not cost the same, and shipping without a schema is the commonest way a call is
+charged for an unusable result.
+
+## 2. Run the benchmark
+
+```bash
+npx genex llm models        # which models this stand serves; pick candidates
+
+npx genex llm bench "<the frozen prompt, one real example filled in>" \
+  --model <id from the line above> \
+  --schema ./answer.schema.json \
+  --samples 3 \
+  --max-coins <n> --user-approved
+```
+
+- It spends **your** coins, on the development lane, through the CLI's own
+  credential. Nothing here runs in a shipped build.
+- `--max-coins <n> --user-approved` is a hard gate, refused before any network
+  call. That is the same shape as every other spend approval in the CLI: you
+  state the ceiling for this run, out loud, once.
+- `--samples 3` is the floor. The same prompt costs different amounts on
+  different runs, because the model's own output length varies.
+- `npx genex llm price` re-prints the last run's recommendation without spending
+  anything again.
+
+## 3. Read the output
+
+Each sample prints what it actually charged. The aggregate prints p50, p95 and
+max of the charged coins, plus one recommendation.
+
+- **p50** is what a typical call costs. It is the number to reason about when
+  you ask "can the game afford this loop?" — multiply it by the calls per
+  minute you are about to disclose.
+- **p95** is what a bad-but-normal call costs: a long answer, a model that
+  reasons its way around. It is the number to **declare**, because a declared
+  price below it means the unlucky calls cannot fund themselves and get refused
+  mid-session.
+- **max** is diagnostic. When max sits far above p95, the prompt has an
+  unbounded branch in it — usually an unconstrained list or a missing schema.
+  Fix the prompt rather than declaring a bigger number.
+
+The recommendation line already applies the **server's own recommended
+headroom** on top of p95. Declare that figure verbatim:
+
+```ts
+const NPC_CALL_PRICE = <the recommended figure>;    // from `npx genex llm bench`, <date>
+const NPC_CALL_CEILING = <the printed ceiling>;     // same run — grants only
+```
+
+Write the benchmark date and the model id beside it in `DESIGN.md`, so the next
+person knows what the number describes. Do not add a margin of your own on top
+of the recommendation, and do not round it down to look cheaper.
+
+For a grant, the run prints a **second** number beside the price: the ceiling,
+`perCallMaxCoins`. Declare that one verbatim too, and do not work it out by
+hand. It is emphatically NOT the benchmark's `max`: p95 is nearest-rank, so at
+the sample counts a benchmark actually takes, p95 and max are the same figure —
+a ceiling set from `max` therefore lands *below* the recommended price, and
+`requestSpendGrant()` refuses that pair before the request ever leaves the page.
+
+The invariant, which the SDK and the server both enforce:
+
+```
+perCallEstimateCoins  ≤  perCallMaxCoins  ≤  the limit the player approves
+```
+
+The ceiling is the price's room to be wrong, not a second price: no call is ever
+charged more than the price it declares, and the platform separately refuses any
+declared price out of proportion to what the model could really cost.
+
+## 4. Turn the game's loop into the disclosure
+
+A standing budget asks the player to approve a rate, so the numbers have to come
+from the loop you wrote, counted honestly:
+
+1. **Count the callers.** How many things call the model at once? Five thinking
+   NPCs, one director, one narrator.
+2. **Count each one's cadence.** How often does each decide? Once every thirty
+   seconds of play.
+3. **Multiply, and pick the period that makes the number legible.** Five NPCs at
+   one call per thirty seconds is ten calls a minute, so `periodLabel: 'minute'`
+   and `estimatedCallsPerPeriod: 10`.
+4. **Coins per period is calls × the declared price** —
+   `estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE`. Not the p50, not a hope: the
+   price you declare is the price charged.
+
+```ts
+disclosure: {
+  periodLabel: 'minute',
+  estimatedCallsPerPeriod: 10,
+  estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE,
+}
+```
+
+The player sees this attributed to your game — "the game estimates about …" —
+beside the platform's own worst case computed from `perCallMaxCoins`. The two
+being far apart is normal; the estimate being far below what the game really
+does is what breaks trust and burns the grant mid-session.
+
+**Batching changes this arithmetic more than any price tuning can.** Five NPCs
+answered by one call that returns five decisions is two calls a minute, not ten,
+and one benchmarked price for the batched prompt replaces five of the unbatched
+one. Do that before you reach for a cheaper model.
+
+## Worked example
+
+A tavern with five NPCs who react to what the player says. Each NPC decides once
+every thirty seconds; a decision is a short JSON object (a mood, one line of
+speech). The prompt carries the NPC's memory and the last two player lines.
+
+1. Freeze the prompt with a full memory and a long player line. Write
+   `./answer.schema.json` with the two fields.
+2. `npx genex llm bench "<that prompt>" --schema ./answer.schema.json
+   --samples 3 --max-coins <ceiling> --user-approved`.
+3. Read: p50 `<p50>`, p95 `<p95>`, max `<max>`, and the two printed
+   declarations — `Declare estimateCoins: <recommended>` and
+   `Grant perCallMaxCoins: <ceiling>`.
+4. Declare `NPC_CALL_PRICE = <recommended>` and
+   `NPC_CALL_CEILING = <ceiling>`, each verbatim from the line that printed it.
+5. Unbatched, the loop is ten calls a minute, so the disclosure is
+   `10` and `10 * <recommended>` coins per minute.
+6. Batch the five NPCs into one call — benchmark the batched prompt separately,
+   because it is a different prompt — and the disclosure becomes two calls a
+   minute at the batched price.
+7. Re-run steps 1–4 whenever the prompt, the schema or the model changes. A
+   prompt edit is a price change; treat it like one.
+
+Every `<placeholder>` above is read off your own benchmark run. None of these
+figures is a platform constant, and none of them should be copied from another
+game — a different prompt has a different price.