@maka/maka-cli 5.191.0 → 5.192.0

package/bundle/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.191.0",
+  "version": "5.192.0",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-chunks.js

@@ -704,7 +704,7 @@ fixed, as is its "kind"):
 
 ${JSON_ONLY}
 [ { "name": string, "description": string, "code"?: string, "openMessage": string,
-    "refuseMessage": string, "guardsExit"?: string, "footprint"?: string } ]
+    "refuseMessage": string, "guardsExit"?: string, "footprint"?: string } ]${chunkEnvelopeNote('devices')}
 One entry per skeleton device, "name" copied exactly.${repairNote(previousError)}
 `.trim();
 }
@@ -753,10 +753,103 @@ amounts, not credentials.
 ${JSON_ONLY}
 [ { "name": string, "description": string, "size": string, "category": string,
     "shape": string, "color": string, "texture": string, "rating": string, "weight": number,
-    "currencyAmount"?: number, "details"?: string, "transferable"?: boolean } ]
+    "currencyAmount"?: number, "details"?: string, "transferable"?: boolean } ]${chunkEnvelopeNote('items')}
 One entry per skeleton item, "name" and "category" copied exactly.${repairNote(previousError)}
 `.trim();
 }
+/**
+ * SCHEMA-CONSTRAINED CHUNKS (user ruling 2026-09-14, after
+ * po7qSJycJrcfWbgaA put the generator's retry budget under a light).
+ *
+ * The expensive path in this generator is a REPAIR ROUND, and a good
+ * share of them are bought by a reply that was not valid JSON at all --
+ * "four of six whole-scene attempts died on Unterminated string in
+ * JSON", and 32 validation-errors in a single hour of production
+ * captures. A response schema (AI.ask's `jsonSchema` ->
+ * output_config.format) makes that fault impossible rather than
+ * catchable: the model cannot emit a shape that does not parse.
+ *
+ * ONLY TWO OF THE FOUR CHUNKS ARE HERE, and the reason is structural
+ * rather than a lack of appetite. The API requires every object in the
+ * schema to carry `additionalProperties: false`, and:
+ *
+ *   rooms -- carries `npcSpots`, `itemSpots` and `exitSpots`, which are
+ *            MAPS with arbitrary keys (a room's own spot names). A map
+ *            cannot both accept unknown keys and forbid them.
+ *   npcs  -- carries `combat`, deliberately open ("optional flavor for
+ *            defined concepts"), same problem.
+ *
+ * Constraining those two would mean freezing vocabularies that are
+ * meant to be open, which is a worse trade than leaving them on the
+ * existing prompt-plus-validator path. devices and items are flat,
+ * fully enumerable, and between them carry half the generator's output
+ * budget (3000 + 6000 of 18000 detail tokens) and the most entries.
+ *
+ * WHETHER THE PROVIDER TAKES IT AT ALL IS DISCOVERED, NOT ASSUMED --
+ * see AI.schemaSupport. A refusal costs one retried call, once, and
+ * then this is skipped for the life of the process.
+ */
+export const CHUNK_ENVELOPE_KEY = 'entries';
+/** The schema wants an OBJECT at the root, and these chunks are arrays
+ *  -- so every schema'd chunk answers as one object with a single
+ *  array under this key. The prompt says so too (chunkEnvelopeNote), so
+ *  the shape is the same whether or not the schema actually rode. */
+function arrayEnvelope(entry) {
+    return {
+        type: 'object',
+        properties: { [CHUNK_ENVELOPE_KEY]: { type: 'array', items: entry } },
+        required: [CHUNK_ENVELOPE_KEY],
+        additionalProperties: false,
+    };
+}
+const str = { type: 'string' };
+export const CHUNK_SCHEMAS = {
+    devices: arrayEnvelope({
+        type: 'object',
+        properties: {
+            name: str, description: str, code: str,
+            openMessage: str, refuseMessage: str,
+            guardsExit: str, footprint: str,
+        },
+        required: ['name', 'description', 'openMessage', 'refuseMessage'],
+        additionalProperties: false,
+    }),
+    items: arrayEnvelope({
+        type: 'object',
+        properties: {
+            name: str, description: str, size: str, category: str,
+            shape: str, color: str, texture: str, rating: str,
+            weight: { type: 'number' },
+            currencyAmount: { type: 'number' },
+            details: str,
+            transferable: { type: 'boolean' },
+        },
+        required: ['name', 'description', 'size', 'category', 'shape', 'color', 'texture', 'rating', 'weight'],
+        additionalProperties: false,
+    }),
+};
+/** The line that tells the model about the envelope above. Only added
+ *  to chunks that have a schema, so the other two keep asking for the
+ *  bare array they have always returned. */
+export function chunkEnvelopeNote(label) {
+    return CHUNK_SCHEMAS[label]
+        ? `\nReturn ONE object with a single key "${CHUNK_ENVELOPE_KEY}" whose value is that array: { "${CHUNK_ENVELOPE_KEY}": [ ... ] }`
+        : '';
+}
+/**
+ * The array a chunk reply carries, however it was wrapped. Tolerant on
+ * purpose: the schema forces the envelope, but the schema is skipped
+ * for providers that refuse it, and a bare array is what this
+ * generator has always accepted. One reader, both shapes.
+ */
+export function unwrapChunk(parsed, label) {
+    if (Array.isArray(parsed))
+        return parsed;
+    const envelope = parsed?.[CHUNK_ENVELOPE_KEY];
+    if (Array.isArray(envelope))
+        return envelope;
+    throw new Error(`The "${label}" chunk came back as neither an array nor a { "${CHUNK_ENVELOPE_KEY}": [...] } object.`);
+}
 // ========================= Parse / validate / assemble ====================
 /**
  * Can anyone at this table unweave a WARD?

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-seed-generator.js

@@ -9,7 +9,7 @@ import { GenerationCapture } from '../utilities/generation-capture.js';
 import { fetchCanonContext } from '../utilities/canon-lore.js';
 import { providerUnavailable } from '../utilities/draft-failure-note.js';
 import { SceneSynthesizer } from './scene-factory.js';
-import { buildSkeletonPrompt, buildRoomsPrompt, buildNpcsPrompt, buildDevicesPrompt, buildItemsPrompt, pickRunType, parseJsonReply, validateSkeleton, normalizeSkeleton, assembleScene, classifyRepair, VAULT_HOST_RATING, } from './scene-chunks.js';
+import { buildSkeletonPrompt, buildRoomsPrompt, buildNpcsPrompt, buildDevicesPrompt, buildItemsPrompt, pickRunType, parseJsonReply, validateSkeleton, normalizeSkeleton, assembleScene, classifyRepair, CHUNK_SCHEMAS, unwrapChunk, VAULT_HOST_RATING, } from './scene-chunks.js';
 // The fixer name convention and the player dossier live with the prompt
 // builders now (see scene-chunks.ts); re-exported so the existing
 // import sites (call.ts, game.ts) keep working unchanged.
@@ -207,9 +207,26 @@ export class SceneSeedGenerator {
     /** The skeleton pass: structure only, fast-validated before any detail pass builds on it. */
     static async requestSkeleton(tier, player, logger, pipeline, previousError, rumor, crew, canonBlock, runType = 'standard') {
         let lastError = previousError;
+        // Decided ONCE, before any prompt is built: the canon block either
+        // rides as a cached system prefix or stays interpolated in the
+        // prompt, and it must do exactly one of the two.
+        const cacheable = AI.cachesPrefix('generation');
         for (let attempt = 1; attempt <= this.maxCallAttempts; attempt++) {
-            const prompt = buildSkeletonPrompt(tier, player, lastError, rumor, crew, canonBlock, runType);
-            const reply = await AI.ask(prompt, { maxTokens: this.SKELETON_TOKENS, timeoutMs: AI.GENERATION_TIMEOUT_MS });
+            const prompt = buildSkeletonPrompt(tier, player, lastError, rumor, crew, cacheable ? undefined : canonBlock, runType);
+            const reply = await AI.ask(prompt, {
+                maxTokens: this.SKELETON_TOKENS,
+                timeoutMs: AI.GENERATION_TIMEOUT_MS,
+                workload: 'generation',
+                // THE CANON BLOCK IS THE ONE PREFIX WORTH CACHING HERE: ~4KB of
+                // book excerpts, byte-identical across both call attempts and
+                // all three pipeline retries. Sent as a cached system block when
+                // the provider supports caching -- and interpolated into the
+                // prompt the old way when it does not, which is why the caller
+                // decided that BEFORE building the prompt (see requestSkeleton's
+                // `cacheable`). Handing a cached prefix to a provider that drops
+                // it would take the canon out of the request entirely.
+                ...(cacheable && canonBlock ? { cachedPrefix: canonBlock } : {}),
+            });
             try {
                 const skeleton = parseJsonReply(reply);
                 skeleton.devices = skeleton.devices ?? [];
@@ -252,9 +269,19 @@ export class SceneSeedGenerator {
             const fullPrompt = lastError
                 ? `${prompt}\n\nYour previous attempt failed with this error -- fix it and try again: ${lastError}`
                 : prompt;
-            const reply = await AI.ask(fullPrompt, { maxTokens, timeoutMs: AI.GENERATION_TIMEOUT_MS });
+            const reply = await AI.ask(fullPrompt, {
+                maxTokens,
+                timeoutMs: AI.GENERATION_TIMEOUT_MS,
+                workload: 'generation',
+                // Absent for the two chunks whose shapes cannot be schema'd --
+                // see CHUNK_SCHEMAS for which, and why.
+                ...(CHUNK_SCHEMAS[label] ? { jsonSchema: CHUNK_SCHEMAS[label] } : {}),
+            });
             try {
-                const parsed = parseJsonReply(reply);
+                // Bare array or { entries: [...] } -- the schema forces the
+                // envelope where it rode, and a provider that refused one still
+                // answers the way it always did.
+                const parsed = unwrapChunk(parseJsonReply(reply), label);
                 logger.write(`SceneSeedGenerator: chunk "${label}" ok (attempt ${attempt})`);
                 // Positives matter as much as negatives: capturing only the
                 // failures would leave the detail stages contributing nothing

package/bundle/typescript/src/tools/ai/ai.class.js

@@ -28,18 +28,52 @@ function readPersistedKeys() {
         return {};
     }
 }
+/**
+ * Per provider, per workload. Only the ANTHROPIC row actually splits --
+ * and that is a fact about what this project knows, not a judgement
+ * about the others:
+ *
+ *   openai   -- gpt-4.1 for both. A cheaper OpenAI model surely exists;
+ *               naming one I have not priced would be guessing at a
+ *               billing decision, which is how you end up rotating a
+ *               working key over a queue backlog. Set
+ *               MAKA_AI_MODEL_DIALOGUE if you know the one you want.
+ *   deepseek -- v4-flash IS the cheap tier; there is nothing to split.
+ *   server   -- the relay enforces its own allowlist, so a split here
+ *               would be a request the server is free to ignore.
+ */
 const DEFAULT_MODELS = {
-    openai: 'gpt-4.1',
-    anthropic: 'claude-sonnet-5',
+    openai: { dialogue: 'gpt-4.1', generation: 'gpt-4.1' },
+    anthropic: {
+        // Haiku 4.5 at $1/$5 per MTok against Sonnet 5's $2/$10 -- half
+        // price for a line of bar chatter. 200K context rather than 1M,
+        // which no dialogue prompt in this game comes close to.
+        dialogue: 'claude-haiku-4-5',
+        // Deliberately NOT downgraded. See the workload note above: this is
+        // the path where a cheaper model bills you twice.
+        generation: 'claude-sonnet-5',
+    },
     // DeepSeek is reached over its ANTHROPIC-compatible endpoint (see
     // HTTPS.askDeepSeek), so a claude-* name would also work -- DeepSeek
     // remaps it -- but naming the real model keeps the HUD and logs
     // honest about what actually answered.
-    deepseek: 'deepseek-v4-flash',
+    deepseek: { dialogue: 'deepseek-v4-flash', generation: 'deepseek-v4-flash' },
     // The relay proxies on the server's own key; the server enforces its
     // own model allowlist regardless of what rides up.
-    server: 'claude-sonnet-5',
+    server: { dialogue: 'claude-sonnet-5', generation: 'claude-sonnet-5' },
 };
+/**
+ * The model for a provider and workload, honouring the overrides in
+ * precedence order: the workload-specific env var, then the global one
+ * (kept so an existing MAKA_AI_MODEL keeps meaning exactly what it
+ * meant -- pinning every call to one model), then the table.
+ */
+export function modelFor(provider, workload) {
+    const specific = workload === 'dialogue'
+        ? process.env.MAKA_AI_MODEL_DIALOGUE
+        : process.env.MAKA_AI_MODEL_GENERATION;
+    return specific || process.env.MAKA_AI_MODEL || DEFAULT_MODELS[provider][workload];
+}
 /**
  * Single entry point for every AI-backed feature in the app (currently the
  * sideQuest game's dynamic scene/dialogue generation). Picks a provider
@@ -90,7 +124,7 @@ export class AI {
      * `maka set:global-config --openai`/`--anthropic`, so a one-off env
      * var can still override a saved default for a single session.
      */
-    static resolveConfig() {
+    static resolveConfig(workload = 'dialogue') {
         const persisted = readPersistedKeys();
         const explicit = process.env.MAKA_AI_PROVIDER?.toLowerCase();
         const openaiKey = process.env.OPENAI_API_KEY || persisted.openai;
@@ -140,7 +174,7 @@ export class AI {
         return {
             provider,
             apiKey,
-            model: process.env.MAKA_AI_MODEL || DEFAULT_MODELS[provider],
+            model: modelFor(provider, workload),
         };
     }
     static isConfigured() {
@@ -398,21 +432,106 @@ export class AI {
      * it explicitly.
      */
     static GENERATION_TIMEOUT_MS = 90_000;
+    /**
+     * TWO OPTIONS THAT ONLY ANTHROPIC GETS, and the gate is deliberate.
+     *
+     * `cachedPrefix` -- text to send as a cached system block. Caching is
+     * a PREFIX match, so this is for the part of a prompt that repeats
+     * across calls: the generator's canon-lore block rides all five chunk
+     * requests and every pipeline retry unchanged. A cache read bills
+     * about a tenth of an input token.
+     *
+     * `jsonSchema` -- constrains the reply to a schema
+     * (output_config.format), so a malformed or truncated JSON answer
+     * stops being possible rather than being caught and retried. That is
+     * the point: the generator's expensive path is a repair round, and
+     * this deletes the fault that drives most of them.
+     *
+     * WHY ANTHROPIC ONLY. Both are Anthropic request fields. DeepSeek is
+     * reached over its Anthropic-COMPATIBLE endpoint, and compatible
+     * endpoints routinely implement the message shape and not the extras
+     * -- an unknown field may be ignored, or may 400 the whole call, and
+     * 400-ing every scene generation to save input tokens is not a trade
+     * worth making blind. OpenAI has its own spelling for both
+     * (`response_format`, automatic caching) which this has not verified.
+     * So they ride where they are known to work, and everywhere else the
+     * call goes out exactly as it did before.
+     */
+    static supportsRequestExtras(provider) {
+        return provider === 'anthropic';
+    }
+    /** Will a prefix handed to `ask` actually be cached for this workload?
+     *  Callers need this BEFORE building the prompt: a cached prefix that
+     *  gets dropped for an unsupported provider would take its content
+     *  out of the request entirely, so the caller has to know whether to
+     *  interpolate it the old way instead. */
+    static cachesPrefix(workload = 'generation') {
+        const config = this.resolveConfig(workload);
+        return !!config && this.supportsRequestExtras(config.provider);
+    }
+    /**
+     * DOES THIS PROVIDER HONOUR A RESPONSE SCHEMA? Discovered, not
+     * assumed -- the same posture as `serverAccess` above, and for the
+     * same reason: guessing wrong is not a degraded feature, it is a 400
+     * on every scene generation.
+     *
+     * `output_config.format` is documented for the Anthropic API, but two
+     * things can still refuse it in the field -- a compatible endpoint
+     * that implements the message shape and none of the extras, and a
+     * schema this code wrote that the validator reads more strictly than
+     * intended. Both surface identically, as a 400 naming the field. So
+     * the first refusal switches it off for the life of the process and
+     * the call is retried plainly; every later generation skips it.
+     *
+     * The cost of being wrong is therefore one retried call, once -- not
+     * a broken job pipeline, and not a feature nobody dares turn on.
+     */
+    static schemaSupport = 'unknown';
+    /** Does this failure read as "I don't take schemas"? Matched on the
+     *  field names, which is what an API naming the offending parameter
+     *  will say however it words the rest. */
+    static SCHEMA_REFUSAL = /output_config|json_schema|output_format|response_format/i;
     static async ask(prompt, opts) {
-        const config = this.resolveConfig();
+        const config = this.resolveConfig(opts?.workload ?? 'dialogue');
         if (!config) {
             throw new Error('No AI provider is configured. Set OPENAI_API_KEY or ANTHROPIC_API_KEY, ' +
                 'or log in to maka-cli.com (`maka login`) to use the server relay ' +
                 '(optionally MAKA_AI_PROVIDER to choose explicitly).');
         }
         const timeoutMs = opts?.timeoutMs;
-        const result = config.provider === 'openai'
-            ? await HTTPS.askGPT({ prompt, openApiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs })
+        const extras = this.supportsRequestExtras(config.provider)
+            ? {
+                cachedPrefix: opts?.cachedPrefix,
+                // Dropped once the provider has told us it will not take one.
+                ...(this.schemaSupport === 'no' ? {} : { jsonSchema: opts?.jsonSchema }),
+            }
+            : {};
+        const send = (withExtras) => config.provider === 'openai'
+            ? HTTPS.askGPT({ prompt, openApiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs })
             : config.provider === 'anthropic'
-                ? await HTTPS.askClaude({ prompt, apiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs })
+                ? HTTPS.askClaude({ prompt, apiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs, ...withExtras })
                 : config.provider === 'deepseek'
-                    ? await HTTPS.askDeepSeek({ prompt, apiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs })
-                    : await HTTPS.askMakaServer({ prompt, authToken: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs });
+                    ? HTTPS.askDeepSeek({ prompt, apiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs })
+                    : HTTPS.askMakaServer({ prompt, authToken: config.apiKey, model: config.model, maxTokens: opts?.maxTokens, timeoutMs });
+        let result = await send(extras);
+        // THE ONE RETRY THAT DISCOVERY COSTS. A 400 naming the schema field
+        // means this provider will not take one -- remember that for the
+        // rest of the process and send the call again plainly, so the
+        // generation that happened to be first does not pay for the lesson.
+        // Deliberately narrow: only a 4xx, only when a schema actually rode
+        // the request, and only when the body names the field. A 500 or a
+        // rate limit is not evidence about schemas and must keep its own
+        // meaning.
+        if (result.statusCode >= 400 && result.statusCode < 500
+            && 'jsonSchema' in extras && extras.jsonSchema
+            && AI.SCHEMA_REFUSAL.test(result.data ?? '')) {
+            this.schemaSupport = 'no';
+            const { jsonSchema: _dropped, ...rest } = extras;
+            result = await send(rest);
+        }
+        else if (result.statusCode < 400 && 'jsonSchema' in extras && extras.jsonSchema) {
+            this.schemaSupport = 'yes';
+        }
         // A BODY THAT IS NOT JSON IS AN HTTP PROBLEM, NOT A PARSE PROBLEM.
         // This parse used to run bare, AHEAD of the statusCode guard below
         // -- so that guard only ever protected JSON-shaped failures. When

package/bundle/typescript/src/tools/https/https.class.js

@@ -287,7 +287,7 @@ export class HTTPS {
             timeout: timeoutMs
         });
     }
-    static async askClaude({ prompt, apiKey, certPath, model = 'claude-sonnet-5', maxTokens = 4096, timeoutMs }) {
+    static async askClaude({ prompt, apiKey, certPath, model = 'claude-sonnet-5', maxTokens = 4096, timeoutMs, cachedPrefix, jsonSchema }) {
         const headers = {
             'x-api-key': apiKey,
             'anthropic-version': '2023-06-01',
@@ -317,6 +317,22 @@ export class HTTPS {
             // all -- not a concern for the default model here, but worth knowing
             // if MAKA_AI_MODEL is ever pointed at one of those.
             thinking: { type: 'disabled' },
+            // THE CACHED PREFIX GOES IN `system`, AHEAD OF THE MESSAGES.
+            // Caching matches on a prefix and the render order is
+            // tools -> system -> messages, so stable text has to sit here for
+            // the volatile per-chunk prompt below to be the only thing that
+            // changes between calls. Omitted entirely when there is nothing
+            // to cache -- an empty system block would be one more byte of
+            // prefix for no benefit.
+            ...(cachedPrefix
+                ? { system: [{ type: 'text', text: cachedPrefix, cache_control: { type: 'ephemeral' } }] }
+                : {}),
+            // SCHEMA-CONSTRAINED REPLY. The root must be an object carrying
+            // `additionalProperties: false` and `required`; the API rejects
+            // anything looser, and the caller owns getting that right.
+            ...(jsonSchema
+                ? { output_config: { format: { type: 'json_schema', schema: jsonSchema } } }
+                : {}),
             messages: [
                 {
                     role: 'user',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.191.0",
+  "version": "5.192.0",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",