@maka/maka-cli 5.190.0 → 5.192.0

package/bundle/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.190.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

@@ -7,8 +7,9 @@ import { Logger } from '../utilities/logger.js';
 import { clampDeviceKind } from '../utilities/affordances.js';
 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.
@@ -169,6 +170,26 @@ export class SceneSeedGenerator {
             catch (err) {
                 carriedError = err instanceof Error ? err.message : String(err);
                 logger.write(`SceneSeedGenerator: pipeline ${pipeline} failed: ${carriedError}`);
+                // A PROVIDER THAT IS NOT ANSWERING WILL NOT ANSWER THREE TIMES
+                // (po7qSJycJrcfWbgaA, 2026-09-14). The pipeline budget exists for
+                // a model that wrote a bad SCENE -- a fresh skeleton is a real
+                // second chance at that. It is worth nothing against a provider
+                // that never started: DeepSeek refused this run's generation with
+                // "unable to start processing your request within the 900-second
+                // timeout limit", and the loop dutifully spent that wait twice
+                // more. Three-quarters of an hour, for a player standing in the
+                // hub, to arrive at the same refusal the first attempt already
+                // had in hand.
+                //
+                // So an unavailable provider ends the generation instead of
+                // re-buying it. The message survives in carriedError and reaches
+                // the player through draftFailureNote, which tells them it is the
+                // provider and not their key -- which is the whole point of
+                // stopping early rather than looking flaky for 45 minutes.
+                if (providerUnavailable(carriedError)) {
+                    logger.write(`SceneSeedGenerator: provider is not answering -- abandoning the remaining ${this.maxPipelineAttempts - pipeline} pipeline attempt(s).`);
+                    break;
+                }
             }
         }
         logger.write(`SceneSeedGenerator: giving up (${carriedError ?? 'unknown'}) -- falling back to a static scene`);
@@ -186,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 });
+            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 ?? [];
@@ -231,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 });
+            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/commands/game/sideQuest/game.js

@@ -191,7 +191,7 @@ import { clockTime, worldNow } from './utilities/world-clock.js';
 import { CommandFactory } from './factories/command-factory.js';
 import { SceneSynthesizer } from './factories/scene-factory.js';
 import { SceneSeedGenerator, FIXER_NAME, isFixerName } from './factories/scene-seed-generator.js';
-import { draftFailureNote } from './utilities/draft-failure-note.js';
+import { draftFailureNote, providerUnavailable } from './utilities/draft-failure-note.js';
 import { CALL_ICON, CALL_COLOR, END_CALL_SENTINEL } from './utilities/comm-style.js';
 import { AI } from '../../../tools/ai/ai.class.js';
 import { BULLET } from './utilities/log-style.js';
@@ -4646,8 +4646,25 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // caller but the ask-for-data-work door passes.
         const nextSeed = await SceneSeedGenerator.generate(this._logFilePath, nextTier, this.player, this.activeRumor, localCrew, undefined, runType);
         if (!nextSeed) {
-            const opsNote = draftFailureNote(SceneSeedGenerator.lastFailure ?? '');
-            return `Incoming call -- ${FIXER_NAME}: "Job fell through, chummer. Client got cold feet before the ink dried. Give me another call in a bit -- I'll shake something loose."${opsNote}`;
+            const why = SceneSeedGenerator.lastFailure ?? '';
+            const opsNote = draftFailureNote(why);
+            // DO NOT INVENT A CLIENT WHO GOT COLD FEET (po7qSJycJrcfWbgaA).
+            // That line is fine for a draft that came back malformed -- the
+            // fiction has to say something, and "the deal soured" is as true
+            // as anything. It is a LIE when the provider never answered: it
+            // names a cause inside the story for something that happened
+            // entirely outside it, and the advice it gives ("call me in a
+            // bit") walks the player straight back into the same wall. This
+            // codebase refuses invented causes everywhere else -- a fixer may
+            // not name a venue it does not know, an NPC may not name a runner
+            // who is not there -- and the rule holds here too.
+            //
+            // So an outage gets its own line: Krow cannot reach anyone, which
+            // is the honest shape of it in his voice, and the OOC note under
+            // it says the rest.
+            return providerUnavailable(why)
+                ? `Incoming call -- ${FIXER_NAME}: "Can't raise anybody tonight, chummer -- whole street's gone quiet on me. Sit tight; I'll call when the lines come back."${opsNote}`
+                : `Incoming call -- ${FIXER_NAME}: "Job fell through, chummer. Client got cold feet before the ink dried. Give me another call in a bit -- I'll shake something loose."${opsNote}`;
         }
         // HUB sessions: the draft lands as a MESSAGE, never a teleport (real
         // playtest note: being yanked into the run the instant generation

