visual-ai-assertions 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-/** Supported provider identifiers for configuring `visualAI()`. */
+/** Supported provider identifiers used internally for pricing and provider selection. */
 declare const Provider: {
     readonly ANTHROPIC: "anthropic";
     readonly OPENAI: "openai";
@@ -16,6 +16,8 @@ declare const Model: {
     readonly OpenAI: {
         readonly GPT_5_4: "gpt-5.4";
         readonly GPT_5_4_PRO: "gpt-5.4-pro";
+        readonly GPT_5_4_MINI: "gpt-5.4-mini";
+        readonly GPT_5_4_NANO: "gpt-5.4-nano";
         readonly GPT_5_2: "gpt-5.2";
         readonly GPT_5_MINI: "gpt-5-mini";
     };
@@ -29,11 +31,9 @@ type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (
 /** Default model selection used when a caller omits `config.model`. */
 declare const DEFAULT_MODELS: {
     readonly anthropic: "claude-sonnet-4-6";
-    readonly openai: "gpt-5-mini";
+    readonly openai: "gpt-5.4-mini";
     readonly google: "gemini-3-flash-preview";
 };
-/** List of accepted provider names for validation and public consumption. */
-declare const VALID_PROVIDERS: readonly ProviderName[];
 /** Built-in content checks available through `client.content()`. */
 declare const Content: {
     /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
@@ -392,17 +392,20 @@ type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
  * @example
  * ```ts
  * const client = visualAI({
- *   provider: "openai",
  *   model: "gpt-5-mini",
  *   apiKey: process.env.OPENAI_API_KEY,
  * });
  * ```
  */
 interface VisualAIConfig {
-    provider?: ProviderName;
     apiKey?: string;
     model?: string;
+    /** Enable error diagnostic logging to stderr. Does not enable prompt/response logging — use `debugPrompt` and `debugResponse` for that. */
     debug?: boolean;
+    /** Log prompts to stderr. */
+    debugPrompt?: boolean;
+    /** Log responses to stderr. */
+    debugResponse?: boolean;
     maxTokens?: number;
     reasoningEffort?: ReasoningEffort;
     trackUsage?: boolean;
@@ -458,7 +461,7 @@ interface ContentOptions {
  *
  * @example
  * ```ts
- * const client = visualAI({ provider: "openai" });
+ * const client = visualAI({ model: "gpt-5-mini" });
  * const result = await client.check("./tests/fixtures/small.png", "The button is visible");
  * ```
  */
@@ -608,7 +611,7 @@ interface VisualAIClient {
 /**
  * Creates a configured visual AI client.
  *
- * @param config Provider selection and runtime options for subsequent requests.
+ * @param config Model selection and runtime options for subsequent requests.
  * @returns A `VisualAIClient` instance with check, compare, ask, and template helpers.
  * @throws {VisualAIConfigError} When the provider or model configuration is invalid.
  * @throws {VisualAIAuthError} When required API credentials are missing.
@@ -619,7 +622,7 @@ interface VisualAIClient {
  *
  * test("hero loads correctly", async ({ page }) => {
  *   const client = visualAI({
- *     provider: "openai",
+ *     model: "gpt-5-mini",
  *     apiKey: process.env.OPENAI_API_KEY,
  *   });
  *
@@ -836,4 +839,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
  */
 declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
 
-export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, Model, type PageLoadOptions, Provider, type ProviderName, type ReasoningEffort, type StatementResult, StatementResultSchema, type SupportedMimeType, type UsageInfo, UsageInfoSchema, VALID_PROVIDERS, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
+export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, Model, type PageLoadOptions, Provider, type ProviderName, type ReasoningEffort, type StatementResult, StatementResultSchema, type SupportedMimeType, type UsageInfo, UsageInfoSchema, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-/** Supported provider identifiers for configuring `visualAI()`. */
+/** Supported provider identifiers used internally for pricing and provider selection. */
 declare const Provider: {
     readonly ANTHROPIC: "anthropic";
     readonly OPENAI: "openai";
@@ -16,6 +16,8 @@ declare const Model: {
     readonly OpenAI: {
         readonly GPT_5_4: "gpt-5.4";
         readonly GPT_5_4_PRO: "gpt-5.4-pro";
+        readonly GPT_5_4_MINI: "gpt-5.4-mini";
+        readonly GPT_5_4_NANO: "gpt-5.4-nano";
         readonly GPT_5_2: "gpt-5.2";
         readonly GPT_5_MINI: "gpt-5-mini";
     };
@@ -29,11 +31,9 @@ type KnownModelName = (typeof Model.Anthropic)[keyof typeof Model.Anthropic] | (
 /** Default model selection used when a caller omits `config.model`. */
 declare const DEFAULT_MODELS: {
     readonly anthropic: "claude-sonnet-4-6";
-    readonly openai: "gpt-5-mini";
+    readonly openai: "gpt-5.4-mini";
     readonly google: "gemini-3-flash-preview";
 };
-/** List of accepted provider names for validation and public consumption. */
-declare const VALID_PROVIDERS: readonly ProviderName[];
 /** Built-in content checks available through `client.content()`. */
 declare const Content: {
     /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
@@ -392,17 +392,20 @@ type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
  * @example
  * ```ts
  * const client = visualAI({
- *   provider: "openai",
  *   model: "gpt-5-mini",
  *   apiKey: process.env.OPENAI_API_KEY,
  * });
  * ```
  */
 interface VisualAIConfig {
-    provider?: ProviderName;
     apiKey?: string;
     model?: string;
+    /** Enable error diagnostic logging to stderr. Does not enable prompt/response logging — use `debugPrompt` and `debugResponse` for that. */
     debug?: boolean;
+    /** Log prompts to stderr. */
+    debugPrompt?: boolean;
+    /** Log responses to stderr. */
+    debugResponse?: boolean;
     maxTokens?: number;
     reasoningEffort?: ReasoningEffort;
     trackUsage?: boolean;
@@ -458,7 +461,7 @@ interface ContentOptions {
  *
  * @example
  * ```ts
- * const client = visualAI({ provider: "openai" });
+ * const client = visualAI({ model: "gpt-5-mini" });
  * const result = await client.check("./tests/fixtures/small.png", "The button is visible");
  * ```
  */
@@ -608,7 +611,7 @@ interface VisualAIClient {
 /**
  * Creates a configured visual AI client.
  *
- * @param config Provider selection and runtime options for subsequent requests.
+ * @param config Model selection and runtime options for subsequent requests.
  * @returns A `VisualAIClient` instance with check, compare, ask, and template helpers.
  * @throws {VisualAIConfigError} When the provider or model configuration is invalid.
  * @throws {VisualAIAuthError} When required API credentials are missing.
@@ -619,7 +622,7 @@ interface VisualAIClient {
  *
  * test("hero loads correctly", async ({ page }) => {
  *   const client = visualAI({
- *     provider: "openai",
+ *     model: "gpt-5-mini",
  *     apiKey: process.env.OPENAI_API_KEY,
  *   });
  *
@@ -836,4 +839,4 @@ declare function assertVisualResult(result: CheckResult, label?: string): void;
  */
 declare function assertVisualCompareResult(result: CompareResult, label?: string): void;
 
-export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, Model, type PageLoadOptions, Provider, type ProviderName, type ReasoningEffort, type StatementResult, StatementResultSchema, type SupportedMimeType, type UsageInfo, UsageInfoSchema, VALID_PROVIDERS, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };
+export { Accessibility, type AccessibilityCheckName, type AccessibilityOptions, type AskOptions, type AskResult, AskResultSchema, type ChangeEntry, ChangeEntrySchema, type CheckOptions, type CheckResult, CheckResultSchema, type CompareOptions, type CompareResult, CompareResultSchema, type Confidence, ConfidenceSchema, Content, type ContentCheckName, type ContentOptions, DEFAULT_MODELS, type DiffImageResult, type ElementsVisibilityOptions, type ImageInput, type Issue, type IssueCategory, IssueCategorySchema, type IssuePriority, IssuePrioritySchema, IssueSchema, type KnownModelName, Layout, type LayoutCheckName, type LayoutOptions, Model, type PageLoadOptions, Provider, type ProviderName, type ReasoningEffort, type StatementResult, StatementResultSchema, type SupportedMimeType, type UsageInfo, UsageInfoSchema, VisualAIAssertionError, VisualAIAuthError, type VisualAIClient, type VisualAIConfig, VisualAIConfigError, VisualAIError, type VisualAIErrorCode, VisualAIImageError, type VisualAIKnownError, VisualAIProviderError, VisualAIRateLimitError, VisualAIResponseParseError, assertVisualCompareResult, assertVisualResult, formatCheckResult, formatCompareResult, isVisualAIKnownError, visualAI };

package/dist/index.js

@@ -13,6 +13,8 @@ var Model = {
   OpenAI: {
     GPT_5_4: "gpt-5.4",
     GPT_5_4_PRO: "gpt-5.4-pro",
+    GPT_5_4_MINI: "gpt-5.4-mini",
+    GPT_5_4_NANO: "gpt-5.4-nano",
     GPT_5_2: "gpt-5.2",
     GPT_5_MINI: "gpt-5-mini"
   },
@@ -23,7 +25,7 @@ var Model = {
 };
 var DEFAULT_MODELS = {
   [Provider.ANTHROPIC]: Model.Anthropic.SONNET_4_6,
-  [Provider.OPENAI]: Model.OpenAI.GPT_5_MINI,
+  [Provider.OPENAI]: Model.OpenAI.GPT_5_4_MINI,
   [Provider.GOOGLE]: Model.Google.GEMINI_3_FLASH_PREVIEW
 };
 var DEFAULT_MAX_TOKENS = 4096;
@@ -33,6 +35,11 @@ var MODEL_TO_PROVIDER = new Map([
   ...Object.values(Model.Google).map((m) => [m, Provider.GOOGLE])
 ]);
 var VALID_PROVIDERS = Object.values(Provider);
+var PROVIDER_DEFAULT_REASONING = {
+  openai: "medium",
+  anthropic: "off",
+  google: "off"
+};
 var Content = {
   /** Detects Lorem ipsum, TODO, TBD, and similar placeholder text */
   PLACEHOLDER_TEXT: "placeholder-text",
@@ -660,23 +667,6 @@ function inferProviderFromModel(model) {
   return prefixMatch?.[1];
 }
 function resolveProvider(config) {
-  if (config.provider) {
-    if (!VALID_PROVIDERS.includes(config.provider)) {
-      throw new VisualAIConfigError(
-        `Unknown provider: "${config.provider}". Supported: ${VALID_PROVIDERS.join(", ")}`
-      );
-    }
-    return config.provider;
-  }
-  const envProvider = process.env.VISUAL_AI_PROVIDER;
-  if (envProvider) {
-    if (VALID_PROVIDERS.includes(envProvider)) {
-      return envProvider;
-    }
-    throw new VisualAIConfigError(
-      `Invalid VISUAL_AI_PROVIDER: "${envProvider}". Supported: ${VALID_PROVIDERS.join(", ")}`
-    );
-  }
   const model = config.model ?? process.env.VISUAL_AI_MODEL;
   if (model) {
     const inferred = inferProviderFromModel(model);
@@ -690,7 +680,7 @@ function resolveProvider(config) {
   const detected = apiKeyProviderMap.find(([key]) => process.env[key]);
   if (detected) return detected[1];
   throw new VisualAIConfigError(
-    "No provider specified. Set `provider` in config, `VISUAL_AI_PROVIDER` env variable, or an API key env variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY)."
+    "Cannot determine provider. Set a model name (config or VISUAL_AI_MODEL) or an API key env variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY)."
   );
 }
 function parseBooleanEnv(envName, value) {
@@ -702,13 +692,27 @@ function parseBooleanEnv(envName, value) {
     `Invalid ${envName} value: "${value}". Use "true", "1", "false", or "0".`
   );
 }
+var VALID_REASONING_EFFORTS = ["low", "medium", "high", "xhigh"];
+function parseReasoningEffortEnv(envName, value) {
+  if (value === void 0 || value === "") return void 0;
+  const lower = value.toLowerCase();
+  if (VALID_REASONING_EFFORTS.includes(lower)) return lower;
+  throw new VisualAIConfigError(
+    `Invalid ${envName} value: "${value}". Use "low", "medium", "high", or "xhigh".`
+  );
+}
+var debugDeprecationWarned = false;
 function resolveConfig(config) {
   const provider = resolveProvider(config);
   const model = config.model ?? process.env.VISUAL_AI_MODEL ?? DEFAULT_MODELS[provider];
-  const modelProvider = inferProviderFromModel(model);
-  if (modelProvider && modelProvider !== provider) {
-    throw new VisualAIConfigError(
-      `Model "${model}" appears to be a ${modelProvider} model, but provider is "${provider}". Either change the provider or use a ${provider}-compatible model.`
+  const debug = config.debug ?? parseBooleanEnv("VISUAL_AI_DEBUG", process.env.VISUAL_AI_DEBUG) ?? false;
+  const debugPrompt = config.debugPrompt ?? parseBooleanEnv("VISUAL_AI_DEBUG_PROMPT", process.env.VISUAL_AI_DEBUG_PROMPT) ?? false;
+  const debugResponse = config.debugResponse ?? parseBooleanEnv("VISUAL_AI_DEBUG_RESPONSE", process.env.VISUAL_AI_DEBUG_RESPONSE) ?? false;
+  if (debug && !debugPrompt && !debugResponse && !debugDeprecationWarned) {
+    debugDeprecationWarned = true;
+    process.stderr.write(
+      `[visual-ai-assertions] Warning: VISUAL_AI_DEBUG no longer enables prompt/response logging. Use VISUAL_AI_DEBUG_PROMPT=true and/or VISUAL_AI_DEBUG_RESPONSE=true instead.
+`
     );
   }
   return {
@@ -716,8 +720,10 @@ function resolveConfig(config) {
     apiKey: config.apiKey,
     model,
     maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
-    reasoningEffort: config.reasoningEffort,
-    debug: config.debug ?? parseBooleanEnv("VISUAL_AI_DEBUG", process.env.VISUAL_AI_DEBUG) ?? false,
+    reasoningEffort: config.reasoningEffort ?? parseReasoningEffortEnv("VISUAL_AI_REASONING_EFFORT", process.env.VISUAL_AI_REASONING_EFFORT),
+    debug,
+    debugPrompt,
+    debugResponse,
     trackUsage: config.trackUsage ?? parseBooleanEnv("VISUAL_AI_TRACK_USAGE", process.env.VISUAL_AI_TRACK_USAGE) ?? false
   };
 }
@@ -749,6 +755,14 @@ var PRICING_TABLE = {
     inputPricePerToken: 1.75 / PER_MILLION,
     outputPricePerToken: 14 / PER_MILLION
   },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_4_MINI}`]: {
+    inputPricePerToken: 0.75 / PER_MILLION,
+    outputPricePerToken: 4.5 / PER_MILLION
+  },
+  [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_4_NANO}`]: {
+    inputPricePerToken: 0.2 / PER_MILLION,
+    outputPricePerToken: 1.25 / PER_MILLION
+  },
   [`${Provider.OPENAI}:${Model.OpenAI.GPT_5_MINI}`]: {
     inputPricePerToken: 0.25 / PER_MILLION,
     outputPricePerToken: 2 / PER_MILLION
@@ -770,8 +784,9 @@ function calculateCost(provider, model, inputTokens, outputTokens) {
 }
 
 // src/core/debug.ts
-function debugLog(config, label, data) {
-  if (config.debug) {
+function debugLog(config, label, data, kind = "error") {
+  const enabled = kind === "prompt" ? config.debugPrompt : kind === "response" ? config.debugResponse : config.debug;
+  if (enabled) {
     process.stderr.write(`[visual-ai-assertions] ${label}: ${data}
 `);
   }
@@ -779,8 +794,9 @@ function debugLog(config, label, data) {
 function usageLog(config, method, usage) {
   if (!config.trackUsage) return;
   const costStr = usage.estimatedCost !== void 0 ? `$${usage.estimatedCost.toFixed(6)}` : "unknown";
+  const reasoningStr = config.reasoningEffort ? `reasoning: ${config.reasoningEffort}` : `reasoning: ${PROVIDER_DEFAULT_REASONING[config.provider]} (provider default)`;
   process.stderr.write(
-    `[visual-ai-assertions] ${method} usage: ${usage.inputTokens} input + ${usage.outputTokens} output tokens (${costStr}) in ${usage.durationSeconds?.toFixed(3) ?? "0.000"}s [${config.model}]
+    `[visual-ai-assertions] ${method} usage: ${usage.inputTokens} input + ${usage.outputTokens} output tokens (${costStr}) in ${usage.durationSeconds?.toFixed(3) ?? "0.000"}s [${config.model}, ${reasoningStr}]
 `
   );
 }
@@ -796,6 +812,28 @@ function processUsage(method, rawUsage, durationSeconds, config) {
   usageLog(config, method, usage);
   return usage;
 }
+var MAX_RAW_RESPONSE_PREVIEW = 500;
+function formatError(error) {
+  if (error instanceof VisualAIResponseParseError) {
+    const truncated = error.rawResponse.length > MAX_RAW_RESPONSE_PREVIEW ? error.rawResponse.slice(0, MAX_RAW_RESPONSE_PREVIEW) + "..." : error.rawResponse;
+    return `${error.name} (${error.code}): ${error.message}. Raw (truncated): ${truncated}`;
+  }
+  if (error instanceof VisualAIError) {
+    return `${error.name} (${error.code}): ${error.message}`;
+  }
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+async function withErrorDebug(config, method, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    debugLog(config, `${method} error`, formatError(error), "error");
+    throw error;
+  }
+}
 async function timedSendMessage(driver, images, prompt) {
   const start = performance.now();
   const response = await driver.sendMessage(images, prompt);
@@ -1124,16 +1162,18 @@ function visualAI(config = {}) {
     if (elements.length === 0) {
       throw new VisualAIConfigError(`At least one element is required for ${methodName}()`);
     }
-    const img = await normalizeImage(image);
-    const prompt = buildElementsVisibilityPrompt(elements, visible, options);
-    debugLog(resolvedConfig, `${methodName} prompt`, prompt);
-    const response = await timedSendMessage(driver, [img], prompt);
-    debugLog(resolvedConfig, `${methodName} response`, response.text);
-    const result = parseCheckResponse(response.text);
-    return {
-      ...result,
-      usage: processUsage(methodName, response.usage, response.durationSeconds, resolvedConfig)
-    };
+    return withErrorDebug(resolvedConfig, methodName, async () => {
+      const img = await normalizeImage(image);
+      const prompt = buildElementsVisibilityPrompt(elements, visible, options);
+      debugLog(resolvedConfig, `${methodName} prompt`, prompt, "prompt");
+      const response = await timedSendMessage(driver, [img], prompt);
+      debugLog(resolvedConfig, `${methodName} response`, response.text, "response");
+      const result = parseCheckResponse(response.text);
+      return {
+        ...result,
+        usage: processUsage(methodName, response.usage, response.durationSeconds, resolvedConfig)
+      };
+    });
   }
   return {
     async check(image, statements, options) {
@@ -1141,61 +1181,64 @@ function visualAI(config = {}) {
       if (stmts.length === 0) {
         throw new VisualAIConfigError("At least one statement is required for check()");
       }
-      const img = await normalizeImage(image);
-      const prompt = buildCheckPrompt(stmts, { instructions: options?.instructions });
-      debugLog(resolvedConfig, "check prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "check response", response.text);
-      const result = parseCheckResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage("check", response.usage, response.durationSeconds, resolvedConfig)
-      };
+      return withErrorDebug(resolvedConfig, "check", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildCheckPrompt(stmts, { instructions: options?.instructions });
+        debugLog(resolvedConfig, "check prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "check response", response.text, "response");
+        const result = parseCheckResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage("check", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     },
     async ask(image, userPrompt, options) {
-      const img = await normalizeImage(image);
-      const prompt = buildAskPrompt(userPrompt, { instructions: options?.instructions });
-      debugLog(resolvedConfig, "ask prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "ask response", response.text);
-      const result = parseAskResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage("ask", response.usage, response.durationSeconds, resolvedConfig)
-      };
+      return withErrorDebug(resolvedConfig, "ask", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildAskPrompt(userPrompt, { instructions: options?.instructions });
+        debugLog(resolvedConfig, "ask prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "ask response", response.text, "response");
+        const result = parseAskResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage("ask", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     },
     async compare(imageA, imageB, options) {
-      const [imgA, imgB] = await Promise.all([normalizeImage(imageA), normalizeImage(imageB)]);
-      const prompt = buildComparePrompt({
-        userPrompt: options?.prompt,
-        instructions: options?.instructions
-      });
-      debugLog(resolvedConfig, "compare prompt", prompt);
-      const response = await timedSendMessage(driver, [imgA, imgB], prompt);
-      debugLog(resolvedConfig, "compare response", response.text);
-      const supportsAnnotatedDiff = resolvedConfig.provider === "google" && resolvedConfig.model === Model.Google.GEMINI_3_FLASH_PREVIEW;
-      const effectiveDiffImage = options?.diffImage ?? (supportsAnnotatedDiff ? true : false);
-      let diffImage;
-      if (effectiveDiffImage) {
-        try {
-          diffImage = await generateAiDiff(imgA, imgB, resolvedConfig.model, driver);
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          debugLog(resolvedConfig, "ai diff error", msg);
-          if (!resolvedConfig.debug) {
+      return withErrorDebug(resolvedConfig, "compare", async () => {
+        const [imgA, imgB] = await Promise.all([normalizeImage(imageA), normalizeImage(imageB)]);
+        const prompt = buildComparePrompt({
+          userPrompt: options?.prompt,
+          instructions: options?.instructions
+        });
+        debugLog(resolvedConfig, "compare prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [imgA, imgB], prompt);
+        debugLog(resolvedConfig, "compare response", response.text, "response");
+        const supportsAnnotatedDiff = resolvedConfig.provider === "google" && resolvedConfig.model === Model.Google.GEMINI_3_FLASH_PREVIEW;
+        const effectiveDiffImage = options?.diffImage ?? (supportsAnnotatedDiff ? true : false);
+        let diffImage;
+        if (effectiveDiffImage) {
+          try {
+            diffImage = await generateAiDiff(imgA, imgB, resolvedConfig.model, driver);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(
               `[visual-ai-assertions] warning: diff generation failed: ${msg}
 `
             );
           }
         }
-      }
-      const result = parseCompareResponse(response.text);
-      return {
-        ...result,
-        ...diffImage ? { diffImage } : {},
-        usage: processUsage("compare", response.usage, response.durationSeconds, resolvedConfig)
-      };
+        const result = parseCompareResponse(response.text);
+        return {
+          ...result,
+          ...diffImage ? { diffImage } : {},
+          usage: processUsage("compare", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     },
     elementsVisible(image, elements, options) {
       return checkElementsVisibility(image, elements, true, options);
@@ -1204,57 +1247,65 @@ function visualAI(config = {}) {
       return checkElementsVisibility(image, elements, false, options);
     },
     async accessibility(image, options) {
-      const img = await normalizeImage(image);
-      const prompt = buildAccessibilityPrompt(options);
-      debugLog(resolvedConfig, "accessibility prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "accessibility response", response.text);
-      const result = parseCheckResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage(
-          "accessibility",
-          response.usage,
-          response.durationSeconds,
-          resolvedConfig
-        )
-      };
+      return withErrorDebug(resolvedConfig, "accessibility", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildAccessibilityPrompt(options);
+        debugLog(resolvedConfig, "accessibility prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "accessibility response", response.text, "response");
+        const result = parseCheckResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage(
+            "accessibility",
+            response.usage,
+            response.durationSeconds,
+            resolvedConfig
+          )
+        };
+      });
     },
     async layout(image, options) {
-      const img = await normalizeImage(image);
-      const prompt = buildLayoutPrompt(options);
-      debugLog(resolvedConfig, "layout prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "layout response", response.text);
-      const result = parseCheckResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage("layout", response.usage, response.durationSeconds, resolvedConfig)
-      };
+      return withErrorDebug(resolvedConfig, "layout", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildLayoutPrompt(options);
+        debugLog(resolvedConfig, "layout prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "layout response", response.text, "response");
+        const result = parseCheckResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage("layout", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     },
     async pageLoad(image, options) {
-      const img = await normalizeImage(image);
-      const prompt = buildPageLoadPrompt(options);
-      debugLog(resolvedConfig, "pageLoad prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "pageLoad response", response.text);
-      const result = parseCheckResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage("pageLoad", response.usage, response.durationSeconds, resolvedConfig)
-      };
+      return withErrorDebug(resolvedConfig, "pageLoad", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildPageLoadPrompt(options);
+        debugLog(resolvedConfig, "pageLoad prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "pageLoad response", response.text, "response");
+        const result = parseCheckResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage("pageLoad", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     },
     async content(image, options) {
-      const img = await normalizeImage(image);
-      const prompt = buildContentPrompt(options);
-      debugLog(resolvedConfig, "content prompt", prompt);
-      const response = await timedSendMessage(driver, [img], prompt);
-      debugLog(resolvedConfig, "content response", response.text);
-      const result = parseCheckResponse(response.text);
-      return {
-        ...result,
-        usage: processUsage("content", response.usage, response.durationSeconds, resolvedConfig)
-      };
+      return withErrorDebug(resolvedConfig, "content", async () => {
+        const img = await normalizeImage(image);
+        const prompt = buildContentPrompt(options);
+        debugLog(resolvedConfig, "content prompt", prompt, "prompt");
+        const response = await timedSendMessage(driver, [img], prompt);
+        debugLog(resolvedConfig, "content response", response.text, "response");
+        const result = parseCheckResponse(response.text);
+        return {
+          ...result,
+          usage: processUsage("content", response.usage, response.durationSeconds, resolvedConfig)
+        };
+      });
     }
   };
 }
@@ -1330,7 +1381,6 @@ export {
   Provider,
   StatementResultSchema,
   UsageInfoSchema,
-  VALID_PROVIDERS,
   VisualAIAssertionError,
   VisualAIAuthError,
   VisualAIConfigError,