@hiper2d/ai-agents 0.29.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -139,6 +139,25 @@ import { setBeforeAskHook } from '@hiper2d/ai-agents';
139
139
  setBeforeAskHook(async agent => { if (agent.userId) await budget.assertWithinBudget(agent.userId); });
140
140
  ```
141
141
 
142
+ ### Retrying empty and malformed answers
143
+
144
+ A model sometimes answers with nothing, or with text that is not the JSON the schema asked
145
+ for. Both throw `ModelInvalidResponseError`, and the same prompt usually works on the next
146
+ try, so an agent can re-send it on its own: set `agent.invalidResponseRetries` (default 0).
147
+ Timeouts, refusals, transport errors and cap hits (`truncated`) are never retried. Each
148
+ re-send runs the before-ask hook again — it is a new paid call. To show the wait in a UI,
149
+ install a retry hook; whatever function it returns is awaited once the ask has settled:
150
+
151
+ ```ts
152
+ import { setRetryHook } from '@hiper2d/ai-agents';
153
+ setRetryHook(async ({ agent, model, error, attempt }) => {
154
+ await ui.show(agent.gameId, `${agent.name}: ${error.message}, asking again`);
155
+ return () => ui.hide(agent.gameId);
156
+ });
157
+ ```
158
+
159
+ The error finally thrown after the last allowed attempt carries `retries`.
160
+
142
161
  ### Logging
143
162
 
144
163
  The library logs through an injectable sink — `setLlmLogger(fn)` — so a host app can route
package/dist/index.d.mts CHANGED
@@ -243,7 +243,7 @@ declare function extractFirstJsonObject(text: string): unknown | null;
243
243
  * ("Failed to parse JSON response:", "Response validation failed:") so log
244
244
  * queries and error handling stay stable.
245
245
  */
246
- declare function parseAndValidateLlmJson<T>(rawReply: string, zodSchema: z.ZodSchema<T>, log?: (message: string) => void): T;
246
+ declare function parseAndValidateLlmJson<T>(rawReply: string, zodSchema: z.ZodSchema<T>, log?: (message: string) => void, model?: string): T;
247
247
 
248
248
  /**
249
249
  * Custom error classes for AI agent interactions
@@ -271,16 +271,22 @@ declare class ModelQuotaExceededError extends ModelError {
271
271
  constructor(message: string, modelType: string);
272
272
  }
273
273
  /**
274
- * The model failed to produce a valid response: the output was malformed (unparseable
275
- * JSON from a structured-output ask) or cut off at the output-token cap before the
276
- * answer was complete (`status: "incomplete"` on the OpenAI Responses API). Not a
277
- * transport or availability problem — the request worked, the generation went wrong.
278
- * A retry with the same prompt often succeeds; `truncated` distinguishes a cap hit
279
- * (raise maxOutputTokens if legitimate responses genuinely need more room) from a
280
- * degenerate/runaway generation (a bigger cap only makes failures slower).
274
+ * The model failed to produce a valid response: the completion was empty (no usable
275
+ * text at all — every agent's empty-content guard throws this), the output was malformed
276
+ * (unparseable JSON, or JSON that fails the schema, from a structured-output ask), or it
277
+ * was cut off at the output-token cap before the answer was complete (`status:
278
+ * "incomplete"` on the OpenAI Responses API). Not a transport or availability problem —
279
+ * the request worked, the generation went wrong. A retry with the same prompt often
280
+ * succeeds, which is what `AbstractAgent.invalidResponseRetries` automates; `truncated`
281
+ * distinguishes a cap hit (raise maxOutputTokens if legitimate responses genuinely need
282
+ * more room; never auto-retried, since re-running it re-buys the whole output) from a
283
+ * degenerate/runaway generation (a bigger cap only makes failures slower). `retries` is
284
+ * stamped by the agent on the error it finally throws: how many automatic re-sends
285
+ * preceded it (absent when none).
281
286
  */
282
287
  declare class ModelInvalidResponseError extends ModelError {
283
288
  truncated: boolean;
289
+ retries?: number;
284
290
  constructor(modelType: string, detail: string, truncated?: boolean);
285
291
  }
286
292
  /**
@@ -388,6 +394,7 @@ declare const LLM_CONSTANTS: {
388
394
  GEMINI_FLASH: string;
389
395
  GEMINI_LITE: string;
390
396
  MISTRAL_SMALL: string;
397
+ MISTRAL_LARGE: string;
391
398
  GROK: string;
392
399
  KIMI: string;
393
400
  KIMI_HIGHSPEED: string;
@@ -565,10 +572,14 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
565
572
  * - Meta Muse Spark (verified 2026-09-12): minimal|low|medium|high|xhigh|max ("none" → 400; max is
566
573
  * Standard tier only)
567
574
  * - Mistral Small 4 / Medium 3.5 / Large 4: the documented API enum is
568
- * none|minimal|low|medium|high|xhigh, but every model we run accepts only "none" and "high"
569
- * (each other value is a 400 "not supported for this model, supported values: [high, none]",
570
- * checked on all three 2026-10-06). Reasoning is OFF unless the field is sent; "none" means
571
- * "don't reason", which an agent expresses by omitting the field, so the slice is just high.
575
+ * none|minimal|low|medium|high|xhigh, but Small 4 accepts only "none" and "high" (each other
576
+ * value is a 400 "not supported for this model, supported values: [high, none]", checked
577
+ * 2026-10-06). Large 4 takes low|medium|high since at least 2026-10-30 (its 400 for "none"
578
+ * lists exactly those), but the level barely changed its latency or trace size on real game
579
+ * turns and it is pinned to the documented "high" default, so the shared slice stays just
580
+ * high: a lower request on Large clamps up rather than risk a 400 on Small. Reasoning is OFF
581
+ * on Small unless the field is sent ("none" = "don't reason", which an agent expresses by
582
+ * omitting the field); Large reasons even when the field is omitted.
572
583
  * - xAI Grok 4.7 (docs.x.ai/developers/model-capabilities/text/reasoning, 2026-09-22):
573
584
  * low|medium|high|xhigh, default high, sent on the Responses API as `reasoning: {effort}`.
574
585
  * Chat Completions has no equivalent. Grok 4.6 and earlier had no knob at all.
@@ -1301,6 +1312,23 @@ declare class BudgetController {
1301
1312
  type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
1302
1313
  /** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
1303
1314
  declare function setBeforeAskHook(hook?: BeforeAskHook): void;
1315
+ /** Awaited once the ask a retry belonged to has settled (answered, or about to throw). */
1316
+ type RetrySettledFn = () => void | Promise<void>;
1317
+ /**
1318
+ * Runs right before an ask is re-sent after an empty or malformed response (see
1319
+ * `AbstractAgent.invalidResponseRetries`); `attempt` counts retries from 1. The intended
1320
+ * use is a UI notice ("the model returned nothing, asking again"): return a function and it
1321
+ * is awaited when the whole ask settles, so the notice can be taken down again. A throwing
1322
+ * hook is logged and ignored — it never stops the retry. Async hooks are awaited.
1323
+ */
1324
+ type RetryHook = (info: {
1325
+ agent: AbstractAgent;
1326
+ model: string;
1327
+ error: ModelInvalidResponseError;
1328
+ attempt: number;
1329
+ }) => void | RetrySettledFn | Promise<void | RetrySettledFn>;
1330
+ /** Install (or clear, with no argument) the process-wide retry hook. Call once at startup. */
1331
+ declare function setRetryHook(hook?: RetryHook): void;
1304
1332
  declare abstract class AbstractAgent {
1305
1333
  name: string;
1306
1334
  gameId?: string;
@@ -1327,6 +1355,17 @@ declare abstract class AbstractAgent {
1327
1355
  * instance for calls that legitimately run long, like maxOutputTokens.
1328
1356
  */
1329
1357
  requestTimeoutMs: number;
1358
+ /**
1359
+ * How many times one ask is re-sent after a ModelInvalidResponseError that is not a
1360
+ * cap hit: the model answered with nothing, or with text that is not the JSON the
1361
+ * schema asked for. Those are one-off generation failures the same prompt usually
1362
+ * gets right on the next try, unlike timeouts, refusals and transport errors, which
1363
+ * are never retried here. 0 (the default) hands every failure to the caller. A
1364
+ * truncated response is excluded because re-running it re-buys the whole output at
1365
+ * the cap. Each re-send runs the before-ask hook again (it is a new paid call) and
1366
+ * fires the retry hook; the error finally thrown carries `retries`.
1367
+ */
1368
+ invalidResponseRetries: number;
1330
1369
  protected readonly instruction: string;
1331
1370
  /**
1332
1371
  * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
@@ -1341,12 +1380,22 @@ declare abstract class AbstractAgent {
1341
1380
  protected readonly agentLoggingConfig: AgentLoggingConfig;
1342
1381
  protected constructor(name: string, instruction: string, model: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
1343
1382
  /**
1344
- * Public ask API — template methods that time the provider call and stamp `durationMs`
1345
- * into the returned TokenUsage. Subclasses implement doAskWithZodSchema/doAskText and
1383
+ * Public ask API — template methods that run the before-ask hook, time the provider
1384
+ * call, stamp `durationMs` into the returned TokenUsage and apply the
1385
+ * invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
1346
1386
  * must NOT override these.
1347
1387
  */
1348
1388
  askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
1349
1389
  askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1390
+ /**
1391
+ * One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
1392
+ * truncated) is re-sent up to invalidResponseRetries times, with the retry hook told
1393
+ * before each re-send. Anything else — a timeout, a refusal, a transport error, or the
1394
+ * last allowed attempt failing — is thrown as-is, stamped with the retry count. Every
1395
+ * settle function the hook returned runs once the ask is over, whichever way it ended.
1396
+ */
1397
+ private askWithRetries;
1398
+ private attempt;
1350
1399
  /**
1351
1400
  * Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
1352
1401
  * never answers) otherwise runs until the host kills the function with no error to show.
@@ -1863,4 +1912,4 @@ declare class MiniMaxAgent extends AbstractAgent {
1863
1912
  doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1864
1913
  }
1865
1914
 
1866
- export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MINIMAX_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, type MiniMaxReasoningEffort, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMiniMaxEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
1915
+ export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MINIMAX_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, type MiniMaxReasoningEffort, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, type RetryHook, type RetrySettledFn, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, setRetryHook, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMiniMaxEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
package/dist/index.d.ts CHANGED
@@ -243,7 +243,7 @@ declare function extractFirstJsonObject(text: string): unknown | null;
243
243
  * ("Failed to parse JSON response:", "Response validation failed:") so log
244
244
  * queries and error handling stay stable.
245
245
  */
246
- declare function parseAndValidateLlmJson<T>(rawReply: string, zodSchema: z.ZodSchema<T>, log?: (message: string) => void): T;
246
+ declare function parseAndValidateLlmJson<T>(rawReply: string, zodSchema: z.ZodSchema<T>, log?: (message: string) => void, model?: string): T;
247
247
 
248
248
  /**
249
249
  * Custom error classes for AI agent interactions
@@ -271,16 +271,22 @@ declare class ModelQuotaExceededError extends ModelError {
271
271
  constructor(message: string, modelType: string);
272
272
  }
273
273
  /**
274
- * The model failed to produce a valid response: the output was malformed (unparseable
275
- * JSON from a structured-output ask) or cut off at the output-token cap before the
276
- * answer was complete (`status: "incomplete"` on the OpenAI Responses API). Not a
277
- * transport or availability problem — the request worked, the generation went wrong.
278
- * A retry with the same prompt often succeeds; `truncated` distinguishes a cap hit
279
- * (raise maxOutputTokens if legitimate responses genuinely need more room) from a
280
- * degenerate/runaway generation (a bigger cap only makes failures slower).
274
+ * The model failed to produce a valid response: the completion was empty (no usable
275
+ * text at all — every agent's empty-content guard throws this), the output was malformed
276
+ * (unparseable JSON, or JSON that fails the schema, from a structured-output ask), or it
277
+ * was cut off at the output-token cap before the answer was complete (`status:
278
+ * "incomplete"` on the OpenAI Responses API). Not a transport or availability problem —
279
+ * the request worked, the generation went wrong. A retry with the same prompt often
280
+ * succeeds, which is what `AbstractAgent.invalidResponseRetries` automates; `truncated`
281
+ * distinguishes a cap hit (raise maxOutputTokens if legitimate responses genuinely need
282
+ * more room; never auto-retried, since re-running it re-buys the whole output) from a
283
+ * degenerate/runaway generation (a bigger cap only makes failures slower). `retries` is
284
+ * stamped by the agent on the error it finally throws: how many automatic re-sends
285
+ * preceded it (absent when none).
281
286
  */
282
287
  declare class ModelInvalidResponseError extends ModelError {
283
288
  truncated: boolean;
289
+ retries?: number;
284
290
  constructor(modelType: string, detail: string, truncated?: boolean);
285
291
  }
286
292
  /**
@@ -388,6 +394,7 @@ declare const LLM_CONSTANTS: {
388
394
  GEMINI_FLASH: string;
389
395
  GEMINI_LITE: string;
390
396
  MISTRAL_SMALL: string;
397
+ MISTRAL_LARGE: string;
391
398
  GROK: string;
392
399
  KIMI: string;
393
400
  KIMI_HIGHSPEED: string;
@@ -565,10 +572,14 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
565
572
  * - Meta Muse Spark (verified 2026-09-12): minimal|low|medium|high|xhigh|max ("none" → 400; max is
566
573
  * Standard tier only)
567
574
  * - Mistral Small 4 / Medium 3.5 / Large 4: the documented API enum is
568
- * none|minimal|low|medium|high|xhigh, but every model we run accepts only "none" and "high"
569
- * (each other value is a 400 "not supported for this model, supported values: [high, none]",
570
- * checked on all three 2026-10-06). Reasoning is OFF unless the field is sent; "none" means
571
- * "don't reason", which an agent expresses by omitting the field, so the slice is just high.
575
+ * none|minimal|low|medium|high|xhigh, but Small 4 accepts only "none" and "high" (each other
576
+ * value is a 400 "not supported for this model, supported values: [high, none]", checked
577
+ * 2026-10-06). Large 4 takes low|medium|high since at least 2026-10-30 (its 400 for "none"
578
+ * lists exactly those), but the level barely changed its latency or trace size on real game
579
+ * turns and it is pinned to the documented "high" default, so the shared slice stays just
580
+ * high: a lower request on Large clamps up rather than risk a 400 on Small. Reasoning is OFF
581
+ * on Small unless the field is sent ("none" = "don't reason", which an agent expresses by
582
+ * omitting the field); Large reasons even when the field is omitted.
572
583
  * - xAI Grok 4.7 (docs.x.ai/developers/model-capabilities/text/reasoning, 2026-09-22):
573
584
  * low|medium|high|xhigh, default high, sent on the Responses API as `reasoning: {effort}`.
574
585
  * Chat Completions has no equivalent. Grok 4.6 and earlier had no knob at all.
@@ -1301,6 +1312,23 @@ declare class BudgetController {
1301
1312
  type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
1302
1313
  /** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
1303
1314
  declare function setBeforeAskHook(hook?: BeforeAskHook): void;
1315
+ /** Awaited once the ask a retry belonged to has settled (answered, or about to throw). */
1316
+ type RetrySettledFn = () => void | Promise<void>;
1317
+ /**
1318
+ * Runs right before an ask is re-sent after an empty or malformed response (see
1319
+ * `AbstractAgent.invalidResponseRetries`); `attempt` counts retries from 1. The intended
1320
+ * use is a UI notice ("the model returned nothing, asking again"): return a function and it
1321
+ * is awaited when the whole ask settles, so the notice can be taken down again. A throwing
1322
+ * hook is logged and ignored — it never stops the retry. Async hooks are awaited.
1323
+ */
1324
+ type RetryHook = (info: {
1325
+ agent: AbstractAgent;
1326
+ model: string;
1327
+ error: ModelInvalidResponseError;
1328
+ attempt: number;
1329
+ }) => void | RetrySettledFn | Promise<void | RetrySettledFn>;
1330
+ /** Install (or clear, with no argument) the process-wide retry hook. Call once at startup. */
1331
+ declare function setRetryHook(hook?: RetryHook): void;
1304
1332
  declare abstract class AbstractAgent {
1305
1333
  name: string;
1306
1334
  gameId?: string;
@@ -1327,6 +1355,17 @@ declare abstract class AbstractAgent {
1327
1355
  * instance for calls that legitimately run long, like maxOutputTokens.
1328
1356
  */
1329
1357
  requestTimeoutMs: number;
1358
+ /**
1359
+ * How many times one ask is re-sent after a ModelInvalidResponseError that is not a
1360
+ * cap hit: the model answered with nothing, or with text that is not the JSON the
1361
+ * schema asked for. Those are one-off generation failures the same prompt usually
1362
+ * gets right on the next try, unlike timeouts, refusals and transport errors, which
1363
+ * are never retried here. 0 (the default) hands every failure to the caller. A
1364
+ * truncated response is excluded because re-running it re-buys the whole output at
1365
+ * the cap. Each re-send runs the before-ask hook again (it is a new paid call) and
1366
+ * fires the retry hook; the error finally thrown carries `retries`.
1367
+ */
1368
+ invalidResponseRetries: number;
1330
1369
  protected readonly instruction: string;
1331
1370
  /**
1332
1371
  * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
@@ -1341,12 +1380,22 @@ declare abstract class AbstractAgent {
1341
1380
  protected readonly agentLoggingConfig: AgentLoggingConfig;
1342
1381
  protected constructor(name: string, instruction: string, model: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
1343
1382
  /**
1344
- * Public ask API — template methods that time the provider call and stamp `durationMs`
1345
- * into the returned TokenUsage. Subclasses implement doAskWithZodSchema/doAskText and
1383
+ * Public ask API — template methods that run the before-ask hook, time the provider
1384
+ * call, stamp `durationMs` into the returned TokenUsage and apply the
1385
+ * invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
1346
1386
  * must NOT override these.
1347
1387
  */
1348
1388
  askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
1349
1389
  askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1390
+ /**
1391
+ * One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
1392
+ * truncated) is re-sent up to invalidResponseRetries times, with the retry hook told
1393
+ * before each re-send. Anything else — a timeout, a refusal, a transport error, or the
1394
+ * last allowed attempt failing — is thrown as-is, stamped with the retry count. Every
1395
+ * settle function the hook returned runs once the ask is over, whichever way it ended.
1396
+ */
1397
+ private askWithRetries;
1398
+ private attempt;
1350
1399
  /**
1351
1400
  * Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
1352
1401
  * never answers) otherwise runs until the host kills the function with no error to show.
@@ -1863,4 +1912,4 @@ declare class MiniMaxAgent extends AbstractAgent {
1863
1912
  doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
1864
1913
  }
1865
1914
 
1866
- export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MINIMAX_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, type MiniMaxReasoningEffort, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMiniMaxEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
1915
+ export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_REQUEST_TIMEOUT_MS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MINIMAX_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, type MiniMaxReasoningEffort, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, type RetryHook, type RetrySettledFn, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, setRetryHook, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMiniMaxEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };