@hiper2d/ai-agents 0.29.0 → 0.30.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 +19 -0
- package/dist/index.d.mts +55 -11
- package/dist/index.d.ts +55 -11
- package/dist/index.js +227 -136
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +226 -136
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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
|
|
275
|
-
*
|
|
276
|
-
*
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
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
|
/**
|
|
@@ -1301,6 +1307,23 @@ declare class BudgetController {
|
|
|
1301
1307
|
type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
|
|
1302
1308
|
/** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
|
|
1303
1309
|
declare function setBeforeAskHook(hook?: BeforeAskHook): void;
|
|
1310
|
+
/** Awaited once the ask a retry belonged to has settled (answered, or about to throw). */
|
|
1311
|
+
type RetrySettledFn = () => void | Promise<void>;
|
|
1312
|
+
/**
|
|
1313
|
+
* Runs right before an ask is re-sent after an empty or malformed response (see
|
|
1314
|
+
* `AbstractAgent.invalidResponseRetries`); `attempt` counts retries from 1. The intended
|
|
1315
|
+
* use is a UI notice ("the model returned nothing, asking again"): return a function and it
|
|
1316
|
+
* is awaited when the whole ask settles, so the notice can be taken down again. A throwing
|
|
1317
|
+
* hook is logged and ignored — it never stops the retry. Async hooks are awaited.
|
|
1318
|
+
*/
|
|
1319
|
+
type RetryHook = (info: {
|
|
1320
|
+
agent: AbstractAgent;
|
|
1321
|
+
model: string;
|
|
1322
|
+
error: ModelInvalidResponseError;
|
|
1323
|
+
attempt: number;
|
|
1324
|
+
}) => void | RetrySettledFn | Promise<void | RetrySettledFn>;
|
|
1325
|
+
/** Install (or clear, with no argument) the process-wide retry hook. Call once at startup. */
|
|
1326
|
+
declare function setRetryHook(hook?: RetryHook): void;
|
|
1304
1327
|
declare abstract class AbstractAgent {
|
|
1305
1328
|
name: string;
|
|
1306
1329
|
gameId?: string;
|
|
@@ -1327,6 +1350,17 @@ declare abstract class AbstractAgent {
|
|
|
1327
1350
|
* instance for calls that legitimately run long, like maxOutputTokens.
|
|
1328
1351
|
*/
|
|
1329
1352
|
requestTimeoutMs: number;
|
|
1353
|
+
/**
|
|
1354
|
+
* How many times one ask is re-sent after a ModelInvalidResponseError that is not a
|
|
1355
|
+
* cap hit: the model answered with nothing, or with text that is not the JSON the
|
|
1356
|
+
* schema asked for. Those are one-off generation failures the same prompt usually
|
|
1357
|
+
* gets right on the next try, unlike timeouts, refusals and transport errors, which
|
|
1358
|
+
* are never retried here. 0 (the default) hands every failure to the caller. A
|
|
1359
|
+
* truncated response is excluded because re-running it re-buys the whole output at
|
|
1360
|
+
* the cap. Each re-send runs the before-ask hook again (it is a new paid call) and
|
|
1361
|
+
* fires the retry hook; the error finally thrown carries `retries`.
|
|
1362
|
+
*/
|
|
1363
|
+
invalidResponseRetries: number;
|
|
1330
1364
|
protected readonly instruction: string;
|
|
1331
1365
|
/**
|
|
1332
1366
|
* The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
|
|
@@ -1341,12 +1375,22 @@ declare abstract class AbstractAgent {
|
|
|
1341
1375
|
protected readonly agentLoggingConfig: AgentLoggingConfig;
|
|
1342
1376
|
protected constructor(name: string, instruction: string, model: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
|
|
1343
1377
|
/**
|
|
1344
|
-
* Public ask API — template methods that
|
|
1345
|
-
* into the returned TokenUsage
|
|
1378
|
+
* Public ask API — template methods that run the before-ask hook, time the provider
|
|
1379
|
+
* call, stamp `durationMs` into the returned TokenUsage and apply the
|
|
1380
|
+
* invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
|
|
1346
1381
|
* must NOT override these.
|
|
1347
1382
|
*/
|
|
1348
1383
|
askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
|
|
1349
1384
|
askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
|
|
1385
|
+
/**
|
|
1386
|
+
* One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
|
|
1387
|
+
* truncated) is re-sent up to invalidResponseRetries times, with the retry hook told
|
|
1388
|
+
* before each re-send. Anything else — a timeout, a refusal, a transport error, or the
|
|
1389
|
+
* last allowed attempt failing — is thrown as-is, stamped with the retry count. Every
|
|
1390
|
+
* settle function the hook returned runs once the ask is over, whichever way it ended.
|
|
1391
|
+
*/
|
|
1392
|
+
private askWithRetries;
|
|
1393
|
+
private attempt;
|
|
1350
1394
|
/**
|
|
1351
1395
|
* Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
|
|
1352
1396
|
* never answers) otherwise runs until the host kills the function with no error to show.
|
|
@@ -1863,4 +1907,4 @@ declare class MiniMaxAgent extends AbstractAgent {
|
|
|
1863
1907
|
doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
|
|
1864
1908
|
}
|
|
1865
1909
|
|
|
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 };
|
|
1910
|
+
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
|
|
275
|
-
*
|
|
276
|
-
*
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
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
|
/**
|
|
@@ -1301,6 +1307,23 @@ declare class BudgetController {
|
|
|
1301
1307
|
type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
|
|
1302
1308
|
/** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
|
|
1303
1309
|
declare function setBeforeAskHook(hook?: BeforeAskHook): void;
|
|
1310
|
+
/** Awaited once the ask a retry belonged to has settled (answered, or about to throw). */
|
|
1311
|
+
type RetrySettledFn = () => void | Promise<void>;
|
|
1312
|
+
/**
|
|
1313
|
+
* Runs right before an ask is re-sent after an empty or malformed response (see
|
|
1314
|
+
* `AbstractAgent.invalidResponseRetries`); `attempt` counts retries from 1. The intended
|
|
1315
|
+
* use is a UI notice ("the model returned nothing, asking again"): return a function and it
|
|
1316
|
+
* is awaited when the whole ask settles, so the notice can be taken down again. A throwing
|
|
1317
|
+
* hook is logged and ignored — it never stops the retry. Async hooks are awaited.
|
|
1318
|
+
*/
|
|
1319
|
+
type RetryHook = (info: {
|
|
1320
|
+
agent: AbstractAgent;
|
|
1321
|
+
model: string;
|
|
1322
|
+
error: ModelInvalidResponseError;
|
|
1323
|
+
attempt: number;
|
|
1324
|
+
}) => void | RetrySettledFn | Promise<void | RetrySettledFn>;
|
|
1325
|
+
/** Install (or clear, with no argument) the process-wide retry hook. Call once at startup. */
|
|
1326
|
+
declare function setRetryHook(hook?: RetryHook): void;
|
|
1304
1327
|
declare abstract class AbstractAgent {
|
|
1305
1328
|
name: string;
|
|
1306
1329
|
gameId?: string;
|
|
@@ -1327,6 +1350,17 @@ declare abstract class AbstractAgent {
|
|
|
1327
1350
|
* instance for calls that legitimately run long, like maxOutputTokens.
|
|
1328
1351
|
*/
|
|
1329
1352
|
requestTimeoutMs: number;
|
|
1353
|
+
/**
|
|
1354
|
+
* How many times one ask is re-sent after a ModelInvalidResponseError that is not a
|
|
1355
|
+
* cap hit: the model answered with nothing, or with text that is not the JSON the
|
|
1356
|
+
* schema asked for. Those are one-off generation failures the same prompt usually
|
|
1357
|
+
* gets right on the next try, unlike timeouts, refusals and transport errors, which
|
|
1358
|
+
* are never retried here. 0 (the default) hands every failure to the caller. A
|
|
1359
|
+
* truncated response is excluded because re-running it re-buys the whole output at
|
|
1360
|
+
* the cap. Each re-send runs the before-ask hook again (it is a new paid call) and
|
|
1361
|
+
* fires the retry hook; the error finally thrown carries `retries`.
|
|
1362
|
+
*/
|
|
1363
|
+
invalidResponseRetries: number;
|
|
1330
1364
|
protected readonly instruction: string;
|
|
1331
1365
|
/**
|
|
1332
1366
|
* The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
|
|
@@ -1341,12 +1375,22 @@ declare abstract class AbstractAgent {
|
|
|
1341
1375
|
protected readonly agentLoggingConfig: AgentLoggingConfig;
|
|
1342
1376
|
protected constructor(name: string, instruction: string, model: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
|
|
1343
1377
|
/**
|
|
1344
|
-
* Public ask API — template methods that
|
|
1345
|
-
* into the returned TokenUsage
|
|
1378
|
+
* Public ask API — template methods that run the before-ask hook, time the provider
|
|
1379
|
+
* call, stamp `durationMs` into the returned TokenUsage and apply the
|
|
1380
|
+
* invalidResponseRetries policy. Subclasses implement doAskWithZodSchema/doAskText and
|
|
1346
1381
|
* must NOT override these.
|
|
1347
1382
|
*/
|
|
1348
1383
|
askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
|
|
1349
1384
|
askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
|
|
1385
|
+
/**
|
|
1386
|
+
* One attempt per loop; an empty or malformed answer (ModelInvalidResponseError, not
|
|
1387
|
+
* truncated) is re-sent up to invalidResponseRetries times, with the retry hook told
|
|
1388
|
+
* before each re-send. Anything else — a timeout, a refusal, a transport error, or the
|
|
1389
|
+
* last allowed attempt failing — is thrown as-is, stamped with the retry count. Every
|
|
1390
|
+
* settle function the hook returned runs once the ask is over, whichever way it ended.
|
|
1391
|
+
*/
|
|
1392
|
+
private askWithRetries;
|
|
1393
|
+
private attempt;
|
|
1350
1394
|
/**
|
|
1351
1395
|
* Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
|
|
1352
1396
|
* never answers) otherwise runs until the host kills the function with no error to show.
|
|
@@ -1863,4 +1907,4 @@ declare class MiniMaxAgent extends AbstractAgent {
|
|
|
1863
1907
|
doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
|
|
1864
1908
|
}
|
|
1865
1909
|
|
|
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 };
|
|
1910
|
+
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 };
|