@genex-ai/cli-demo 1.35.1-dev.748 → 1.35.2-dev.749

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.35.1-dev.748",
+  "version": "1.35.2-dev.749",
   "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": {

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

@@ -36,6 +36,12 @@ budget, so a check every turn is affordable where a generate every turn is not.
 `generate()` for words, `judge()` for decisions; a feature often wants both —
 the judge picks the branch, generate writes the line.
 
+**Words the player watches appear? Stream them.** Dialogue, narration, an NPC's
+reply in a speech bubble: under a grant, `generateStream()` is the same call as
+`generate({ grantId })`, but the text arrives while the model writes it instead
+of all at once after it. Keep `generate()` for answers the game only uses whole
+(a quest object, a list of decisions) — nobody watches those being written.
+
 ## Step 0 — is the lane live on this stand?
 
 ```bash
@@ -89,6 +95,13 @@ identity must be resolved first — `$genex-threejs-embed-auth`.
   (`{ instructions, criteria: [levels, lowest first] }`) or `noul`
   (`{ instructions }`); each answer has its question's type, and `noul` is a
   probability — pick your own threshold. Needs a budget requested with `judge`.
+- `generateStream({ …the generate() options, grantId, onDelta?(text, soFar),
+  onPartialField?(name, partialText), signal? })` → the same result as
+  `generate()`. Grant-only. `onDelta` hands over each piece and all the text so
+  far; for `outputFormat: 'json'`, `onPartialField` reports the schema's FIRST
+  top-level string property as far as it is written — put the spoken line first
+  in the schema. `signal` stops the reading, never the call (it still finishes
+  and is charged).
 - `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
@@ -216,6 +229,27 @@ only, and judge calls share the budget's `maxConcurrent` and
 `maxCallsPerMinute`: batch questions into one call (up to 64) rather than one
 call per question.
 
+**Streaming a reply under the budget:**
+
+```ts
+const res = await generateStream({
+  grantId, modelId, outputFormat: 'json', schema: LINE_SCHEMA,   // `line` is its first property
+  prompt: npcPrompt(npc, playerLine), estimateCoins: NPC_CALL_PRICE,
+  idempotencyKey: `npc:${npc.id}:${turnId}`,
+  onPartialField: (_name, soFar) => npc.bubble.show(soFar),     // provisional
+});
+applyGeneration(res);                                            // the answer is THIS
+```
+
+The pieces are provisional: a call can still fail after text has shown (the
+model broke off, the JSON missed the schema), so the bubble shows them and
+`applyGeneration` decides what the game keeps — the same one writer as always.
+Price, benchmark and receipt are `generate()`'s: a started stream is charged its
+declared price even when the player walks away mid-sentence. A stream holds one
+of the budget's `maxConcurrent` slots until it has settled. Sometimes the reply
+arrives whole — a busy stand, a retried call, a budget on the player's own plan —
+and `onDelta` then gets the whole text once; the game needs no second path.
+
 **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
@@ -314,6 +348,7 @@ These are source contracts, not a claim that every stand runs this lane —
 - [ ] `generate()` / `requestSpendGrant()` is the first statement of a click handler
 - [ ] A repeated-call feature uses a grant; a one-off uses `generate()`
 - [ ] A decision (a label, a yes/no, a level) is a `judge()` question under the grant, not a `generate()` asked for a word
+- [ ] Dialogue the player watches appear uses `generateStream()` under the grant; the resolved result, not the pieces, goes to `applyGeneration()`
 - [ ] 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
@@ -354,6 +389,10 @@ the period (your own `estimatedCallsPerPeriod` at the largest size): wait, and
 if it keeps happening your declared rate is too low — fix the loop or the
 estimate, never retry in a tight loop.
 
+**`stream_requires_grant`** — `generateStream()` was called without a
+`grantId`. Streaming is grant-only: a one-time call waits on the player's
+approval popup, so use `generate()` for it.
+
 **`generation_limit`** — three ad-hoc calls are already in flight for this
 account, or recently stopped with their bill still pending; a pending call
 stops counting ten minutes after it was dispatched. From the bench: run