ai-sdk-guardrails 5.0.2 → 5.2.0

package/README.md

@@ -7,10 +7,10 @@ Add guardrails to your AI applications in one line of code. Block PII, prevent p
 [![npm version](https://img.shields.io/npm/v/ai-sdk-guardrails.svg?logo=npm&label=npm)](https://www.npmjs.com/package/ai-sdk-guardrails)
 [![downloads](https://img.shields.io/npm/dw/ai-sdk-guardrails.svg?label=downloads)](https://www.npmjs.com/package/ai-sdk-guardrails)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/ai-sdk-guardrails.svg?label=minzipped)](https://bundlephobia.com/package/ai-sdk-guardrails)
-[![license](https://img.shields.io/npm/l/ai-sdk-guardrails.svg?label=license)](./LICENSE)
+[![license](https://img.shields.io/npm/l/ai-sdk-guardrails.svg?label=license)](../../LICENSE)
 ![types](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript&logoColor=white)
 
-![Guardrails Demo](./media/guardrail-example.gif)
+![Guardrails Demo](../../media/guardrail-example.gif)
 
 ## Drop-in Guardrails for any AI model
 
@@ -39,7 +39,7 @@ npm install ai-sdk-guardrails
 
 **Don't want to write code?** Use our visual wizard to configure guardrails:
 
-1. **Open the wizard**: [wizard-prototype/index.html](./wizard-prototype/index.html)
+1. **Open the wizard**: [wizard-prototype/index.html](../../wizard-prototype/index.html)
 2. **Choose your use case**: Content moderation, data protection, quality assurance, or security
 3. **Select guardrails**: Pick from 40+ built-in guardrails
 4. **Configure settings**: Adjust thresholds and parameters with sliders and toggles
@@ -386,6 +386,191 @@ const agent = withAgentGuardrails(
 const result = await agent.generate({ prompt: '...' });
 ```
 
+## Advanced Stopping Mechanisms
+
+Control exactly **when and how** guardrails stop execution with powerful, composable stopping mechanisms:
+
+### 1. AbortSignal-Based Stopping
+
+Clean, standard API for canceling AI operations:
+
+```ts
+import { createGuardrailAbortController } from 'ai-sdk-guardrails';
+
+const { signal, abortOnViolation } = createGuardrailAbortController();
+
+const model = withGuardrails(openai('gpt-4o'), {
+  outputGuardrails: [toxicityFilter()],
+  onOutputBlocked: abortOnViolation('critical'), // Abort on critical violations
+});
+
+// Signal will be aborted if critical violation detected
+await streamText({ model, prompt: '...', abortSignal: signal });
+```
+
+**Features:**
+
+- Standard AbortController API
+- Severity-based abortion (`'low' | 'medium' | 'high' | 'critical'`)
+- Custom abort conditions
+- Manual abortion support
+
+### 2. Stream Transform with Source-Level Stopping
+
+Stop streaming at the **source** (most efficient):
+
+```ts
+import { createGuardrailStreamTransform } from 'ai-sdk-guardrails';
+
+const result = streamText({
+  model,
+  prompt: 'Tell me a story',
+  experimental_transform: createGuardrailStreamTransform(
+    [toxicityFilter(), piiDetector()],
+    {
+      stopOnSeverity: 'high', // Stop on high/critical
+      checkInterval: 1, // Check every chunk
+      onViolation: (summary) => {
+        // Violation callback
+        console.log('Stopped:', summary);
+      },
+    },
+  ),
+});
+```
+
+**Modes:**
+
+- `createGuardrailStreamTransform` - Progressive checking (each chunk)
+- `createGuardrailStreamTransformBuffered` - Buffered checking (on flush)
+
+### 3. Token-Level Control
+
+Reduce overhead with smart token-based checking:
+
+```ts
+import {
+  createTokenBudgetTransform,
+  createTokenAwareGuardrailTransform,
+} from 'ai-sdk-guardrails';
+
+experimental_transform: [
+  // Hard token limit
+  createTokenBudgetTransform({
+    maxTokens: 1000,
+    onBudgetExceeded: (info) => console.log(info),
+  }),
+
+  // Check guardrails every N tokens (not every chunk!)
+  createTokenAwareGuardrailTransform([toxicityFilter()], {
+    checkEveryTokens: 50, // Check every 50 tokens
+    maxTokens: 1000, // Combined with budget
+    stopOnSeverity: 'high',
+  }),
+];
+```
+
+**Benefits:**
+
+- Reduce guardrail overhead by 80%+
+- Cost control with token budgets
+- Custom tokenizer support
+
+### 4. Adaptive Multi-Step Execution
+
+Self-correcting behavior across multi-step agent execution:
+
+```ts
+import {
+  createAdaptivePrepareStep,
+  type GuardrailViolation,
+} from 'ai-sdk-guardrails';
+
+const violations: GuardrailViolation[] = [];
+
+const agent = new Agent({
+  model,
+  tools: { search: searchTool },
+  prepareStep: createAdaptivePrepareStep({
+    violations,
+    escalateAfter: 3, // Stop after 3 violations
+    strategy: (violations) => ({
+      temperature: Math.max(0.1, 0.7 - violations.length * 0.1),
+      system: `${violations.length} violations detected. Be careful.`,
+    }),
+  }),
+});
+
+// Track violations
+withAgentGuardrails(agent, {
+  outputGuardrails: [toxicityFilter()],
+  onOutputBlocked: (summary, context, step) => {
+    violations.push({ step, summary });
+  },
+});
+```
+
+**Features:**
+
+- Progressive temperature reduction
+- Custom adaptive strategies
+- Escalation to auto-stop
+- Lookback window configuration
+
+### 5. Tool Execution Abortion
+
+Prevent dangerous tool execution before or during execution:
+
+```ts
+import { wrapToolWithAbortion } from 'ai-sdk-guardrails';
+
+const safeTool = wrapToolWithAbortion(
+  dangerousApiTool,
+  [urlValidator, paramValidator],
+  {
+    checkBefore: true, // Validate before execution
+    monitorDuring: true, // Monitor during execution
+    monitorInterval: 1000, // Check every second
+    checkInputDelta: true, // Monitor streaming inputs
+    abortOnSeverity: 'critical',
+  },
+);
+```
+
+**Protection:**
+
+- Pre-execution validation
+- Real-time monitoring
+- Streaming input checking
+- Manual abortion control
+
+### 6. Finish Reason & Metadata
+
+Better observability with proper finish reasons and metadata:
+
+```ts
+import { createFinishReasonEnhancement } from 'ai-sdk-guardrails';
+
+// Automatically set in middleware, or manually:
+const enhanced = createFinishReasonEnhancement(summary, result);
+
+console.log(enhanced.finishReason); // 'content_filter' for blocks
+console.log(enhanced.providerMetadata.guardrails);
+// {
+//   blocked: true,
+//   violations: [{ message: '...', severity: 'high', ... }],
+//   executionTime: 50,
+//   stats: { passed: 2, blocked: 1, failed: 0 }
+// }
+```
+
+**Features:**
+
+- Standard `content_filter` finish reason
+- Structured violation metadata
+- Execution statistics
+- Custom metadata preservation
+
 ## MCP Security Guardrails (Advanced)
 
 **Production-Ready**: Protect against the ["lethal trifecta" vulnerability](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) when using Model Context Protocol (MCP) tools.
@@ -487,9 +672,9 @@ const model = withGuardrails(openai('gpt-4o'), {
 
 See complete examples:
 
-- [Production MCP Configuration](./examples/44-production-mcp-config.ts)
-- [MCP Security Test Suite](./examples/41-mcp-security-test.ts)
-- [Enhanced Security Testing](./examples/43-enhanced-mcp-security-test.ts)
+- [Production MCP Configuration](../examples/44-production-mcp-config.ts)
+- [MCP Security Test Suite](../examples/41-mcp-security-test.ts)
+- [Enhanced Security Testing](../examples/43-enhanced-mcp-security-test.ts)
 
 ## Error Handling
 
@@ -559,50 +744,50 @@ See source for all built-in guardrails:
 
 ## Examples
 
-Browse 48+ runnable examples: [examples/README.md](./examples/README.md) |
+Browse 48+ runnable examples: [examples/README.md](../examples/README.md) |
 
 ### Quick Starts
 
-| Example                    | Description                     | File                                                                              |
-| -------------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
-| Simple combined protection | Minimal input and output setup  | [07a-simple-combined-protection.ts](./examples/07a-simple-combined-protection.ts) |
-| Auto retry on output       | Retry until output meets a rule | [32-auto-retry-output.ts](./examples/32-auto-retry-output.ts)                     |
-| LLM judge auto-retry       | Judge feedback drives retry     | [35-judge-auto-retry.ts](./examples/35-judge-auto-retry.ts)                       |
-| Weather assistant          | End-to-end input/output + retry | [33-blog-post-weather-assistant.ts](./examples/33-blog-post-weather-assistant.ts) |
+| Example                    | Description                     | File                                                                               |
+| -------------------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| Simple combined protection | Minimal input and output setup  | [07a-simple-combined-protection.ts](../examples/07a-simple-combined-protection.ts) |
+| Auto retry on output       | Retry until output meets a rule | [32-auto-retry-output.ts](../examples/32-auto-retry-output.ts)                     |
+| LLM judge auto-retry       | Judge feedback drives retry     | [35-judge-auto-retry.ts](../examples/35-judge-auto-retry.ts)                       |
+| Weather assistant          | End-to-end input/output + retry | [33-blog-post-weather-assistant.ts](../examples/33-blog-post-weather-assistant.ts) |
 
 ### Input Safety
 
-| Example            | Description                         | File                                                            |
-| ------------------ | ----------------------------------- | --------------------------------------------------------------- |
-| Input length limit | Enforce max input length            | [01-input-length-limit.ts](./examples/01-input-length-limit.ts) |
-| Blocked keywords   | Block specific terms                | [02-blocked-keywords.ts](./examples/02-blocked-keywords.ts)     |
-| PII detection      | Detect PII before calling the model | [03-pii-detection.ts](./examples/03-pii-detection.ts)           |
-| Rate limiting      | Simple per-user rate limit          | [13-rate-limiting.ts](./examples/13-rate-limiting.ts)           |
+| Example            | Description                         | File                                                             |
+| ------------------ | ----------------------------------- | ---------------------------------------------------------------- |
+| Input length limit | Enforce max input length            | [01-input-length-limit.ts](../examples/01-input-length-limit.ts) |
+| Blocked keywords   | Block specific terms                | [02-blocked-keywords.ts](../examples/02-blocked-keywords.ts)     |
+| PII detection      | Detect PII before calling the model | [03-pii-detection.ts](../examples/03-pii-detection.ts)           |
+| Rate limiting      | Simple per-user rate limit          | [13-rate-limiting.ts](../examples/13-rate-limiting.ts)           |
 
 ### Output Safety
 
-| Example                 | Description                         | File                                                                      |
-| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
-| Output length check     | Require min/max output length       | [04-output-length-check.ts](./examples/04-output-length-check.ts)         |
-| Sensitive output filter | Filter secrets and PII in responses | [05-sensitive-output-filter.ts](./examples/05-sensitive-output-filter.ts) |
-| Hallucination detection | Flag uncertain factual claims       | [19-hallucination-detection.ts](./examples/19-hallucination-detection.ts) |
+| Example                 | Description                         | File                                                                       |
+| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
+| Output length check     | Require min/max output length       | [04-output-length-check.ts](../examples/04-output-length-check.ts)         |
+| Sensitive output filter | Filter secrets and PII in responses | [05-sensitive-output-filter.ts](../examples/05-sensitive-output-filter.ts) |
+| Hallucination detection | Flag uncertain factual claims       | [19-hallucination-detection.ts](../examples/19-hallucination-detection.ts) |
 
 ### Streaming
 
-| Example           | Description                        | File                                                                              |
-| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
-| Streaming limits  | Apply limits in buffered streaming | [11-streaming-limits.ts](./examples/11-streaming-limits.ts)                       |
-| Streaming quality | Quality checks with streaming      | [12-streaming-quality.ts](./examples/12-streaming-quality.ts)                     |
-| Early termination | Stop streams early when blocked    | [28-streaming-early-termination.ts](./examples/28-streaming-early-termination.ts) |
+| Example           | Description                        | File                                                                               |
+| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
+| Streaming limits  | Apply limits in buffered streaming | [11-streaming-limits.ts](../examples/11-streaming-limits.ts)                       |
+| Streaming quality | Quality checks with streaming      | [12-streaming-quality.ts](../examples/12-streaming-quality.ts)                     |
+| Early termination | Stop streams early when blocked    | [28-streaming-early-termination.ts](../examples/28-streaming-early-termination.ts) |
 
 ### Advanced
 
-| Example                    | Description                   | File                                                                            |
-| -------------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
-| Simple quality judge       | Cheaper model judges quality  | [15a-simple-quality-judge.ts](./examples/15a-simple-quality-judge.ts)           |
-| Secret leakage scan        | Scan responses for secrets    | [18-secret-leakage-scan.ts](./examples/18-secret-leakage-scan.ts)               |
-| SQL code safety            | Basic SQL safety checks       | [24-sql-code-safety.ts](./examples/24-sql-code-safety.ts)                       |
-| Role hierarchy enforcement | Enforce role rules in prompts | [23-role-hierarchy-enforcement.ts](./examples/23-role-hierarchy-enforcement.ts) |
+| Example                    | Description                   | File                                                                             |
+| -------------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
+| Simple quality judge       | Cheaper model judges quality  | [15a-simple-quality-judge.ts](../examples/15a-simple-quality-judge.ts)           |
+| Secret leakage scan        | Scan responses for secrets    | [18-secret-leakage-scan.ts](../examples/18-secret-leakage-scan.ts)               |
+| SQL code safety            | Basic SQL safety checks       | [24-sql-code-safety.ts](../examples/24-sql-code-safety.ts)                       |
+| Role hierarchy enforcement | Enforce role rules in prompts | [23-role-hierarchy-enforcement.ts](../examples/23-role-hierarchy-enforcement.ts) |
 
 ## Migration from v3.x
 
@@ -652,4 +837,4 @@ Issues and PRs are welcome.
 
 ## License
 
-MIT © Jag Reehal. See [LICENSE](./LICENSE) for details.
+MIT © Jag Reehal. See [LICENSE](../../LICENSE) for details.

package/dist/{chunk-CSUDFTRH.js → chunk-2QL3CFHU.js}

@@ -1,6 +1,6 @@
 import {
   createInputGuardrail
-} from "./chunk-VKJ5EAS7.js";
+} from "./chunk-CB2WX5S7.js";
 
 // src/guardrails/input.ts
 var SEVERITY_LEVELS = {
@@ -141,7 +141,14 @@ var inputLengthLimit = (options) => {
         tripwireTriggered: currentLength > opts.maxLength,
         message: currentLength > opts.maxLength ? `Input ${unit} count ${currentLength} exceeds limit of ${opts.maxLength}` : void 0,
         severity: opts.severity,
-        metadata
+        metadata,
+        info: {
+          guardrailName: "input-length-limit",
+          currentLength,
+          maxLength: opts.maxLength,
+          countMethod: opts.countMethod,
+          unit
+        }
       };
     }
   );
@@ -179,7 +186,12 @@ var blockedWords = (options) => {
             metadata: createStandardMetadata("GR-IN-002", context, {
               allowlistMatched: true,
               blockedWords: opts.words
-            })
+            }),
+            info: {
+              guardrailName: "blocked-words",
+              allowlistMatched: true,
+              blockedWords: opts.words
+            }
           };
         }
       }
@@ -196,7 +208,13 @@ var blockedWords = (options) => {
         tripwireTriggered: !!blockedWord,
         message: blockedWord ? `Blocked word detected: ${blockedWord.word}` : void 0,
         severity: opts.severity,
-        metadata
+        metadata,
+        info: {
+          guardrailName: "blocked-words",
+          blockedWord: blockedWord?.word,
+          allWords: opts.words,
+          allowlist: opts.allowlist
+        }
       };
     }
   );
@@ -278,7 +296,14 @@ var rateLimiting = (options) => {
           ...metadata,
           ...opts.includeServerHints && { serverHints }
         },
-        suggestion: isRateLimited ? `Please wait ${Math.ceil(recommendedBackoff / 1e3)} seconds before making another request` : void 0
+        suggestion: isRateLimited ? `Please wait ${Math.ceil(recommendedBackoff / 1e3)} seconds before making another request` : void 0,
+        info: {
+          guardrailName: "rate-limiting",
+          currentCount: current.count,
+          maxRequests: opts.maxRequestsPerMinute,
+          isRateLimited,
+          timeUntilReset
+        }
       };
     }
   );
@@ -352,7 +377,13 @@ var profanityFilter = (options = {}) => {
         message: detectedProfanity ? `Profanity detected (${detectedProfanity.category}): ${detectedProfanity.word}` : void 0,
         severity: detectedProfanity?.severity || SEVERITY_LEVELS.HIGH,
         metadata,
-        suggestion: "Please use respectful and appropriate language"
+        suggestion: "Please use respectful and appropriate language",
+        info: {
+          guardrailName: "profanity-filter",
+          profaneWord: detectedProfanity?.word,
+          category: detectedProfanity?.category,
+          locale: opts.locale
+        }
       };
     }
   );
@@ -394,7 +425,12 @@ var customValidation = (options) => {
       tripwireTriggered: !isValid,
       message: isValid ? void 0 : opts.message || `Custom validation failed: ${reasonCode || "unknown reason"}`,
       severity: opts.severity,
-      metadata
+      metadata,
+      info: {
+        guardrailName: opts.name,
+        isValid,
+        reasonCode
+      }
     };
   });
 };
@@ -537,7 +573,13 @@ var promptInjectionDetector = (options = {}) => {
         message: confidence > threshold ? `Potential prompt injection detected (confidence: ${(confidence * 100).toFixed(1)}%): ${detectedPatterns.length} suspicious patterns found` : void 0,
         severity: confidence > 0.8 ? SEVERITY_LEVELS.CRITICAL : SEVERITY_LEVELS.HIGH,
         metadata,
-        suggestion: "Please rephrase your request without system instructions or role-playing elements"
+        suggestion: "Please rephrase your request without system instructions or role-playing elements",
+        info: {
+          guardrailName: "prompt-injection-detector",
+          confidence,
+          threshold,
+          detectedPatternsCount: detectedPatterns.length
+        }
       };
     }
   );
@@ -622,7 +664,12 @@ var piiDetector = () => createInputGuardrail(
       message: detectedPII.length > 0 ? `PII detected: ${detectedPII.map((pii) => `${pii.type} (${pii.matches.length})`).join(", ")}` : void 0,
       severity: SEVERITY_LEVELS.CRITICAL,
       metadata,
-      suggestion: "Please remove any personal information (emails, phone numbers, SSNs, etc.) from your input"
+      suggestion: "Please remove any personal information (emails, phone numbers, SSNs, etc.) from your input",
+      info: {
+        guardrailName: "pii-detector",
+        piiTypes: detectedPII.map((pii) => pii.type),
+        totalMatches
+      }
     };
   }
 );
@@ -658,7 +705,14 @@ var toxicityDetector = (threshold = 0.7) => createInputGuardrail(
         detectedWords,
         textLength: allText.length
       },
-      suggestion: "Please use respectful and constructive language"
+      suggestion: "Please use respectful and constructive language",
+      info: {
+        guardrailName: "toxicity-detector",
+        toxicityScore,
+        threshold,
+        detectedWords,
+        textLength: allText.length
+      }
     };
   }
 );
@@ -673,7 +727,12 @@ var mathHomeworkDetector = (options = {}) => {
     return createInputGuardrail(
       "math-homework-detector",
       "Math homework detection (disabled)",
-      () => ({ tripwireTriggered: false })
+      () => ({
+        tripwireTriggered: false,
+        info: {
+          guardrailName: "math-homework-detector"
+        }
+      })
     );
   }
   const mathKeywords = [
@@ -720,7 +779,13 @@ var mathHomeworkDetector = (options = {}) => {
             educationalContext: hasEducationalContext,
             allowedContext: hasAllowedContext,
             policy: "educational-use-allowed"
-          })
+          }),
+          info: {
+            guardrailName: "math-homework-detector",
+            educationalContext: hasEducationalContext,
+            allowedContext: hasAllowedContext,
+            policy: "educational-use-allowed"
+          }
         };
       }
       const keywordMatches = mathKeywords.filter(
@@ -742,6 +807,13 @@ var mathHomeworkDetector = (options = {}) => {
         message: isMathHomework ? "Math homework request detected" : void 0,
         severity,
         metadata,
+        info: {
+          guardrailName: "math-homework-detector",
+          isMathHomework,
+          keywordMatches: keywordMatches.length,
+          patternMatches: patternMatches.length,
+          strictMode
+        },
         suggestion: "Try asking about learning concepts instead of solving specific problems"
       };
     }
@@ -844,7 +916,12 @@ var codeGenerationLimiter = (options = {}) => {
           metadata: createStandardMetadata("GR-IN-008", context, {
             hasCodeRequest: false,
             mode: opts.mode
-          })
+          }),
+          info: {
+            guardrailName: "code-generation-limiter",
+            hasCodeRequest: false,
+            mode: opts.mode
+          }
         };
       }
       const detectedLanguages = [];
@@ -880,6 +957,13 @@ var codeGenerationLimiter = (options = {}) => {
         message: isBlocked ? `Code generation blocked for language(s): ${blockedLanguages.join(", ")}` : void 0,
         severity: opts.severity,
         metadata,
+        info: {
+          guardrailName: "code-generation-blocker",
+          isBlocked,
+          detectedLanguages: uniqueLanguages,
+          blockedLanguages,
+          mode: opts.mode
+        },
         suggestion: opts.mode === "deny" ? `Please avoid requesting code in these languages: ${opts.deniedLanguages?.join(", ")}` : `Please request code only in allowed languages: ${opts.allowedLanguages?.join(", ")}`
       };
     }
@@ -990,6 +1074,11 @@ var allowedToolsGuardrail = (options) => {
             allowedTools,
             deniedTools,
             detectionMethod: "none"
+          },
+          info: {
+            guardrailName: "allowed-tools-guardrail",
+            detectedTools: [],
+            detectionMethod: "none"
           }
         };
       }
@@ -1029,7 +1118,15 @@ var allowedToolsGuardrail = (options) => {
             naturalLanguageTools,
             textLength: allText.length
           },
-          suggestion: "Remove unauthorized tool calls or update the allowed tools configuration"
+          suggestion: "Remove unauthorized tool calls or update the allowed tools configuration",
+          info: {
+            guardrailName: "allowed-tools-guardrail",
+            detectedTools: allDetectedTools,
+            blockedTools,
+            violations,
+            allowedTools,
+            deniedTools
+          }
         };
       }
       return {
@@ -1041,6 +1138,11 @@ var allowedToolsGuardrail = (options) => {
           deniedTools,
           contextToolCalls,
           naturalLanguageTools
+        },
+        info: {
+          guardrailName: "allowed-tools-guardrail",
+          detectedTools: allDetectedTools,
+          allToolsAllowed: true
         }
       };
     }

package/dist/{chunk-VKJ5EAS7.js → chunk-CB2WX5S7.js}

@@ -151,8 +151,6 @@ function extractErrorInfo(error) {
     message: String(error)
   };
 }
-var InputBlockedError = GuardrailsInputError;
-var OutputBlockedError = GuardrailsOutputError;
 
 // src/core.ts
 function createInputGuardrail(name, description, execute) {
@@ -388,8 +386,6 @@ export {
   MiddlewareError,
   isGuardrailsError,
   extractErrorInfo,
-  InputBlockedError,
-  OutputBlockedError,
   createInputGuardrail,
   createOutputGuardrail,
   retry,