agentshield-sdk 13.5.0 → 14.2.0

package/src/integrations-frameworks.js

@@ -0,0 +1,463 @@
+'use strict';
+
+/**
+ * Agent Shield — Framework Integration Wrappers
+ *
+ * Plug-and-play integrations for next-generation AI agent frameworks:
+ * - CrewAI (task decorators & callbacks)
+ * - Google Agent Development Kit (plugin system)
+ * - Microsoft Agent Framework (middleware pipeline)
+ *
+ * These close gaps identified in the Microsoft Agent Governance Toolkit
+ * parity audit.
+ *
+ * @module integrations-frameworks
+ */
+
+const { AgentShield } = require('./index');
+const { ShieldBlockError } = require('./integrations');
+
+// =========================================================================
+// CrewAI Integration
+// =========================================================================
+
+/**
+ * Creates Agent Shield callbacks for CrewAI task lifecycle.
+ *
+ * CrewAI uses task decorators and callbacks. This wrapper provides
+ * beforeTask / afterTask hooks that scan task descriptions, expected
+ * outputs, and task results for prompt injection and other threats.
+ *
+ * Usage:
+ *   const { shieldCrewAI } = require('agentshield-sdk/src/integrations-frameworks');
+ *   const { beforeTask, afterTask } = shieldCrewAI({ blockOnThreat: true });
+ *
+ *   // In your CrewAI task lifecycle:
+ *   beforeTask(task, agent);       // throws ShieldBlockError if threat found
+ *   const output = await task.run();
+ *   afterTask(task, output);       // throws ShieldBlockError if threat found
+ *
+ * @param {object} [options]
+ * @param {string} [options.sensitivity='high'] - Detection sensitivity level.
+ * @param {boolean} [options.blockOnThreat=true] - Whether to throw on threat detection.
+ * @param {string} [options.blockThreshold='high'] - Minimum severity that triggers a block.
+ * @param {function} [options.onThreat] - Callback when a threat is detected.
+ * @returns {{ beforeTask: function, afterTask: function, shield: AgentShield }}
+ */
+function shieldCrewAI(options = {}) {
+  const shield = new AgentShield({
+    sensitivity: options.sensitivity || 'high',
+    blockOnThreat: options.blockOnThreat !== false,
+    blockThreshold: options.blockThreshold || 'high'
+  });
+  const onThreat = options.onThreat || null;
+
+  /**
+   * Scans a CrewAI task before execution.
+   * Inspects task.description and task.expected_output for injection.
+   *
+   * @param {object} task - CrewAI task object.
+   * @param {object} [agent] - CrewAI agent assigned to the task.
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  function beforeTask(task, agent) {
+    if (!task) return;
+
+    const fields = [];
+    if (task.description) fields.push(String(task.description));
+    if (task.expected_output) fields.push(String(task.expected_output));
+
+    for (const text of fields) {
+      const result = shield.scanInput(text);
+      if (result.threats && result.threats.length > 0) {
+        if (onThreat) {
+          try {
+            onThreat({
+              phase: 'before_task',
+              threats: result.threats,
+              task: task.description || '',
+              agent: agent && agent.role ? agent.role : undefined
+            });
+          } catch (e) {
+            console.error('[Agent Shield] onThreat callback error:', e.message);
+          }
+        }
+        if (result.blocked) {
+          throw new ShieldBlockError('CrewAI task blocked by Agent Shield', result.threats);
+        }
+      }
+    }
+  }
+
+  /**
+   * Scans a CrewAI task output after execution.
+   *
+   * @param {object} task - CrewAI task object.
+   * @param {*} output - Task execution output.
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  function afterTask(task, output) {
+    if (output == null) return;
+
+    const text = typeof output === 'string' ? output : JSON.stringify(output);
+    const result = shield.scanOutput(text);
+
+    if (result.threats && result.threats.length > 0) {
+      if (onThreat) {
+        try {
+          onThreat({
+            phase: 'after_task',
+            threats: result.threats,
+            task: task && task.description ? task.description : ''
+          });
+        } catch (e) {
+          console.error('[Agent Shield] onThreat callback error:', e.message);
+        }
+      }
+      if (result.blocked) {
+        throw new ShieldBlockError('CrewAI task output blocked by Agent Shield', result.threats);
+      }
+    }
+  }
+
+  return { beforeTask, afterTask, shield };
+}
+
+// =========================================================================
+// Google Agent Development Kit (ADK) Integration
+// =========================================================================
+
+/**
+ * Creates Agent Shield hooks for the Google Agent Development Kit plugin system.
+ *
+ * Google ADK uses a plugin architecture with lifecycle hooks. This wrapper
+ * provides beforeToolCall, afterToolCall, and beforeGenerate functions that
+ * scan tool arguments, tool results, and generation prompts for threats.
+ *
+ * Usage:
+ *   const { shieldGoogleADK } = require('agentshield-sdk/src/integrations-frameworks');
+ *   const hooks = shieldGoogleADK({ blockOnThreat: true });
+ *
+ *   // Register as ADK plugin callbacks:
+ *   hooks.beforeToolCall('web_search', { query: userInput });
+ *   const result = await tool.execute(args);
+ *   hooks.afterToolCall('web_search', result);
+ *   hooks.beforeGenerate(prompt);
+ *
+ * @param {object} [options]
+ * @param {string} [options.sensitivity='high'] - Detection sensitivity level.
+ * @param {boolean} [options.blockOnThreat=true] - Whether to throw on threat detection.
+ * @param {string} [options.blockThreshold='high'] - Minimum severity that triggers a block.
+ * @param {function} [options.onThreat] - Callback when a threat is detected.
+ * @returns {{ beforeToolCall: function, afterToolCall: function, beforeGenerate: function, shield: AgentShield }}
+ */
+function shieldGoogleADK(options = {}) {
+  const shield = new AgentShield({
+    sensitivity: options.sensitivity || 'high',
+    blockOnThreat: options.blockOnThreat !== false,
+    blockThreshold: options.blockThreshold || 'high'
+  });
+  const onThreat = options.onThreat || null;
+
+  /**
+   * Scans tool arguments before a tool call.
+   *
+   * @param {string} toolName - Name of the tool being called.
+   * @param {*} args - Tool arguments (object, string, or any serializable value).
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  function beforeToolCall(toolName, args) {
+    if (args == null) return;
+
+    const text = typeof args === 'string' ? args : JSON.stringify(args);
+    const result = shield.scanInput(text);
+
+    if (result.threats && result.threats.length > 0) {
+      if (onThreat) {
+        try {
+          onThreat({
+            phase: 'before_tool_call',
+            toolName: toolName || 'unknown',
+            threats: result.threats
+          });
+        } catch (e) {
+          console.error('[Agent Shield] onThreat callback error:', e.message);
+        }
+      }
+      if (result.blocked) {
+        throw new ShieldBlockError(
+          `Google ADK tool "${toolName || 'unknown'}" call blocked by Agent Shield`,
+          result.threats
+        );
+      }
+    }
+  }
+
+  /**
+   * Scans tool results after a tool call.
+   *
+   * @param {string} toolName - Name of the tool that was called.
+   * @param {*} result - Tool execution result.
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  function afterToolCall(toolName, toolResult) {
+    if (toolResult == null) return;
+
+    const text = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
+    const result = shield.scanOutput(text);
+
+    if (result.threats && result.threats.length > 0) {
+      if (onThreat) {
+        try {
+          onThreat({
+            phase: 'after_tool_call',
+            toolName: toolName || 'unknown',
+            threats: result.threats
+          });
+        } catch (e) {
+          console.error('[Agent Shield] onThreat callback error:', e.message);
+        }
+      }
+      if (result.blocked) {
+        throw new ShieldBlockError(
+          `Google ADK tool "${toolName || 'unknown'}" result blocked by Agent Shield`,
+          result.threats
+        );
+      }
+    }
+  }
+
+  /**
+   * Scans a prompt before generation.
+   *
+   * @param {string|*} prompt - The prompt to scan.
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  function beforeGenerate(prompt) {
+    if (prompt == null) return;
+
+    const text = typeof prompt === 'string' ? prompt : JSON.stringify(prompt);
+    const result = shield.scanInput(text);
+
+    if (result.threats && result.threats.length > 0) {
+      if (onThreat) {
+        try {
+          onThreat({
+            phase: 'before_generate',
+            threats: result.threats
+          });
+        } catch (e) {
+          console.error('[Agent Shield] onThreat callback error:', e.message);
+        }
+      }
+      if (result.blocked) {
+        throw new ShieldBlockError('Google ADK generation blocked by Agent Shield', result.threats);
+      }
+    }
+  }
+
+  return { beforeToolCall, afterToolCall, beforeGenerate, shield };
+}
+
+// =========================================================================
+// Microsoft Agent Framework Integration
+// =========================================================================
+
+/**
+ * Creates Agent Shield middleware for the Microsoft Agent Framework pipeline.
+ *
+ * The MS Agent Framework uses a middleware pattern where each middleware
+ * receives a context and a next() function. This wrapper scans context.input
+ * before calling next(), then scans context.output after next() returns.
+ *
+ * Usage:
+ *   const { shieldMSAgentFramework } = require('agentshield-sdk/src/integrations-frameworks');
+ *   const { agentMiddleware } = shieldMSAgentFramework({ blockOnThreat: true });
+ *
+ *   // Register in the MS Agent Framework pipeline:
+ *   agent.use(agentMiddleware);
+ *
+ * @param {object} [options]
+ * @param {string} [options.sensitivity='high'] - Detection sensitivity level.
+ * @param {boolean} [options.blockOnThreat=true] - Whether to throw on threat detection.
+ * @param {string} [options.blockThreshold='high'] - Minimum severity that triggers a block.
+ * @param {function} [options.onThreat] - Callback when a threat is detected.
+ * @returns {{ agentMiddleware: function, shield: AgentShield }}
+ */
+function shieldMSAgentFramework(options = {}) {
+  const shield = new AgentShield({
+    sensitivity: options.sensitivity || 'high',
+    blockOnThreat: options.blockOnThreat !== false,
+    blockThreshold: options.blockThreshold || 'high'
+  });
+  const onThreat = options.onThreat || null;
+
+  /**
+   * Middleware function for the MS Agent Framework pipeline.
+   * Scans context.input before next() and context.output after next().
+   *
+   * @param {object} context - Pipeline context with input/output properties.
+   * @param {function} next - Next middleware in the pipeline.
+   * @throws {ShieldBlockError} If a threat is detected and blocking is enabled.
+   */
+  async function agentMiddleware(context, next) {
+    // Scan input before passing to next middleware
+    if (context && context.input != null) {
+      const inputText = typeof context.input === 'string'
+        ? context.input
+        : JSON.stringify(context.input);
+
+      const inputResult = shield.scanInput(inputText);
+
+      if (inputResult.threats && inputResult.threats.length > 0) {
+        if (onThreat) {
+          try {
+            onThreat({
+              phase: 'input',
+              threats: inputResult.threats,
+              text: inputText
+            });
+          } catch (e) {
+            console.error('[Agent Shield] onThreat callback error:', e.message);
+          }
+        }
+        if (inputResult.blocked) {
+          throw new ShieldBlockError(
+            'MS Agent Framework input blocked by Agent Shield',
+            inputResult.threats
+          );
+        }
+      }
+    }
+
+    // Call next middleware in the pipeline
+    await next();
+
+    // Scan output after pipeline execution
+    if (context && context.output != null) {
+      const outputText = typeof context.output === 'string'
+        ? context.output
+        : JSON.stringify(context.output);
+
+      const outputResult = shield.scanOutput(outputText);
+
+      if (outputResult.threats && outputResult.threats.length > 0) {
+        if (onThreat) {
+          try {
+            onThreat({
+              phase: 'output',
+              threats: outputResult.threats,
+              text: outputText
+            });
+          } catch (e) {
+            console.error('[Agent Shield] onThreat callback error:', e.message);
+          }
+        }
+        if (outputResult.blocked) {
+          throw new ShieldBlockError(
+            'MS Agent Framework output blocked by Agent Shield',
+            outputResult.threats
+          );
+        }
+      }
+    }
+  }
+
+  return { agentMiddleware, shield };
+}
+
+// =========================================================================
+// Google ADK JavaScript (adk-js) Integration
+// =========================================================================
+
+/**
+ * Creates Agent Shield middleware for the Google ADK JavaScript/TypeScript SDK.
+ *
+ * Google ADK for JS (GA April 2026) uses a callback-based agent lifecycle.
+ * This wrapper returns a plugin object compatible with ADK-JS's plugin API
+ * that scans tool inputs, tool outputs, and generated content.
+ *
+ * Usage:
+ *   const { shieldGoogleADKJS } = require('agentshield-sdk/src/integrations-frameworks');
+ *   const plugin = shieldGoogleADKJS({ blockOnThreat: true });
+ *
+ *   // Register with ADK-JS agent:
+ *   const agent = new Agent({ plugins: [plugin] });
+ *
+ * @param {object} [options]
+ * @param {string} [options.sensitivity='high'] - Detection sensitivity level.
+ * @param {boolean} [options.blockOnThreat=true] - Whether to throw on threat detection.
+ * @param {string} [options.blockThreshold='high'] - Minimum severity that triggers a block.
+ * @param {function} [options.onThreat] - Callback when a threat is detected.
+ * @returns {{ name: string, beforeToolCall: function, afterToolCall: function, beforeModelCall: function, afterModelCall: function, shield: AgentShield }}
+ */
+function shieldGoogleADKJS(options = {}) {
+  const shield = new AgentShield({
+    sensitivity: options.sensitivity || 'high',
+    blockOnThreat: options.blockOnThreat !== false,
+    blockThreshold: options.blockThreshold || 'high'
+  });
+  const onThreat = options.onThreat || null;
+
+  function _scan(text, phase, meta) {
+    if (!text) return;
+    const result = shield.scanInput(text);
+    if (result.threats && result.threats.length > 0) {
+      if (onThreat) {
+        try { onThreat({ phase, ...meta, threats: result.threats }); }
+        catch (e) { console.error('[Agent Shield] onThreat callback error:', e.message); }
+      }
+      if (result.blocked) {
+        throw new ShieldBlockError(`Google ADK-JS ${phase} blocked by Agent Shield`, result.threats);
+      }
+    }
+  }
+
+  return {
+    name: 'AgentShieldPlugin',
+
+    beforeToolCall(context) {
+      const text = context.args != null
+        ? (typeof context.args === 'string' ? context.args : JSON.stringify(context.args))
+        : null;
+      _scan(text, 'before_tool_call', { toolName: context.toolName || 'unknown' });
+    },
+
+    afterToolCall(context) {
+      const text = context.result != null
+        ? (typeof context.result === 'string' ? context.result : JSON.stringify(context.result))
+        : null;
+      _scan(text, 'after_tool_call', { toolName: context.toolName || 'unknown' });
+    },
+
+    beforeModelCall(context) {
+      const text = context.prompt || context.input;
+      if (text) _scan(typeof text === 'string' ? text : JSON.stringify(text), 'before_model_call', {});
+    },
+
+    afterModelCall(context) {
+      const text = context.response || context.output;
+      if (!text) return;
+      const outputText = typeof text === 'string' ? text : JSON.stringify(text);
+      const result = shield.scanOutput(outputText);
+      if (result.threats && result.threats.length > 0) {
+        if (onThreat) {
+          try { onThreat({ phase: 'after_model_call', threats: result.threats }); }
+          catch (e) { console.error('[Agent Shield] onThreat callback error:', e.message); }
+        }
+        if (result.blocked) {
+          throw new ShieldBlockError('Google ADK-JS model output blocked by Agent Shield', result.threats);
+        }
+      }
+    },
+
+    shield
+  };
+}
+
+module.exports = {
+  shieldCrewAI,
+  shieldGoogleADK,
+  shieldGoogleADKJS,
+  shieldMSAgentFramework
+};

package/src/integrations.js

@@ -493,6 +493,210 @@ function shieldFetch(fetchFn, options = {}) {
   };
 }
 
+// =========================================================================
+// OpenAI Agents SDK (@openai/agents) — April 2026 release
+// =========================================================================
+
+/**
+ * Creates guardrails for the OpenAI Agents SDK (@openai/agents).
+ *
+ * The OpenAI Agents SDK (Python and TypeScript, April 2026 update) uses a
+ * Guardrail primitive that validates inputs and outputs. Agent Shield plugs
+ * in natively as both an input guardrail (scanning user messages) and an
+ * output guardrail (scanning agent responses).
+ *
+ * Compatible with:
+ *   - @openai/agents (TypeScript/JavaScript)
+ *   - openai-agents (Python — use the Python SDK's equivalent)
+ *
+ * Usage:
+ *   const { Agent, run } = require('@openai/agents');
+ *   const { shieldOpenAIAgent } = require('agentshield-sdk');
+ *
+ *   const { inputGuardrail, outputGuardrail } = shieldOpenAIAgent({
+ *     blockOnThreat: true,
+ *     sensitivity: 'high'
+ *   });
+ *
+ *   const agent = new Agent({
+ *     name: 'Assistant',
+ *     instructions: 'You are a helpful assistant',
+ *     inputGuardrails: [inputGuardrail],
+ *     outputGuardrails: [outputGuardrail]
+ *   });
+ *
+ *   const result = await run(agent, userInput);
+ *
+ * @param {object} [options]
+ * @param {string} [options.sensitivity='high'] - Detection sensitivity.
+ * @param {boolean} [options.blockOnThreat=true] - Trip guardrail tripwire on threats.
+ * @param {string} [options.blockThreshold='high'] - Minimum severity that blocks.
+ * @param {boolean} [options.pii=true] - Redact PII from inputs before handing to the agent.
+ * @param {boolean} [options.scanToolCalls=true] - Scan arguments to tool calls.
+ * @param {function} [options.onThreat] - Callback when threat detected.
+ * @returns {{ inputGuardrail: object, outputGuardrail: object, toolGuardrail: object, shield: AgentShield }}
+ */
+function shieldOpenAIAgent(options = {}) {
+  const shield = new AgentShield({
+    sensitivity: options.sensitivity || 'high',
+    blockOnThreat: options.blockOnThreat !== false,
+    blockThreshold: options.blockThreshold || 'high',
+    onThreat: options.onThreat
+  });
+
+  const piiRedactor = options.pii !== false ? new PIIRedactor() : null;
+
+  /**
+   * Input guardrail — runs on every user message before the agent sees it.
+   * Returns the shape expected by @openai/agents: { outputInfo, tripwireTriggered }.
+   */
+  const inputGuardrail = {
+    name: 'Agent Shield — Input',
+    execute: async (ctx) => {
+      // @openai/agents passes { input, context, agent }. Input may be a string
+      // or an array of message items. We scan every user-role text item.
+      const input = ctx.input || ctx.message || ctx;
+      const texts = normalizeAgentInput(input);
+
+      let allThreats = [];
+      let maxSeverity = null;
+
+      for (const text of texts) {
+        const result = shield.scanInput(text);
+        if (result.threats && result.threats.length > 0) {
+          allThreats = allThreats.concat(result.threats);
+          for (const t of result.threats) {
+            if (!maxSeverity || SEVERITY_RANK[t.severity] < SEVERITY_RANK[maxSeverity]) {
+              maxSeverity = t.severity;
+            }
+          }
+        }
+      }
+
+      const tripwireTriggered = shouldBlock(maxSeverity, options.blockThreshold || 'high');
+
+      return {
+        outputInfo: {
+          threats: allThreats,
+          maxSeverity,
+          scannedBy: 'agentshield-sdk',
+          piiRedacted: piiRedactor ? true : false
+        },
+        tripwireTriggered
+      };
+    }
+  };
+
+  /**
+   * Output guardrail — runs on agent responses before they reach the user.
+   * Catches prompt leaks, PII in output, canary tokens, etc.
+   */
+  const outputGuardrail = {
+    name: 'Agent Shield — Output',
+    execute: async (ctx) => {
+      const output = ctx.agentOutput || ctx.output || ctx.finalOutput || ctx;
+      const text = typeof output === 'string' ? output : JSON.stringify(output);
+
+      const result = shield.scanOutput(text);
+      const threats = result.threats || [];
+      const maxSeverity = threats.reduce((acc, t) => {
+        if (!acc || SEVERITY_RANK[t.severity] < SEVERITY_RANK[acc]) return t.severity;
+        return acc;
+      }, null);
+
+      return {
+        outputInfo: {
+          threats,
+          maxSeverity,
+          scannedBy: 'agentshield-sdk'
+        },
+        tripwireTriggered: shouldBlock(maxSeverity, options.blockThreshold || 'high')
+      };
+    }
+  };
+
+  /**
+   * Tool guardrail — runs before tool execution. Scans tool arguments for
+   * injection, path traversal, SSRF targets, and other tool-abuse patterns.
+   */
+  const toolGuardrail = {
+    name: 'Agent Shield — Tool',
+    execute: async (ctx) => {
+      const toolName = ctx.toolName || ctx.tool?.name || 'unknown';
+      const args = ctx.args || ctx.arguments || {};
+      const argsText = typeof args === 'string' ? args : JSON.stringify(args);
+
+      const result = shield.scanToolCall(toolName, typeof args === 'object' ? args : { input: args });
+      const threats = result.threats || [];
+      const maxSeverity = threats.reduce((acc, t) => {
+        if (!acc || SEVERITY_RANK[t.severity] < SEVERITY_RANK[acc]) return t.severity;
+        return acc;
+      }, null);
+
+      return {
+        outputInfo: {
+          threats,
+          toolName,
+          maxSeverity,
+          scannedBy: 'agentshield-sdk'
+        },
+        tripwireTriggered: shouldBlock(maxSeverity, options.blockThreshold || 'high')
+      };
+    }
+  };
+
+  return { inputGuardrail, outputGuardrail, toolGuardrail, shield };
+}
+
+/** Severity rank for block-threshold comparisons (lower number = higher severity). */
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/** Returns true if maxSeverity meets or exceeds the configured threshold. */
+function shouldBlock(maxSeverity, threshold) {
+  if (!maxSeverity) return false;
+  return SEVERITY_RANK[maxSeverity] <= SEVERITY_RANK[threshold];
+}
+
+/**
+ * Normalizes the OpenAI Agents SDK input shape into an array of user-role text strings.
+ * Handles: string, array of message items, message with content parts, etc.
+ */
+function normalizeAgentInput(input) {
+  if (typeof input === 'string') return [input];
+  if (!input) return [];
+
+  // Array of messages
+  if (Array.isArray(input)) {
+    const texts = [];
+    for (const item of input) {
+      if (typeof item === 'string') texts.push(item);
+      else if (item?.role === 'user' || item?.role === 'system') {
+        if (typeof item.content === 'string') texts.push(item.content);
+        else if (Array.isArray(item.content)) {
+          for (const part of item.content) {
+            if (typeof part === 'string') texts.push(part);
+            else if (part?.type === 'text' && part.text) texts.push(part.text);
+            else if (part?.text) texts.push(part.text);
+          }
+        }
+      }
+    }
+    return texts;
+  }
+
+  // Single message object
+  if (input.content) {
+    if (typeof input.content === 'string') return [input.content];
+    if (Array.isArray(input.content)) {
+      return input.content
+        .map(p => typeof p === 'string' ? p : (p?.text || ''))
+        .filter(Boolean);
+    }
+  }
+
+  return [];
+}
+
 // =========================================================================
 // Shared Error Class
 // =========================================================================
@@ -516,6 +720,9 @@ module.exports = {
   // OpenAI
   shieldOpenAIClient,
 
+  // OpenAI Agents SDK (@openai/agents, April 2026)
+  shieldOpenAIAgent,
+
   // Vercel AI
   shieldVercelAI,