@hiper2d/ai-agents 0.5.1 → 0.5.2

package/dist/index.d.mts

@@ -272,15 +272,29 @@ declare class ModelInvalidResponseError extends ModelError {
     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
- * same prompt will refuse again — the caller has to change the prompt or the model.
- * Observed 2026-08-30 on Claude Fable 5: a persona system prompt plus a narrated multi-turn
- * history that ends by asking the character what it does refuses, while either half alone
- * answers; Sonnet 5 and Opus 4.8 answer the same requests.
+ * The model declined to answer. Not retryable as-is — the same prompt will refuse again —
+ * the caller has to change the prompt or the model. `reason` is the provider's own label
+ * for the refusal, when it gives one:
+ *
+ *   Anthropic  `stop_reason: "refusal"` with no content blocks when its safety layer rejects
+ *              the request as a whole. Observed 2026-08-30 on Claude Fable 5: a persona
+ *              system prompt plus a narrated multi-turn history that ends by asking the
+ *              character what it does refuses, while either half alone answers; Sonnet 5
+ *              and Opus 4.8 answer the same requests. `reason` = "refusal".
+ *   Google     a 200 with no candidates and `promptFeedback.blockReason` set (the prompt
+ *              itself was rejected: PROHIBITED_CONTENT, SAFETY, BLOCKLIST, JAILBREAK,
+ *              MODEL_ARMOR, OTHER), or a candidate whose `finishReason` is a content
+ *              block (SAFETY, PROHIBITED_CONTENT, BLOCKLIST, RECITATION, SPII,
+ *              IMAGE_SAFETY, ...). Observed 2026-09-13 in production: an explicit
+ *              sexual roleplay game was refused by Gemini 3.8 Flash and 3.1 Pro with
+ *              blockReason PROHIBITED_CONTENT in ~200ms and zero output tokens, while
+ *              Mistral, MiniMax and Muse answered the same prompt. PROHIBITED_CONTENT is
+ *              Google's non-configurable filter — no safetySettings change lifts it.
+ *              `reason` = the blockReason or finishReason string.
  */
 declare class ModelRefusalError extends ModelError {
-    constructor(modelType: string, message?: string);
+    reason?: string;
+    constructor(modelType: string, message?: string, reason?: string);
 }
 
 /**

package/dist/index.d.ts

@@ -272,15 +272,29 @@ declare class ModelInvalidResponseError extends ModelError {
     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
- * same prompt will refuse again — the caller has to change the prompt or the model.
- * Observed 2026-08-30 on Claude Fable 5: a persona system prompt plus a narrated multi-turn
- * history that ends by asking the character what it does refuses, while either half alone
- * answers; Sonnet 5 and Opus 4.8 answer the same requests.
+ * The model declined to answer. Not retryable as-is — the same prompt will refuse again —
+ * the caller has to change the prompt or the model. `reason` is the provider's own label
+ * for the refusal, when it gives one:
+ *
+ *   Anthropic  `stop_reason: "refusal"` with no content blocks when its safety layer rejects
+ *              the request as a whole. Observed 2026-08-30 on Claude Fable 5: a persona
+ *              system prompt plus a narrated multi-turn history that ends by asking the
+ *              character what it does refuses, while either half alone answers; Sonnet 5
+ *              and Opus 4.8 answer the same requests. `reason` = "refusal".
+ *   Google     a 200 with no candidates and `promptFeedback.blockReason` set (the prompt
+ *              itself was rejected: PROHIBITED_CONTENT, SAFETY, BLOCKLIST, JAILBREAK,
+ *              MODEL_ARMOR, OTHER), or a candidate whose `finishReason` is a content
+ *              block (SAFETY, PROHIBITED_CONTENT, BLOCKLIST, RECITATION, SPII,
+ *              IMAGE_SAFETY, ...). Observed 2026-09-13 in production: an explicit
+ *              sexual roleplay game was refused by Gemini 3.8 Flash and 3.1 Pro with
+ *              blockReason PROHIBITED_CONTENT in ~200ms and zero output tokens, while
+ *              Mistral, MiniMax and Muse answered the same prompt. PROHIBITED_CONTENT is
+ *              Google's non-configurable filter — no safetySettings change lifts it.
+ *              `reason` = the blockReason or finishReason string.
  */
 declare class ModelRefusalError extends ModelError {
-    constructor(modelType: string, message?: string);
+    reason?: string;
+    constructor(modelType: string, message?: string, reason?: string);
 }
 
 /**

package/dist/index.js

@@ -883,9 +883,11 @@ var ModelInvalidResponseError = class extends ModelError {
   }
 };
 var ModelRefusalError = class extends ModelError {
-  constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`) {
+  reason;
+  constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`, reason) {
     super(message, modelType);
     this.name = "ModelRefusalError";
+    this.reason = reason;
   }
 };
 
@@ -2823,7 +2825,7 @@ ${schemaDescription}`;
         throw new Error(this.errorMessages.apiError(apiError));
       }
       if (response.stop_reason === "refusal") {
-        throw new ModelRefusalError(this.model);
+        throw new ModelRefusalError(this.model, void 0, "refusal");
       }
       if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
         throw new Error(this.errorMessages.emptyResponse);
@@ -2917,7 +2919,7 @@ ${schemaDescription}`;
         throw new Error(this.errorMessages.apiError(apiError));
       }
       if (response.stop_reason === "refusal") {
-        throw new ModelRefusalError(this.model);
+        throw new ModelRefusalError(this.model, void 0, "refusal");
       }
       if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
         throw new Error(this.errorMessages.emptyResponse);
@@ -2973,6 +2975,45 @@ ${schemaDescription}`;
 
 // src/agents/google-agent.ts
 var import_genai3 = require("@google/genai");
+var GEMINI_REFUSAL_FINISH_REASONS = /* @__PURE__ */ new Set([
+  "SAFETY",
+  "RECITATION",
+  "BLOCKLIST",
+  "PROHIBITED_CONTENT",
+  "SPII",
+  "IMAGE_SAFETY",
+  "IMAGE_PROHIBITED_CONTENT",
+  "IMAGE_RECITATION"
+]);
+function throwForEmptyGeminiResponse(model, response, fallback) {
+  const blockReason = response?.promptFeedback?.blockReason;
+  const candidate = response?.candidates?.[0];
+  const finishReason = candidate?.finishReason;
+  const finishMessage = candidate?.finishMessage;
+  const ratings = (candidate?.safetyRatings ?? response?.promptFeedback?.safetyRatings ?? []).filter((r) => r?.blocked || r?.probability && r.probability !== "NEGLIGIBLE");
+  const ratingText = ratings.length ? `; safetyRatings: ${ratings.map((r) => `${r.category}=${r.probability ?? (r.blocked ? "blocked" : "?")}`).join(", ")}` : "";
+  if (blockReason) {
+    throw new ModelRefusalError(
+      model,
+      `${model} refused the prompt (blockReason: ${blockReason}${finishMessage ? `, ${finishMessage}` : ""}${ratingText})`,
+      blockReason
+    );
+  }
+  if (finishReason && GEMINI_REFUSAL_FINISH_REASONS.has(finishReason)) {
+    throw new ModelRefusalError(
+      model,
+      `${model} refused to answer (finishReason: ${finishReason}${finishMessage ? `, ${finishMessage}` : ""}${ratingText})`,
+      finishReason
+    );
+  }
+  if (finishReason === "MAX_TOKENS") {
+    throw new ModelInvalidResponseError(model, "empty response, finishReason MAX_TOKENS (thinking consumed the whole output budget)", true);
+  }
+  const bits = [`finishReason=${finishReason ?? "none"}`];
+  if (!response?.candidates?.length) bits.push("no candidates");
+  if (finishMessage) bits.push(`finishMessage="${finishMessage}"`);
+  throw new Error(`${fallback} (${bits.join(", ")})`);
+}
 var GoogleAgent = class extends AbstractAgent {
   client;
   defaultConfig = {
@@ -2984,7 +3025,7 @@ var GoogleAgent = class extends AbstractAgent {
   };
   // Error message templates
   errorMessages = {
-    emptyResponse: "Empty response from Google API - check logs for detailed response info",
+    emptyResponse: "Empty response from Google API",
     invalidFormat: "Invalid response format from Google API",
     apiError: (error) => `Failed to get response from Google API: ${error instanceof Error ? error.message : String(error)}`,
     unsupportedRole: (role) => `Unsupported role type: ${role}`
@@ -3156,7 +3197,7 @@ var GoogleAgent = class extends AbstractAgent {
       }
       this.logger(`Zod schema response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
       if (!response.text) {
-        throw new Error(this.errorMessages.emptyResponse);
+        throwForEmptyGeminiResponse(this.model, response, this.errorMessages.emptyResponse);
       }
       const parsedData = parseAndValidateLlmJson(response.text, zodSchema, (m) => this.logger(m));
       if (parsedData) {
@@ -3244,7 +3285,7 @@ var GoogleAgent = class extends AbstractAgent {
       }
       this.logger(`Plain text response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
       if (!response.text) {
-        throw new Error(this.errorMessages.emptyResponse);
+        throwForEmptyGeminiResponse(this.model, response, this.errorMessages.emptyResponse);
       }
       this.logReply(response.text, thinkingContent || void 0, tokenUsage);
       return [response.text, thinkingContent, tokenUsage, googleThoughtSignature || void 0];