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

package/dist/index.js

@@ -916,12 +916,18 @@ var TOOLS_CONTRACT_OFFER = `5. **When the game is built and playable \u2014 neve
 var TOOLS_CONTRACT_HOSTED_LAWS = `5. **This game is hosted on Genex now, and publishing is glue \u2014 never a rebuild.** The game ships exactly as the user built it: \`initEmbed()\` first in the boot code (the \`genex-threejs-embed-auth\` card has the call; the renderer draws before any \`await waitForPlayer()\`), a static build into \`dist/\` with relative asset paths, then \`npx genex preview\`. Never restructure, reformat or "improve" the game to ship it, never scaffold a new app around it, and never start a design document or a build plan for it \u2014 the user's own process is theirs. Load the \`genex-tool-publish\` card before the first preview; it owns the vocabulary, the links and the limits.
 6. **Ship first, then report.** \`preview\` prints a preflight \u2014 phone memory, a missing volume slider, an asset nobody wired, a viewport line. It never blocks a deploy, so push the build as it is, hand over the link, THEN relay each preflight line to the user in one plain sentence with an offer to fix it, and fix one only on their yes. The preflight is a report for the user, not a to-do list for you.
 7. **The link is the game's page, and there are two versions.** After every preview give the user \`<dashboard>/draft/<slug>\` \u2014 \`dashboardOrigins[0]\` and \`slug\` from \`.genex/project.json\` \u2014 never localhost, a file path or the bare play origin. \`preview\` updates the draft and never touches what players are on; the first release is \`npx genex publish\` (it lists the game); after that "publish it", "update it" and "yes" all mean \`npx genex promote\` \u2014 the exact draft build, no rebuild. Ask once per round of work, in one line, and keep working while you wait.`;
+var TOOLS_CONTRACT_LLM_OFFER = `A model running while people play is built into the Genex platform \u2014 the player pays, with Genex coins or their own Claude/ChatGPT subscription, and approves it on a Genex sheet; your game just calls \`generate()\`. Want it that way?`;
+function toolsContractLlmLaw(n, hosted) {
+  const onYes = hosted ? "On a yes, load `$genex-tool-llm` and then `$genex-llm-in-games`, which owns the build." : "On a yes, load `$genex-tool-llm`, which owns the rest: it checks the lane with `npx genex llm models` first, then runs `npx genex init --convert` (a hosted game is a static browser build \u2014 a local server holding a key can never ship).";
+  return `${n}. **A model running while people PLAY is a platform feature \u2014 never something you wire onto the user's own meter.** When a request implies one (NPCs that talk or decide in their own words, content written from what the player types, a prompt box in the game, "let the player pick a model"), recognise it, say in ONE line: "${TOOLS_CONTRACT_LLM_OFFER}" \u2014 then ASK and wait. ${onYes} On a no, build the authored version instead. Either way, never ship a game that calls a model on a key or an account of the user's own: every visitor would spend their money with nobody approving it, and the credential is readable in the bundle. Player-funded generation is text and JSON only \u2014 3D, images, video and audio stay the asset lanes above, on the user's meter.`;
+}
 function toolsContractBlock(opts) {
   return `${CONTRACT_BEGIN}
 ${TOOLS_CONTRACT_HEAD}${opts.hosted ? " This game is also hosted on Genex: `preview` \xB7 `promote` \xB7 `publish` \xB7 `rollback` \xB7 `rename` work here (the `genex-tool-publish` card owns them)." : ""}
 
 ${TOOLS_CONTRACT_LAWS_1_TO_4}
 ${opts.hosted ? TOOLS_CONTRACT_HOSTED_LAWS : TOOLS_CONTRACT_OFFER}
+${toolsContractLlmLaw(opts.hosted ? 8 : 6, opts.hosted)}
 ${CONTRACT_END}
 `;
 }
@@ -1227,13 +1233,18 @@ async function hasGenexSkills(skillsDir) {
   }
 }
 var TOOL_SKILL_PREFIX = "genex-tool-";
