More robust handling of checking guardrailLlm client type (#32)

* Properly pass back execution errors
* Remove unneeded OAI check
* Extract error helper
* Copilot comments

Author: steven10a

src/__tests__/unit/checks/moderation-secret-keys.test.ts

@@ -65,7 +65,23 @@ describe('moderation guardrail', () => {
     const result = await moderationCheck({}, 'safe text', ModerationConfig.parse({}));
 
     expect(result.tripwireTriggered).toBe(false);
-    expect(result.info?.error).toBe('Moderation API call failed');
+    expect(result.executionFailed).toBe(true);
+    expect(result.originalException).toBeDefined();
+    expect(result.info?.error).toContain('network down');
+  });
+
+  it('returns executionFailed for API key errors to support raiseGuardrailErrors', async () => {
+    const apiKeyError = new Error(
+      'Incorrect API key provided: sk-invalid. You can find your API key at https://platform.openai.com/account/api-keys.'
+    );
+    createMock.mockRejectedValue(apiKeyError);
+
+    const result = await moderationCheck({}, 'test text', ModerationConfig.parse({}));
+
+    expect(result.tripwireTriggered).toBe(false);
+    expect(result.executionFailed).toBe(true);
+    expect(result.originalException).toBe(apiKeyError);
+    expect(result.info?.error).toContain('Incorrect API key');
   });
 
   it('uses context client when available', async () => {

src/checks/moderation.ts

@@ -89,6 +89,17 @@ function isNotFoundError(error: unknown): boolean {
   return !!(error && typeof error === 'object' && 'status' in error && error.status === 404);
 }
 
+/**
+ * Ensure a value is an Error instance.
+ * Converts non-Error values to Error instances with a string representation.
+ *
+ * @param error The error value to convert
+ * @returns An Error instance
+ */
+function ensureError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
 /**
  * Call the OpenAI moderation API.
  *
@@ -144,8 +155,9 @@ export const moderationCheck: CheckFn<ModerationContext, string, ModerationConfi
   if (ctx) {
     const contextObj = ctx as Record<string, unknown>;
     const candidate = contextObj.guardrailLlm;
-    if (candidate && candidate instanceof OpenAI) {
-      client = candidate;
+    // Just use whatever is provided, let the try-catch handle validation
+    if (candidate) {
+      client = candidate as OpenAI;
     }
   }
 
@@ -162,25 +174,32 @@ export const moderationCheck: CheckFn<ModerationContext, string, ModerationConfi
           try {
             resp = await callModerationAPI(new OpenAI(), data);
           } catch (fallbackError) {
-            // If fallback fails, provide a helpful error message
-            const errorMessage = fallbackError instanceof Error 
-              ? fallbackError.message 
-              : String(fallbackError);
-            
-            // Check if it's an API key error
-            if (errorMessage.includes('api_key') || errorMessage.includes('OPENAI_API_KEY')) {
-              return {
-                tripwireTriggered: false,
-                info: {
-                  checked_text: data,
-                  error: 'Moderation API requires OpenAI API key. Set OPENAI_API_KEY environment variable or pass a client with valid credentials.',
-                },
-              };
-            }
-            throw fallbackError;
+            // If fallback fails, return execution failure
+            // This allows runGuardrails to handle based on raiseGuardrailErrors flag
+            const errorObj = ensureError(fallbackError);
+            return {
+              tripwireTriggered: false,
+              executionFailed: true,
+              originalException: errorObj,
+              info: {
+                checked_text: data,
+                error: errorObj.message,
+              },
+            };
           }
         } else {
-          throw error;
+          // Non-404 error from context client - return execution failure
+          // This allows runGuardrails to handle based on raiseGuardrailErrors flag
+          const errorObj = ensureError(error);
+          return {
+            tripwireTriggered: false,
+            executionFailed: true,
+            originalException: errorObj,
+            info: {
+              checked_text: data,
+              error: errorObj.message,
+            },
+          };
         }
       }
     } else {
@@ -230,11 +249,14 @@ export const moderationCheck: CheckFn<ModerationContext, string, ModerationConfi
     };
   } catch (error) {
     console.warn('AI-based moderation failed:', error);
+    const errorObj = ensureError(error);
     return {
       tripwireTriggered: false,
+      executionFailed: true,
+      originalException: errorObj,
       info: {
         checked_text: data,
-        error: 'Moderation API call failed',
+        error: errorObj.message,
       },
     };
   }