package/bundle/typescript/src/commands/game/sideQuest/utilities/draft-failure-note.js

@@ -23,6 +23,30 @@
  * codes need word boundaries so they can't match inside some other
  * number.
  */
+/**
+ * IS THE PROVIDER SIMPLY NOT ANSWERING? Exported because two decisions
+ * hang off the same question and must never disagree: what the player is
+ * told (below), and whether SceneSeedGenerator bothers with its remaining
+ * pipeline attempts (po7qSJycJrcfWbgaA). Two separately-written lists
+ * would drift, and the drift would be invisible -- the generator would
+ * keep re-buying a fifteen-minute wait while the note said the provider
+ * was down.
+ *
+ * Matched on PROSE, not status codes: only the prose crosses the wire,
+ * and each provider words it differently.
+ *
+ * The 2026-09-14 addition is DeepSeek's own queue refusal -- "We were
+ * unable to start processing your request within the 900-second timeout
+ * limit. Please try again later." Nothing in the old list came close to
+ * it, so a real outage read to the player as "Job fell through, chummer.
+ * Client got cold feet" with no note at all, and sent them straight back
+ * to call into the same wall. `Request timeout` is this codebase's own
+ * transport giving up (https.class.ts), which means the same thing from
+ * the other end of the socket.
+ */
+export function providerUnavailable(why) {
+    return /overloaded or down|rate-limited by its provider|took too long to answer|could not (?:complete that request|reach its ai provider)|unable to start processing|\b\d{2,4}-second timeout limit|Request timeout|ETIMEDOUT|ECONNRESET|socket hang up/i.test(why);
+}
 export function draftFailureNote(why) {
     // NAME THE CAUSE WHEN IT'S THE PROVIDER, NOT LUCK (real session: six
     // Krow calls into an out-of-credits key, indistinguishable from flaky
@@ -50,7 +74,7 @@ export function draftFailureNote(why) {
     // answering. Matched on the SITE'S OWN wording (ai-error-envelope.ts
     // classifyUpstream/classifyTransportFailure) rather than status
     // codes, since only the prose crosses the wire.
-    const providerOutage = !providerDown && /overloaded or down|rate-limited by its provider|took too long to answer|could not (?:complete that request|reach its ai provider)/i.test(why);
+    const providerOutage = !providerDown && providerUnavailable(why);
     // A structural failure is OURS, not the player's -- name it as the
     // generator's problem so nobody goes hunting their billing page, and
     // keep it short: the fiction already covers the beat.

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() {
@@ -377,20 +411,127 @@ export class AI {
      * runs 3-5x a dialogue reply, and the old fixed caps truncated it
      * mid-string). Leave unset for ordinary dialogue-sized replies.
      */
+    /**
+     * HOW LONG A GENERATION CALL WAITS (po7qSJycJrcfWbgaA, 2026-09-14).
+     *
+     * DeepSeek answered a run's scene generation with "We were unable to
+     * start processing your request within the 900-second timeout limit"
+     * -- fifteen minutes of queue before a refusal, and the generator's
+     * pipeline budget took that three times over. Forty-five minutes of a
+     * player standing in the hub waiting for a call that, when it finally
+     * came, said the job fell through.
+     *
+     * The transport's own default is the module's TIMEOUT (300s), which
+     * is a sane ceiling for a big download and far too patient for a
+     * prompt somebody is waiting on. A scene chunk that has not started
+     * coming back in 90 seconds is not going to save the commission.
+     *
+     * Deliberately NOT applied to every AI.ask: dialogue calls are short
+     * and already bounded by the same default, and an NPC that takes an
+     * extra beat is not a player staring at nothing. Generation asks for
+     * 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 result = config.provider === 'openai'
-            ? await HTTPS.askGPT({ prompt, openApiKey: config.apiKey, model: config.model, maxTokens: opts?.maxTokens })
+        const timeoutMs = opts?.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 })
+                ? 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 })
-                    : await HTTPS.askMakaServer({ prompt, authToken: config.apiKey, model: config.model, maxTokens: opts?.maxTokens });
+                    ? 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

@@ -258,7 +258,7 @@ export class HTTPS {
             req.end();
         });
     }
-    static async askGPT({ prompt, openApiKey, certPath, model = 'gpt-4.1', maxTokens = 3000 }) {
+    static async askGPT({ prompt, openApiKey, certPath, model = 'gpt-4.1', maxTokens = 3000, timeoutMs }) {
         const headers = {
             'Authorization': `Bearer ${openApiKey}`,
             'Content-Type': 'application/json',
@@ -283,10 +283,11 @@ export class HTTPS {
             path: '/v1/chat/completions',
             data,
             headers,
-            cert: certPath
+            cert: certPath,
+            timeout: timeoutMs
         });
     }
-    static async askClaude({ prompt, apiKey, certPath, model = 'claude-sonnet-5', maxTokens = 4096 }) {
+    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',
@@ -316,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',
@@ -328,7 +345,8 @@ export class HTTPS {
             path: '/v1/messages',
             data,
             headers,
-            cert: certPath
+            cert: certPath,
+            timeout: timeoutMs
         });
     }
     /**
@@ -349,7 +367,7 @@ export class HTTPS {
      * reasoning tokens that never reach the player. The same trap the
      * Claude path above documents, sprung by a different vendor.
      */
-    static async askDeepSeek({ prompt, apiKey, certPath, model = 'deepseek-v4-flash', maxTokens = 4096 }) {
+    static async askDeepSeek({ prompt, apiKey, certPath, model = 'deepseek-v4-flash', maxTokens = 4096, timeoutMs }) {
         return await this.post({
             hostname: 'api.deepseek.com',
             path: '/anthropic/v1/messages',
@@ -364,7 +382,8 @@ export class HTTPS {
                 'anthropic-version': '2023-06-01',
                 'Content-Type': 'application/json',
             },
-            cert: certPath
+            cert: certPath,
+            timeout: timeoutMs
         });
     }
     /**
@@ -375,7 +394,7 @@ export class HTTPS {
      * resume token, not an API key. Production host only -- the relay is
      * an account nicety, not a dev-loop dependency.
      */
-    static async askMakaServer({ prompt, authToken, model, maxTokens = 4096 }) {
+    static async askMakaServer({ prompt, authToken, model, maxTokens = 4096, timeoutMs }) {
         // MAKA_DEV TARGETING (kvhsgn3ouEG2znsha). Every other maka-cli.com
         // transport in this codebase already swings to a local server --
         // backlog, canon-lore, catalog, cloud-saves, session-telemetry,
@@ -401,8 +420,10 @@ export class HTTPS {
             data: { prompt, model, maxTokens },
             headers: { 'x-auth-token': authToken },
             // Generation-length calls ride this too; outlive the server's own
-            // 150s upstream timeout so its error body reaches us.
-            timeout: 180000,
+            // 150s upstream timeout so its error body reaches us. A caller
+            // asking for LESS patience still wins -- it is the one that knows
+            // whether somebody is waiting on the answer.
+            timeout: timeoutMs ?? 180000,
         });
     }
     static async askGPTStreaming(prompt, model = 'gpt-4.1') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.190.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.",