-var HOSTED_TOOL_SKILLS = ["genex-tool-publish", "genex-threejs-embed-auth"];
+var HOSTED_TOOL_SKILLS = [
+  "genex-tool-publish",
+  "genex-threejs-embed-auth",
+  "genex-llm-in-games"
+];
 var REMIX_EXCLUDED_SKILLS = [
   "genex-game-director",
   "genex-getting-started",
   "genex-tool-audio",
   "genex-tool-character",
   "genex-tool-image",
+  "genex-tool-llm",
   "genex-tool-model",
   "genex-tool-publish",
   "genex-tool-texture",
@@ -23278,8 +23289,13 @@ import fs33 from "fs/promises";
 import path34 from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 var SUBS3 = ["models", "bench", "price"];
-var LLM_BENCH_APPROVAL_REQUIRED = "STOP: `genex llm bench` runs the real model and spends the player's COIN \u2014 a wallet this build's asset allowance cannot see. Re-run with --max-coins <n> --user-approved only after they agreed to the number.";
+var LLM_BENCH_APPROVAL_REQUIRED = "STOP: `genex llm bench` runs the real model and spends YOUR OWN coin \u2014 your wallet, not a player's, and one this build's asset allowance cannot see. Re-run with --max-coins <n> --user-approved only after the person at the keyboard agreed to the number.";
 var LLM_LANE_OFF_LINE = "The runtime LLM lane is off on this stand \u2014 in-game generate() answers 404 here, and nothing can be benchmarked.";
+var LLM_TOOLS_CONVERT_HINT = [
+  "In-game model calls need a hosted game. This folder is a Genex Tools workspace, so nothing here",
+  "can call a model at play time yet \u2014 and the player, not you, is who pays for one that does.",
+  "Ask the user first; on their yes run `npx genex init --convert`, then load the genex-tool-llm card."
+];
 var LLM_BENCH_FILE = ".genex/llm-bench.json";
 var DEFAULT_BENCH_SAMPLES = 3;
 var DEFAULT_SAMPLE_TIMEOUT_SEC = 180;
@@ -23345,6 +23361,8 @@ async function runLlm(opts = {}) {
     await reportSavedPrice(cwd, opts, log);
     return;
   }
+  const ws = await resolveWorkspace(cwd);
+  const toolsOnly = ws.mode === "tools" && !ws.hosted;
   if (sub === "bench") {
     if (opts.maxCoins === void 0 || opts.userApproved !== true) {
       fail4("llm bench", LLM_BENCH_APPROVAL_REQUIRED);
@@ -23362,10 +23380,13 @@ async function runLlm(opts = {}) {
       fail4("llm bench", "Pass --json-output or --text, not both.");
       return;
     }
-    const ws = await resolveWorkspace(cwd);
-    if (ws.mode === "tools" && !ws.hosted) {
+    if (toolsOnly) {
       if (opts.json) writeJsonLine({ command: "llm bench", status: "failed", error: "`genex llm bench` is not part of Genex Tools." });
-      else reportPlatformRefused(log, "llm bench");
+      else {
+        reportPlatformRefused(log, "llm bench");
+        log.plain(`  ${c.cyan("\u2192")} A model that runs while people PLAY is a platform feature: the player pays and approves it.`);
+        log.plain(`    Ask the user, and on their yes: ${c.cyan("npx genex init --convert")} \u2014 then the ${c.cyan("genex-tool-llm")} card.`);
+      }
       process.exitCode = 1;
       return;
     }
@@ -23408,12 +23429,12 @@ async function runLlm(opts = {}) {
     await writeUserToken(token, opts.envPath, apiUrl);
   }
   if (sub === "models") {
-    await reportModels(apiUrl, token, opts, log);
+    await reportModels(apiUrl, token, opts, log, toolsOnly);
     return;
   }
   await runBench({ apiUrl, token, projectId: meta.id, cwd, opts, log });
 }
-async function reportModels(apiUrl, token, opts, log) {
+async function reportModels(apiUrl, token, opts, log, toolsOnly = false) {
   const probe = await apiFetch(`${apiUrl}/api/runtime/models`, {
     headers: { Authorization: `Bearer ${token}` }
   }).catch(() => null);
@@ -23435,7 +23456,8 @@ async function reportModels(apiUrl, token, opts, log) {
         enabled: null,
         models: null,
         externalProviders: null,
-        recommendedDeclaredHeadroomBps: null
+        recommendedDeclaredHeadroomBps: null,
+        convertHint: toolsOnly ? LLM_TOOLS_CONVERT_HINT.join(" ") : null
       });
     }
     process.exitCode = 1;
@@ -23450,22 +23472,33 @@ async function reportModels(apiUrl, token, opts, log) {
       enabled: lane.state === "live",
       models: lane.models,
       externalProviders: lane.externalProviders,
-      recommendedDeclaredHeadroomBps: lane.recommendedDeclaredHeadroomBps
+      recommendedDeclaredHeadroomBps: lane.recommendedDeclaredHeadroomBps,
+      // Always present, `null` off a tools workspace — the same
+      // every-key-always-present rule the other keys follow, so a reader can
+      // tell "no hint" from "a CLI that predates the hint".
+      convertHint: toolsOnly ? LLM_TOOLS_CONVERT_HINT.join(" ") : null
     });
     if (lane.state === "unknown") process.exitCode = 1;
     return;
   }
+  const printConvertHint = () => {
+    if (!toolsOnly) return;
+    log.plain("");
+    for (const line of LLM_TOOLS_CONVERT_HINT) log.dim(`  ${line}`);
+  };
   log.plain(c.bold("genex llm models"));
   log.dim(`  ${apiUrl}`);
   log.plain("");
   if (lane.state === "off") {
     log.plain(`  ${LLM_LANE_OFF_LINE}`);
     log.dim("  Build the feature without an in-game model, or ask the operator to turn the lane on.");
+    printConvertHint();
     return;
   }
   if (lane.state === "unavailable") {
     log.warn("  This stand has the lane on but cannot serve its model list.");
     log.dim("  That is a server configuration problem, not yours \u2014 nothing here can be benchmarked yet.");
+    printConvertHint();
     return;
   }
   if (lane.state === "unknown" || !lane.models) {
@@ -23490,6 +23523,10 @@ async function reportModels(apiUrl, token, opts, log) {
   } else {
     log.dim(`  Recommended headroom over benchmarked coins on this stand: ${lane.recommendedDeclaredHeadroomBps} bps.`);
   }
+  if (toolsOnly) {
+    printConvertHint();
+    return;
+  }
   log.dim("  Those per-million rates are the PROVIDER's; what your game is charged is the platform");
   log.dim(`  tariff on top, which only a real call reveals: ${c.cyan('genex llm bench "<prompt>" --max-coins <n> --user-approved')}`);
 }
@@ -23935,7 +23972,7 @@ async function runDoctor(opts = {}) {
   }
   rows.push(termsRow(authState, legal));
   rows.push(creditsRow(authState, credits));
-  rows.push(runtimeRow(authState, runtime));
+  rows.push(runtimeRow(authState, runtime, mode === "tools"));
   if (opts.json) {
     process.stdout.write(
       JSON.stringify(
@@ -24096,15 +24133,16 @@ function creditsRow(state, info) {
     fix: info.balance <= 0 ? "Out of credits \u2014 generation is refused until the refill or a top-up." : void 0
   };
 }
-function runtimeRow(state, lane) {
+function runtimeRow(state, lane, toolsOnly = false) {
   if (state !== "ok") return { label: "Runtime", value: "\u2014 (sign in first)" };
+  const convertFix = "In-game calls need a hosted game, and the PLAYER pays for them \u2014 ask the user, then `npx genex init --convert`; the genex-tool-llm card has the offer to make.";
   switch (lane?.state) {
     case "live": {
       const n = lane.models?.length ?? 0;
       return {
         label: "Runtime",
         value: `in-game LLM lane live \xB7 ${n} model${n === 1 ? "" : "s"}`,
-        fix: 'Price a call before a game declares one: `npx genex llm bench "<prompt>" --max-coins <n> --user-approved`.'
+        fix: toolsOnly ? convertFix : 'Price a call before a game declares one: `npx genex llm bench "<prompt>" --max-coins <n> --user-approved`.'
       };
     }
     case "off":
@@ -26729,8 +26767,8 @@ ${c.bold("Usage")}
                                      Run the real model <n> times through the development
                                      lane and report what each attempt was CHARGED. Refused
                                      without both flags, before any network call: this spends
-                                     COIN, a wallet the build's asset allowance cannot see.
-                                     Needs a folder linked to a game you own.
+                                     YOUR OWN COIN, a wallet the build's asset allowance
+                                     cannot see. Needs a folder linked to a game you own.
   genex llm price [--json]           The recommendation from the last bench in this folder.
                                      Reads a file; spends nothing.
 
@@ -26739,8 +26777,9 @@ ${c.bold("Bench options")}
   --samples <n>        How many real attempts (default ${DEFAULT_BENCH_SAMPLES}). More samples, better p95.
   --schema <file>      A JSON file holding the output schema; implies JSON output.
   --json-output        Ask for JSON without a schema.   --text  Ask for text (the default).
-  --max-coins <n>      The per-attempt ceiling the player approved. The run's worst case is
-                       that number times --samples, and it is printed before anything starts.
+  --max-coins <n>      The per-attempt ceiling YOU approved \u2014 a bench runs on your own coin,
+                       never a player's. The run's worst case is that number times --samples,
+                       and it is printed before anything starts.
   --timeout <seconds>  Bounds the wait for each attempt.
   --json               One machine-readable object; every key is always present, null when
                        the CLI could not learn it.
@@ -26749,10 +26788,12 @@ ${c.bold("Why a benchmark and not an estimate")}
   \`estimateCoins\` is a PRICE, not a guess: declaring it charges it, in full, even when the
   attempt fails, is cancelled, or stops at its budget. And three layers sit between the
   provider's rate card and that number \u2014 the provider's cost, the platform's tariff (already
-  inside every charged coin), and your headroom. Adding a margin to the provider's rate
-  silently drops the tariff and under-prices every call, so the recommendation is built from
-  CHARGED COINS and the headroom comes from the server. A stand that serves no headroom gets
-  no recommendation, because the multiplier is not the CLI's to invent.
+  inside every charged coin), and your headroom. The bench itself is billed to YOU, on the
+  development lane; the player-funded lane is what the published game uses. Adding a margin
+  to the provider's rate silently drops the tariff and under-prices every call, so the
+  recommendation is built from CHARGED COINS and the headroom comes from the server. A stand
+  that serves no headroom gets no recommendation, because the multiplier is not the CLI's to
+  invent.
 
   Results land in ${LLM_BENCH_FILE} \u2014 gitignored, machine-local, re-read by \`genex llm price\`.
 `,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.35.0-dev.736",
+  "version": "1.35.0-dev.737",
   "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

@@ -243,11 +243,15 @@ 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`.
+**`player_wallet_required`** — ONE code for the two early dead ends: the lane
+refuses a guest and a PREVIEW build on the same line. `waitForPlayer()` tells
+them apart. `guest: true` — guests play but hold no wallet, so show the feature
+as sign-in-to-use rather than hiding it (`$genex-threejs-embed-auth`). Signed
+in and still refused — this is a `genex preview` draft, which never spends:
+check the layout there, and the call itself only after `genex promote`. The
+SDK's stock sentence for this code is "Sign in to Genex to use this", which is
+right for the guest and wrong on a draft, so write the in-fiction line per
+cause rather than showing it for both.
 
 **`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.

package/templates/skills/genex-tool-llm/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: genex-tool-llm
+description: A language model running while somebody PLAYS the finished game — an NPC that answers in its own words, a quest written from what the player typed, a prompt box in the game. On Genex the player pays and approves it, so this is a platform feature, never a key on the author's meter. Read this the moment a request implies a model at play time, before building anything.
+---
+
+# Genex Tools · Models at play time
+
+This card is about a model that runs **while somebody plays the finished game**
+— not about generating art while you build it. "Make me a picture, a model, a
+voice line" is the asset belt: use the lane card for it and stay here only if a
+model has to run for the player.
+
+## What the platform does
+
+A game hosted on Genex can call a language model from inside the running game
+and get back text or JSON. **The player pays and the player approves**: coins
+from their Genex wallet, or their own Claude / ChatGPT subscription, chosen on
+an approval sheet Genex draws that the game cannot render, skin or bypass.
+Either one call at a time, or one standing budget the player approves once and
+the game then spends against without another popup. The game holds no provider
+key, sees no credential, and never talks to a model vendor.
+
+That is the whole reason this is a platform feature and not something you wire
+up here: an unhosted folder has nowhere to put a key that is not the author's
+own.
+
+## Recognise the request
+
+Any of these means a model at PLAY time, however it is phrased:
+
+- NPCs that talk, answer, argue, or decide in their own words
+- anything written from what the player types — a name, a wish, a command, a question
+- a prompt box, a chat panel, an "ask the oracle" widget inside the game
+- quests, items, dialogue, or levels generated per save or per run
+- "let the player choose a model", "use my API key in the game", "hook a chatbot into it"
+- a judge, a grader, or a referee that reads free-form player input
+
+## Offer it in one line, then ASK
+
+Say this and stop:
+
+> A model running while people play is built into the Genex platform — the
+> player pays, with Genex coins or their own Claude/ChatGPT subscription, and
+> approves it on a Genex sheet; your game just calls `generate()`. Want it
+> that way?
+
+Wait for the answer. Do not start building either version first, and do not
+expand the offer into a pitch — one line, one question.
+
+## On a yes
+
+1. `npx genex llm models` — whether this stand serves the lane at all, and
+   which models. It answers in this folder as it is, before anything is
+   converted, so it comes first: if it says the lane is off, in-game calls
+   answer 404 here — tell the user so plainly, build the graceful fallback, and
+   do not convert a folder for a feature the stand does not serve.
+2. `npx genex init --convert` — it connects this folder to a hosted Genex game
+   in place. The code, the files and this toolkit stay exactly as they are, and
+   generations still land in `./assets`. It is the user's yes that runs it, so
+   ask before you do if you have not already.
+3. Load `$genex-llm-in-games` — it arrives with the conversion and owns the
+   build: the SDK surface, one-time calls versus a standing budget, measuring
+   the price before the game declares it, and honest handling of every refusal.
+
+**The game has to be a static browser build.** A hosted game is files served
+from the edge; there is no server of yours inside it. So the familiar pattern —
+a small local Express/Flask app that holds a key and proxies the model — works
+on your machine and can never ship. Calling `generate()` from the browser is
+the shipping shape of that idea.
+
+## On a no
+
+Then build nothing that calls a model at play time. Not a key in `.env`, not a
+local proxy, not the author's own account behind a fetch. A shipped game
+carrying the author's credential means every visitor spends the author's money,
+with nobody approving anything and no limit on it — and the credential is
+readable in the bundle. Say that in one plain sentence, then build the authored
+version instead: a written dialogue tree, a table of lines, a rule-based
+director. Those are not consolation prizes; they are what most good games use.
+
+## The honest boundary — text and JSON only
+
+Player-funded generation returns **text or JSON**. Nothing else.
+
+- **"The player types anything and gets a 3D model, paid by them"** is not a
+  thing on this platform. Say so plainly instead of half-building it.
+- 3D models, images, textures, video, music, voice and characters are the ASSET
+  lanes of this toolkit: you generate them while you build, on the user's own
+  meter, and they download into `./assets` and ship inside the game. What is
+  live and what it costs: `npx genex doctor`.
+- The shape that does work is **JSON parameters, then render**: the model
+  returns a structured description and the game builds it from assets and code
+  you already shipped — a creature assembled from parts you generated, a room
+  laid out from a list of prefab ids, a palette, a stat block, a line delivered
+  from pre-generated voice clips. Offer that when somebody asks for the
+  impossible version.

package/templates/skills/genex-tool-workflow/SKILL.md

@@ -8,6 +8,9 @@ description: How Genex Tools works across every lane — `npx genex doctor` to c
 The rules that apply to every lane. The per-lane cards are
 `$genex-tool-model`, `$genex-tool-image`, `$genex-tool-video`,
 `$genex-tool-texture`, `$genex-tool-audio`, `$genex-tool-character`.
+`$genex-tool-llm` is the odd one out: it is not a generation lane at all but
+the door for a model that runs while somebody PLAYS the finished game — read it
+the moment a request implies one.
 
 ## Check before you promise
 
@@ -92,8 +95,10 @@ tiling floor and three paid assets nobody loaded.
 
 Hosting, publishing, multiplayer, remixing and custom domains are the Genex
 platform, not this toolkit — those commands are refused in this folder by
-design, and the refusal says where they live. This workspace generates assets
-for a game you build and ship yourself. When the user wants that game live on
-Genex with its own URL, the AGENTS.md rules say how to offer it; on a yes the
-folder is connected to a hosted game in place — same cards, same rules — and
-the `$genex-tool-publish` card arrives with the publishing commands.
+design, and the refusal says where they live. So is a model that runs while
+somebody plays the finished game: that one is player-funded and needs a hosted
+game, and `$genex-tool-llm` owns how to offer it. This workspace generates
+assets for a game you build and ship yourself. When the user wants that game
+live on Genex with its own URL, the AGENTS.md rules say how to offer it; on a
+yes the folder is connected to a hosted game in place — same cards, same rules
+— and the `$genex-tool-publish` card arrives with the publishing commands.