mcp-rubber-duck 1.8.0 → 1.9.0

package/src/providers/duck-provider-enhanced.ts

@@ -4,6 +4,8 @@ import { FunctionBridge } from '../services/function-bridge.js';
 import { ConversationMessage } from '../config/types.js';
 import { logger } from '../utils/logger.js';
 import { SafeLogger } from '../utils/safe-logger.js';
+import { GuardrailsService } from '../guardrails/service.js';
+import { GuardrailBlockError } from '../guardrails/errors.js';
 
 export interface EnhancedChatResponse extends ChatResponse {
   pendingApprovals?: {
@@ -22,15 +24,43 @@ export class EnhancedDuckProvider extends DuckProvider {
     nickname: string,
     options: ProviderOptions,
     functionBridge: FunctionBridge,
-    mcpEnabled: boolean = true
+    mcpEnabled: boolean = true,
+    guardrailsService?: GuardrailsService
   ) {
-    super(name, nickname, options);
+    super(name, nickname, options, guardrailsService);
     this.functionBridge = functionBridge;
     this.mcpEnabled = mcpEnabled;
   }
 
   async chat(options: ChatOptions): Promise<EnhancedChatResponse> {
     try {
+      const modelToUse = options.model || this.options.model;
+
+      // Create guardrail context if service is enabled
+      const guardrailContext = this.guardrailsService?.isEnabled()
+        ? this.guardrailsService.createContext({
+            provider: this.name,
+            model: modelToUse,
+            messages: options.messages,
+            prompt: options.messages[options.messages.length - 1]?.content,
+          })
+        : undefined;
+
+      // Execute pre_request guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        const preResult = await this.guardrailsService.execute('pre_request', guardrailContext);
+        if (preResult.action === 'block') {
+          throw new GuardrailBlockError(
+            preResult.blockedBy || 'unknown',
+            preResult.blockReason || 'Request blocked by guardrails'
+          );
+        }
+        // Update messages if modified by guardrails (e.g., PII redaction)
+        if (preResult.action === 'modify' && guardrailContext.messages.length > 0) {
+          options = { ...options, messages: guardrailContext.messages };
+        }
+      }
+
       // If MCP is enabled, add function definitions
       if (this.mcpEnabled) {
         const functions = await this.functionBridge.getFunctionDefinitions();
@@ -43,7 +73,6 @@ export class EnhancedDuckProvider extends DuckProvider {
 
       // Prepare messages for function calling
       const messages = this.prepareMessages(options.messages, options.systemPrompt);
-      const modelToUse = options.model || this.options.model;
 
       const baseParams: Partial<OpenAIChatParams> = {
         model: modelToUse,
@@ -75,17 +104,52 @@ export class EnhancedDuckProvider extends DuckProvider {
 
       // Check if the model wants to call functions
       if (choice.message?.tool_calls && choice.message.tool_calls.length > 0) {
-        return await this.handleToolCalls(
+        const toolResult = await this.handleToolCalls(
           choice.message.tool_calls,
           messages as OpenAIMessage[],
           baseParams,
-          modelToUse
+          modelToUse,
+          guardrailContext
         );
+
+        // Execute post_response guardrails on final result
+        if (guardrailContext && this.guardrailsService?.isEnabled()) {
+          guardrailContext.response = toolResult.content;
+          const postResult = await this.guardrailsService.execute('post_response', guardrailContext);
+          if (postResult.action === 'block') {
+            throw new GuardrailBlockError(
+              postResult.blockedBy || 'unknown',
+              postResult.blockReason || 'Response blocked by guardrails'
+            );
+          }
+          if (postResult.action === 'modify' && guardrailContext.response) {
+            toolResult.content = guardrailContext.response;
+          }
+        }
+
+        return toolResult;
+      }
+
+      let content = choice.message?.content || '';
+
+      // Execute post_response guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        guardrailContext.response = content;
+        const postResult = await this.guardrailsService.execute('post_response', guardrailContext);
+        if (postResult.action === 'block') {
+          throw new GuardrailBlockError(
+            postResult.blockedBy || 'unknown',
+            postResult.blockReason || 'Response blocked by guardrails'
+          );
+        }
+        if (postResult.action === 'modify' && guardrailContext.response) {
+          content = guardrailContext.response;
+        }
       }
 
       // No tool calls, return regular response
       return {
-        content: choice.message?.content || '',
+        content,
         usage: response.usage ? {
           promptTokens: response.usage.prompt_tokens,
           completionTokens: response.usage.completion_tokens,
@@ -96,6 +160,10 @@ export class EnhancedDuckProvider extends DuckProvider {
       };
 
     } catch (error: unknown) {
+      // Re-throw GuardrailBlockError as-is
+      if (error instanceof GuardrailBlockError) {
+        throw error;
+      }
       logger.error(`Enhanced provider ${this.name} chat error:`, error);
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(`Duck ${this.nickname} couldn't respond: ${errorMessage}`);
@@ -106,7 +174,8 @@ export class EnhancedDuckProvider extends DuckProvider {
     toolCalls: OpenAIToolCall[],
     messages: OpenAIMessage[],
     baseParams: Partial<OpenAIChatParams>,
-    modelToUse: string
+    modelToUse: string,
+    _guardrailContext?: import('../guardrails/types.js').GuardrailContext
   ): Promise<EnhancedChatResponse> {
     const pendingApprovals: { id: string; message: string }[] = [];
     const toolMessages: OpenAIMessage[] = [];

package/src/providers/enhanced-manager.ts

@@ -3,6 +3,7 @@ import { ProviderManager } from './manager.js';
 import { ConfigManager } from '../config/config.js';
 import { FunctionBridge } from '../services/function-bridge.js';
 import { UsageService } from '../services/usage.js';
+import { GuardrailsService } from '../guardrails/service.js';
 import { DuckResponse } from '../config/types.js';
 import { ChatOptions, MCPResult } from './types.js';
 import { logger } from '../utils/logger.js';
@@ -12,8 +13,8 @@ export class EnhancedProviderManager extends ProviderManager {
   private functionBridge?: FunctionBridge;
   private mcpEnabled: boolean = false;
 
-  constructor(configManager: ConfigManager, functionBridge?: FunctionBridge, usageService?: UsageService) {
-    super(configManager, usageService);
+  constructor(configManager: ConfigManager, functionBridge?: FunctionBridge, usageService?: UsageService, guardrailsService?: GuardrailsService) {
+    super(configManager, usageService, guardrailsService);
     this.functionBridge = functionBridge;
     this.mcpEnabled = !!functionBridge &&
       (configManager.getConfig().mcp_bridge?.enabled || false);
@@ -49,7 +50,8 @@ export class EnhancedProviderManager extends ProviderManager {
             systemPrompt: providerConfig.system_prompt,
           },
           this.functionBridge,
-          this.mcpEnabled
+          this.mcpEnabled,
+          this.guardrailsService
         );
 
         this.enhancedProviders.set(name, enhancedProvider);

package/src/providers/manager.ts

@@ -3,6 +3,7 @@ import { ConfigManager } from '../config/config.js';
 import { ProviderHealth, DuckResponse } from '../config/types.js';
 import { ChatOptions, ModelInfo } from './types.js';
 import { UsageService } from '../services/usage.js';
+import { GuardrailsService } from '../guardrails/service.js';
 import { logger } from '../utils/logger.js';
 import { getRandomDuckMessage } from '../utils/ascii-art.js';
 
@@ -11,11 +12,13 @@ export class ProviderManager {
   private healthStatus: Map<string, ProviderHealth> = new Map();
   protected configManager: ConfigManager;
   protected usageService?: UsageService;
+  protected guardrailsService?: GuardrailsService;
   private defaultProvider?: string;
 
-  constructor(configManager: ConfigManager, usageService?: UsageService) {
+  constructor(configManager: ConfigManager, usageService?: UsageService, guardrailsService?: GuardrailsService) {
     this.configManager = configManager;
     this.usageService = usageService;
+    this.guardrailsService = guardrailsService;
     this.initializeProviders();
   }
 
@@ -34,7 +37,7 @@ export class ProviderManager {
           timeout: providerConfig.timeout,
           maxRetries: providerConfig.max_retries,
           systemPrompt: providerConfig.system_prompt,
-        });
+        }, this.guardrailsService);
 
         this.providers.set(name, provider);
         logger.info(`Initialized provider: ${name} (${providerConfig.nickname})`);
@@ -44,7 +47,7 @@ export class ProviderManager {
     }
 
     this.defaultProvider = config.default_provider;
-    
+
     if (this.providers.size === 0) {
       throw new Error('No providers could be initialized');
     }

package/src/providers/provider.ts

@@ -2,18 +2,22 @@ import OpenAI from 'openai';
 import { ChatOptions, ChatResponse, ProviderOptions, ModelInfo, OpenAIChatParams, OpenAIChatResponse, OpenAIMessage } from './types.js';
 import { ConversationMessage } from '../config/types.js';
 import { logger } from '../utils/logger.js';
+import { GuardrailsService } from '../guardrails/service.js';
+import { GuardrailBlockError } from '../guardrails/errors.js';
 
 export class DuckProvider {
   protected client: OpenAI;
   protected options: ProviderOptions;
+  protected guardrailsService?: GuardrailsService;
   public name: string;
   public nickname: string;
 
-  constructor(name: string, nickname: string, options: ProviderOptions) {
+  constructor(name: string, nickname: string, options: ProviderOptions, guardrailsService?: GuardrailsService) {
     this.name = name;
     this.nickname = nickname;
     this.options = options;
-    
+    this.guardrailsService = guardrailsService;
+
     this.client = new OpenAI({
       apiKey: options.apiKey || 'not-needed',
       baseURL: options.baseURL,
@@ -34,9 +38,35 @@ export class DuckProvider {
 
   async chat(options: ChatOptions): Promise<ChatResponse> {
     try {
-      const messages = this.prepareMessages(options.messages, options.systemPrompt);
       const modelToUse = options.model || this.options.model;
-      
+
+      // Create guardrail context if service is enabled
+      const guardrailContext = this.guardrailsService?.isEnabled()
+        ? this.guardrailsService.createContext({
+            provider: this.name,
+            model: modelToUse,
+            messages: options.messages,
+            prompt: options.messages[options.messages.length - 1]?.content,
+          })
+        : undefined;
+
+      // Execute pre_request guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        const preResult = await this.guardrailsService.execute('pre_request', guardrailContext);
+        if (preResult.action === 'block') {
+          throw new GuardrailBlockError(
+            preResult.blockedBy || 'unknown',
+            preResult.blockReason || 'Request blocked by guardrails'
+          );
+        }
+        // Update messages if modified by guardrails (e.g., PII redaction)
+        if (preResult.action === 'modify' && guardrailContext.messages.length > 0) {
+          options = { ...options, messages: guardrailContext.messages };
+        }
+      }
+
+      const messages = this.prepareMessages(options.messages, options.systemPrompt);
+
       const baseParams: Partial<OpenAIChatParams> = {
         model: modelToUse,
         messages: messages as OpenAIMessage[],
@@ -50,9 +80,26 @@ export class DuckProvider {
 
       const response = await this.createChatCompletion(baseParams);
       const choice = response.choices[0];
-      
+      let content = choice.message?.content || '';
+
+      // Execute post_response guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        guardrailContext.response = content;
+        const postResult = await this.guardrailsService.execute('post_response', guardrailContext);
+        if (postResult.action === 'block') {
+          throw new GuardrailBlockError(
+            postResult.blockedBy || 'unknown',
+            postResult.blockReason || 'Response blocked by guardrails'
+          );
+        }
+        // Use potentially modified response (e.g., PII restoration)
+        if (postResult.action === 'modify' && guardrailContext.response) {
+          content = guardrailContext.response;
+        }
+      }
+
       return {
-        content: choice.message?.content || '',
+        content,
         usage: response.usage ? {
           promptTokens: response.usage.prompt_tokens,
           completionTokens: response.usage.completion_tokens,
@@ -62,6 +109,10 @@ export class DuckProvider {
         finishReason: choice.finish_reason || undefined,
       };
     } catch (error: unknown) {
+      // Re-throw GuardrailBlockError as-is
+      if (error instanceof GuardrailBlockError) {
+        throw error;
+      }
       logger.error(`Provider ${this.name} chat error:`, error);
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(`Duck ${this.nickname} couldn't respond: ${errorMessage}`);

package/src/server.ts

@@ -20,6 +20,7 @@ import { UsageService } from './services/usage.js';
 import { DuckResponse } from './config/types.js';
 import { ApprovalService } from './services/approval.js';
 import { FunctionBridge } from './services/function-bridge.js';
+import { GuardrailsService } from './guardrails/service.js';
 import { logger } from './utils/logger.js';
 import { duckArt, getRandomDuckMessage } from './utils/ascii-art.js';
 
@@ -52,6 +53,7 @@ export class RubberDuckServer {
   private configManager: ConfigManager;
   private pricingService: PricingService;
   private usageService: UsageService;
+  private guardrailsService?: GuardrailsService;
   private providerManager: ProviderManager;
   private enhancedProviderManager?: EnhancedProviderManager;
   private conversationManager: ConversationManager;
@@ -86,8 +88,13 @@ export class RubberDuckServer {
     this.pricingService = new PricingService(config.pricing);
     this.usageService = new UsageService(this.pricingService);
 
-    // Initialize provider manager with usage tracking
-    this.providerManager = new ProviderManager(this.configManager, this.usageService);
+    // Initialize guardrails service if configured
+    if (config.guardrails?.enabled) {
+      this.guardrailsService = new GuardrailsService(config.guardrails);
+    }
+
+    // Initialize provider manager with usage tracking and guardrails
+    this.providerManager = new ProviderManager(this.configManager, this.usageService, this.guardrailsService);
     this.conversationManager = new ConversationManager();
     this.cache = new ResponseCache(config.cache_ttl);
     this.healthMonitor = new HealthMonitor(this.providerManager);
@@ -116,20 +123,22 @@ export class RubberDuckServer {
       // Initialize approval service
       this.approvalService = new ApprovalService(mcpConfig.approval_timeout);
 
-      // Initialize function bridge
+      // Initialize function bridge with guardrails
       this.functionBridge = new FunctionBridge(
         this.mcpClientManager,
         this.approvalService,
         mcpConfig.trusted_tools,
         mcpConfig.approval_mode,
-        mcpConfig.trusted_tools_by_server || {}
+        mcpConfig.trusted_tools_by_server || {},
+        this.guardrailsService
       );
 
-      // Initialize enhanced provider manager with usage tracking
+      // Initialize enhanced provider manager with usage tracking and guardrails
       this.enhancedProviderManager = new EnhancedProviderManager(
         this.configManager,
         this.functionBridge,
-        this.usageService
+        this.usageService,
+        this.guardrailsService
       );
 
       this.mcpEnabled = true;
@@ -824,6 +833,18 @@ export class RubberDuckServer {
       console.log('\n' + getRandomDuckMessage('startup'));
     }
 
+    // Initialize guardrails service if configured
+    if (this.guardrailsService) {
+      try {
+        await this.guardrailsService.initialize();
+        logger.info('Guardrails service initialized successfully');
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error('Failed to initialize guardrails:', errorMessage);
+        logger.warn('Guardrails functionality may not be available');
+      }
+    }
+
     // Initialize MCP connections if enabled
     if (this.mcpEnabled && this.mcpClientManager) {
       try {
@@ -853,6 +874,11 @@ export class RubberDuckServer {
     // Cleanup usage service (flush pending writes)
     this.usageService.shutdown();
 
+    // Cleanup guardrails service
+    if (this.guardrailsService) {
+      await this.guardrailsService.shutdown();
+    }
+
     // Cleanup MCP resources
     if (this.approvalService) {
       this.approvalService.shutdown();

package/src/services/function-bridge.ts

@@ -2,6 +2,9 @@ import { MCPClientManager, MCPTool } from './mcp-client-manager.js';
 import { ApprovalService } from './approval.js';
 import { logger } from '../utils/logger.js';
 import Ajv, { ValidateFunction } from 'ajv';
+import { GuardrailsService } from '../guardrails/service.js';
+import { GuardrailContext } from '../guardrails/types.js';
+import { GuardrailBlockError } from '../guardrails/errors.js';
 
 export interface FunctionDefinition {
   name: string;
@@ -26,13 +29,15 @@ export class FunctionBridge {
   private ajv: unknown;
   private toolSchemas: Map<string, Record<string, unknown>> = new Map();
   private approvalMode: 'always' | 'trusted' | 'never';
+  private guardrailsService?: GuardrailsService;
 
   constructor(
     mcpManager: MCPClientManager,
     approvalService: ApprovalService,
     trustedTools: string[] = [],
     approvalMode: 'always' | 'trusted' | 'never' = 'always',
-    trustedToolsByServer: Record<string, string[]> = {}
+    trustedToolsByServer: Record<string, string[]> = {},
+    guardrailsService?: GuardrailsService
   ) {
     this.mcpManager = mcpManager;
     this.approvalService = approvalService;
@@ -40,7 +45,8 @@ export class FunctionBridge {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
     this.ajv = new (Ajv as unknown as new (options: unknown) => unknown)({ allErrors: true, removeAdditional: 'all' });
     this.approvalMode = approvalMode;
-    
+    this.guardrailsService = guardrailsService;
+
     // Initialize per-server trusted tools
     Object.entries(trustedToolsByServer).forEach(([serverName, tools]) => {
       this.trustedToolsByServer.set(serverName, new Set(tools));
@@ -236,16 +242,61 @@ export class FunctionBridge {
         }
       }
 
+      // Create guardrail context if service is enabled
+      let guardrailContext: GuardrailContext | undefined;
+      if (this.guardrailsService?.isEnabled()) {
+        guardrailContext = this.guardrailsService.createContext({
+          toolName: `${mcpServer}:${mcpTool}`,
+          toolArgs: cleanArgs,
+        });
+
+        // Execute pre_tool_input guardrails
+        const preResult = await this.guardrailsService.execute('pre_tool_input', guardrailContext);
+        if (preResult.action === 'block') {
+          throw new GuardrailBlockError(
+            preResult.blockedBy || 'unknown',
+            preResult.blockReason || 'Tool input blocked by guardrails'
+          );
+        }
+        // Use potentially modified args (e.g., PII redaction)
+        if (preResult.action === 'modify' && guardrailContext.toolArgs) {
+          Object.assign(cleanArgs, guardrailContext.toolArgs);
+        }
+      }
+
       // Execute the MCP tool
       logger.info(`Executing MCP tool ${mcpServer}:${mcpTool} for ${duckName}`);
       const result = await this.mcpManager.callTool(mcpServer, mcpTool, cleanArgs);
 
+      // Execute post_tool_output guardrails
+      if (guardrailContext && this.guardrailsService?.isEnabled()) {
+        guardrailContext.toolResult = result;
+        const postResult = await this.guardrailsService.execute('post_tool_output', guardrailContext);
+        if (postResult.action === 'block') {
+          throw new GuardrailBlockError(
+            postResult.blockedBy || 'unknown',
+            postResult.blockReason || 'Tool output blocked by guardrails'
+          );
+        }
+        // Return potentially modified result
+        if (postResult.action === 'modify') {
+          return {
+            success: true,
+            data: guardrailContext.toolResult,
+          };
+        }
+      }
+
       return {
         success: true,
         data: result,
       };
 
     } catch (error: unknown) {
+      // Re-throw GuardrailBlockError as-is
+      if (error instanceof GuardrailBlockError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       logger.error(`Function call failed for ${functionName}:`, errorMessage);
       return {