@hiper2d/ai-agents 0.1.2 → 0.1.3

package/dist/index.d.mts

@@ -257,6 +257,19 @@ declare class ModelAuthenticationError extends ModelError {
 declare class ModelQuotaExceededError extends ModelError {
     constructor(message: string, modelType: string);
 }
+/**
+ * The model failed to produce a valid response: the output was malformed (unparseable
+ * JSON from a structured-output ask) or cut off at the output-token cap before the
+ * answer was complete (`status: "incomplete"` on the OpenAI Responses API). Not a
+ * transport or availability problem — the request worked, the generation went wrong.
+ * A retry with the same prompt often succeeds; `truncated` distinguishes a cap hit
+ * (raise maxOutputTokens if legitimate responses genuinely need more room) from a
+ * degenerate/runaway generation (a bigger cap only makes failures slower).
+ */
+declare class ModelInvalidResponseError extends ModelError {
+    truncated: boolean;
+    constructor(modelType: string, detail: string, truncated?: boolean);
+}
 /**
  * The model declined to answer: Anthropic returns `stop_reason: "refusal"` with no content
  * blocks when its safety layer rejects the request as a whole. Not retryable as-is — the
@@ -1188,4 +1201,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };

package/dist/index.d.ts

@@ -257,6 +257,19 @@ declare class ModelAuthenticationError extends ModelError {
 declare class ModelQuotaExceededError extends ModelError {
     constructor(message: string, modelType: string);
 }
+/**
+ * The model failed to produce a valid response: the output was malformed (unparseable
+ * JSON from a structured-output ask) or cut off at the output-token cap before the
+ * answer was complete (`status: "incomplete"` on the OpenAI Responses API). Not a
+ * transport or availability problem — the request worked, the generation went wrong.
+ * A retry with the same prompt often succeeds; `truncated` distinguishes a cap hit
+ * (raise maxOutputTokens if legitimate responses genuinely need more room) from a
+ * degenerate/runaway generation (a bigger cap only makes failures slower).
+ */
+declare class ModelInvalidResponseError extends ModelError {
+    truncated: boolean;
+    constructor(modelType: string, detail: string, truncated?: boolean);
+}
 /**
  * The model declined to answer: Anthropic returns `stop_reason: "refusal"` with no content
  * blocks when its safety layer rejects the request as a whole. Not retryable as-is — the
@@ -1188,4 +1201,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };

package/dist/index.js

@@ -58,6 +58,7 @@ __export(index_exports, {
   MistralAgent: () => MistralAgent,
   ModelAuthenticationError: () => ModelAuthenticationError,
   ModelError: () => ModelError,
+  ModelInvalidResponseError: () => ModelInvalidResponseError,
   ModelOverloadError: () => ModelOverloadError,
   ModelQuotaExceededError: () => ModelQuotaExceededError,
   ModelRateLimitError: () => ModelRateLimitError,
@@ -836,6 +837,14 @@ var ModelQuotaExceededError = class extends ModelError {
     this.name = "ModelQuotaExceededError";
   }
 };
+var ModelInvalidResponseError = class extends ModelError {
+  truncated;
+  constructor(modelType, detail, truncated = false) {
+    super(`${modelType} failed to produce a valid response: ${detail}`, modelType);
+    this.name = "ModelInvalidResponseError";
+    this.truncated = truncated;
+  }
+};
 var ModelRefusalError = class extends ModelError {
   constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`) {
     super(message, modelType);
@@ -1903,18 +1912,37 @@ var Gpt5Agent = class extends AbstractAgent {
           thinking: import_zod2.z.string().describe("Your internal chain-of-thought reasoning process used to arrive at the final answer.")
         });
       }
-      const response = await this.client.responses.parse({
-        model: this.model,
-        instructions: this.instruction,
-        input,
-        max_output_tokens: this.maxOutputTokens,
-        text: {
-          format: (0, import_zod3.zodTextFormat)(schemaToSend, "response_schema")
+      let response;
+      try {
+        response = await this.client.responses.parse({
+          model: this.model,
+          instructions: this.instruction,
+          input,
+          max_output_tokens: this.maxOutputTokens,
+          text: {
+            format: (0, import_zod3.zodTextFormat)(schemaToSend, "response_schema")
+          }
+        });
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          throw new ModelInvalidResponseError(
+            this.model,
+            `malformed JSON output \u2014 the generation was cut off at the ${this.maxOutputTokens}-token output cap or went off the rails (${error.message})`
+          );
         }
-      });
+        throw error;
+      }
+      if (response.status === "incomplete") {
+        const reason = response.incomplete_details?.reason ?? "unknown";
+        throw new ModelInvalidResponseError(
+          this.model,
+          `response incomplete (${reason}) at max_output_tokens=${this.maxOutputTokens}`,
+          reason === "max_output_tokens"
+        );
+      }
       if (!response.output_parsed) {
         this.logger(`Parsing failed. Raw content: ${response.output_text}`);
-        throw new Error(this.errorMessages.invalidFormat);
+        throw new ModelInvalidResponseError(this.model, this.errorMessages.invalidFormat);
       }
       let reasoningContent = "";
       if (this.enableThinking && response.output_parsed.thinking) {
@@ -1953,6 +1981,9 @@ var Gpt5Agent = class extends AbstractAgent {
       return [response.output_parsed, reasoningContent, tokenUsage];
     } catch (error) {
       this.logger(this.logTemplates.error(this.name, error));
+      if (error instanceof ModelError) {
+        throw error;
+      }
       throw new Error(this.errorMessages.apiError(error));
     }
   }
@@ -1978,6 +2009,14 @@ var Gpt5Agent = class extends AbstractAgent {
       });
       const content = response.output_text;
       if (!content) {
+        if (response.status === "incomplete") {
+          const reason = response.incomplete_details?.reason ?? "unknown";
+          throw new ModelInvalidResponseError(
+            this.model,
+            `empty response, incomplete (${reason}) at max_output_tokens=${this.maxOutputTokens}`,
+            reason === "max_output_tokens"
+          );
+        }
         throw new Error(this.errorMessages.emptyResponse);
       }
       let tokenUsage;
@@ -2010,6 +2049,9 @@ var Gpt5Agent = class extends AbstractAgent {
       return [content, "", tokenUsage];
     } catch (error) {
       this.logger(this.logTemplates.error(this.name, error));
+      if (error instanceof ModelError) {
+        throw error;
+      }
       throw new Error(this.errorMessages.apiError(error));
     }
   }
@@ -4426,6 +4468,7 @@ var AgentFactory = class {
   MistralAgent,
   ModelAuthenticationError,
   ModelError,
+  ModelInvalidResponseError,
   ModelOverloadError,
   ModelQuotaExceededError,
   ModelRateLimitError,