ai-sdk-guardrails 5.0.2 → 5.1.0

package/README.md

@@ -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.

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,

package/dist/{chunk-CSUDFTRH.js → chunk-OP5XB2DJ.js}

@@ -1,6 +1,6 @@
 import {
   createInputGuardrail
-} from "./chunk-VKJ5EAS7.js";
+} from "./chunk-CB2WX5S7.js";
 
 // src/guardrails/input.ts
 var SEVERITY_LEVELS = {

package/dist/{chunk-ND2ICBTR.js → chunk-XWDH2NCM.js}

@@ -1,6 +1,6 @@
 import {
   createOutputGuardrail
-} from "./chunk-VKJ5EAS7.js";
+} from "./chunk-CB2WX5S7.js";
 
 // src/guardrails/output.ts
 var EMPTY_CONTENT = {

package/dist/{chunk-LVXHWHZC.js → chunk-ZZFNRQAT.js}

@@ -1,9 +1,9 @@
 import {
   extractContent
-} from "./chunk-ND2ICBTR.js";
+} from "./chunk-XWDH2NCM.js";
 import {
   createOutputGuardrail
-} from "./chunk-VKJ5EAS7.js";
+} from "./chunk-CB2WX5S7.js";
 
 // src/guardrails/tools.ts
 function defaultMarker(tool) {

package/dist/guardrails/input.d.cts

@@ -1,4 +1,4 @@
-import { I as InputGuardrail, a as InputGuardrailContext } from '../types-CeZi2BBN.cjs';
+import { I as InputGuardrail, a as InputGuardrailContext } from '../types-WcM_8Gvq.cjs';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/input.d.ts

@@ -1,4 +1,4 @@
-import { I as InputGuardrail, a as InputGuardrailContext } from '../types-CeZi2BBN.js';
+import { I as InputGuardrail, a as InputGuardrailContext } from '../types-WcM_8Gvq.js';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/input.js

@@ -15,8 +15,8 @@ import {
   promptInjectionDetector,
   rateLimiting,
   toxicityDetector
-} from "../chunk-CSUDFTRH.js";
-import "../chunk-VKJ5EAS7.js";
+} from "../chunk-OP5XB2DJ.js";
+import "../chunk-CB2WX5S7.js";
 export {
   allowedToolsGuardrail,
   blockedKeywords,

package/dist/guardrails/output.d.cts

@@ -1,4 +1,4 @@
-import { O as OutputGuardrail, A as AIResult } from '../types-CeZi2BBN.cjs';
+import { O as OutputGuardrail, A as AIResult } from '../types-WcM_8Gvq.cjs';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/output.d.ts

@@ -1,4 +1,4 @@
-import { O as OutputGuardrail, A as AIResult } from '../types-CeZi2BBN.js';
+import { O as OutputGuardrail, A as AIResult } from '../types-WcM_8Gvq.js';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/output.js

@@ -24,8 +24,8 @@ import {
   tokenUsageLimit,
   toxicityFilter,
   unsafeContentDetector
-} from "../chunk-ND2ICBTR.js";
-import "../chunk-VKJ5EAS7.js";
+} from "../chunk-XWDH2NCM.js";
+import "../chunk-CB2WX5S7.js";
 export {
   biasDetector,
   blockedContent,

package/dist/guardrails/tools.d.cts

@@ -1,4 +1,4 @@
-import { A as AIResult, O as OutputGuardrail } from '../types-CeZi2BBN.cjs';
+import { A as AIResult, O as OutputGuardrail } from '../types-WcM_8Gvq.cjs';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/tools.d.ts

@@ -1,4 +1,4 @@
-import { A as AIResult, O as OutputGuardrail } from '../types-CeZi2BBN.js';
+import { A as AIResult, O as OutputGuardrail } from '../types-WcM_8Gvq.js';
 import 'ai';
 import '@ai-sdk/provider';
 import '@opentelemetry/api';

package/dist/guardrails/tools.js

@@ -1,9 +1,9 @@
 import {
   expectedToolUse,
   toolEgressPolicy
-} from "../chunk-LVXHWHZC.js";
-import "../chunk-ND2ICBTR.js";
-import "../chunk-VKJ5EAS7.js";
+} from "../chunk-ZZFNRQAT.js";
+import "../chunk-XWDH2NCM.js";
+import "../chunk-CB2WX5S7.js";
 export {
   expectedToolUse,
   toolEgressPolicy