mcp-rubber-duck 1.7.0 → 1.9.0

package/src/guardrails/service.ts

@@ -0,0 +1,209 @@
+import { GuardrailPlugin, GuardrailPhase, GuardrailContext, GuardrailResult, CreateContextOptions } from './types.js';
+import { createGuardrailContext } from './context.js';
+import { GuardrailsConfig, GuardrailsPluginsConfig } from '../config/types.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Main service that orchestrates guardrail plugins
+ */
+export class GuardrailsService {
+  private plugins: GuardrailPlugin[] = [];
+  private config: GuardrailsConfig;
+  private enabled: boolean = false;
+
+  constructor(config?: Partial<GuardrailsConfig>) {
+    this.config = {
+      enabled: config?.enabled ?? false,
+      log_violations: config?.log_violations ?? true,
+      log_modifications: config?.log_modifications ?? false,
+      fail_open: config?.fail_open ?? false,
+      plugins: config?.plugins,
+    };
+    // Start disabled - will be enabled after successful initialization with plugins
+    this.enabled = false;
+  }
+
+  /**
+   * Initialize the service and all configured plugins
+   */
+  async initialize(): Promise<void> {
+    if (!this.config.enabled) {
+      logger.info('Guardrails disabled in configuration');
+      return;
+    }
+
+    const pluginConfigs = this.config.plugins || {};
+
+    // Load plugins in order
+    await this.loadPluginsFromConfig(pluginConfigs);
+
+    // Sort by priority (lower = runs first)
+    this.plugins.sort((a, b) => a.priority - b.priority);
+
+    this.enabled = this.plugins.length > 0;
+    logger.info(`Guardrails initialized with ${this.plugins.length} plugins`);
+  }
+
+  private async loadPluginsFromConfig(pluginConfigs: Partial<GuardrailsPluginsConfig>): Promise<void> {
+    const pluginOrder: Array<[string, unknown]> = [
+      ['rate_limiter', pluginConfigs.rate_limiter],
+      ['token_limiter', pluginConfigs.token_limiter],
+      ['pii_redactor', pluginConfigs.pii_redactor],
+      ['pattern_blocker', pluginConfigs.pattern_blocker],
+    ];
+
+    for (const [pluginName, pluginConfig] of pluginOrder) {
+      if (!pluginConfig || !(pluginConfig as { enabled?: boolean }).enabled) {
+        continue;
+      }
+
+      try {
+        const plugin = await this.loadPlugin(pluginName);
+        await plugin.initialize(pluginConfig as Record<string, unknown>);
+        if ((pluginConfig as { priority?: number }).priority !== undefined) {
+          plugin.priority = (pluginConfig as { priority: number }).priority;
+        }
+        this.plugins.push(plugin);
+        logger.info(`Guardrail plugin '${pluginName}' initialized`);
+      } catch (error) {
+        logger.error(`Failed to initialize guardrail plugin '${pluginName}':`, error);
+      }
+    }
+  }
+
+  private async loadPlugin(name: string): Promise<GuardrailPlugin> {
+    // Dynamic plugin loading
+    switch (name) {
+      case 'rate_limiter': {
+        const { RateLimiterPlugin } = await import('./plugins/rate-limiter.js');
+        return new RateLimiterPlugin();
+      }
+      case 'token_limiter': {
+        const { TokenLimiterPlugin } = await import('./plugins/token-limiter.js');
+        return new TokenLimiterPlugin();
+      }
+      case 'pattern_blocker': {
+        const { PatternBlockerPlugin } = await import('./plugins/pattern-blocker.js');
+        return new PatternBlockerPlugin();
+      }
+      case 'pii_redactor': {
+        const { PIIRedactorPlugin } = await import('./plugins/pii-redactor/index.js');
+        return new PIIRedactorPlugin();
+      }
+      default:
+        throw new Error(`Unknown guardrail plugin: ${name}`);
+    }
+  }
+
+  /**
+   * Check if guardrails are enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Create a new context for guardrail execution
+   */
+  createContext(options: CreateContextOptions): GuardrailContext {
+    return createGuardrailContext(options);
+  }
+
+  /**
+   * Execute all relevant plugins for a given phase
+   */
+  async execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult> {
+    if (!this.enabled) {
+      return { action: 'allow', context };
+    }
+
+    const relevantPlugins = this.plugins.filter(
+      (p) => p.enabled && p.phases.includes(phase)
+    );
+
+    // Track logged items to avoid duplicates
+    let lastViolationCount = 0;
+    let lastModificationCount = 0;
+    let wasModified = false;
+
+    for (const plugin of relevantPlugins) {
+      try {
+        const result = await plugin.execute(phase, context);
+
+        // Log only NEW violations if configured
+        if (this.config.log_violations && context.violations.length > lastViolationCount) {
+          for (let i = lastViolationCount; i < context.violations.length; i++) {
+            const violation = context.violations[i];
+            logger.warn(`Guardrail violation: ${violation.pluginName} - ${violation.message}`, {
+              rule: violation.rule,
+              severity: violation.severity,
+              details: violation.details,
+            });
+          }
+          lastViolationCount = context.violations.length;
+        }
+
+        // Log only NEW modifications if configured
+        if (this.config.log_modifications && context.modifications.length > lastModificationCount) {
+          for (let i = lastModificationCount; i < context.modifications.length; i++) {
+            const mod = context.modifications[i];
+            logger.info(`Guardrail modification: ${mod.pluginName} - ${mod.reason}`, {
+              field: mod.field,
+            });
+          }
+          lastModificationCount = context.modifications.length;
+        }
+
+        if (result.action === 'block') {
+          logger.warn(`Request blocked by guardrail '${plugin.name}': ${result.blockReason}`);
+          return result;
+        }
+
+        // Track if any plugin modified the context
+        if (result.action === 'modify') {
+          wasModified = true;
+        }
+
+        // Update context for next plugin
+        context = result.context;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Guardrail plugin '${plugin.name}' error:`, error);
+
+        if (!this.config.fail_open) {
+          return {
+            action: 'block',
+            context,
+            blockedBy: plugin.name,
+            blockReason: `Plugin error: ${errorMessage}`,
+          };
+        }
+        // fail_open: continue to next plugin
+      }
+    }
+
+    return { action: wasModified ? 'modify' : 'allow', context };
+  }
+
+  /**
+   * Shutdown the service and all plugins
+   */
+  async shutdown(): Promise<void> {
+    for (const plugin of this.plugins) {
+      try {
+        await plugin.shutdown();
+      } catch (error) {
+        logger.error(`Error shutting down plugin '${plugin.name}':`, error);
+      }
+    }
+    this.plugins = [];
+    this.enabled = false;
+  }
+
+  /**
+   * Get list of loaded plugins
+   */
+  getPlugins(): GuardrailPlugin[] {
+    return [...this.plugins];
+  }
+}

package/src/guardrails/types.ts

@@ -0,0 +1,120 @@
+import { ConversationMessage } from '../config/types.js';
+
+/**
+ * Phases in the guardrail pipeline where plugins can intercept
+ */
+export type GuardrailPhase =
+  | 'pre_request' // Before LLM API call
+  | 'post_response' // After LLM response, before tool handling
+  | 'pre_tool_input' // Before MCP tool execution
+  | 'post_tool_output' // After MCP tool returns
+  | 'pre_cache'; // Before caching response
+
+/**
+ * Action to take after guardrail evaluation
+ */
+export type GuardrailAction = 'allow' | 'block' | 'modify';
+
+/**
+ * Severity levels for violations
+ */
+export type ViolationSeverity = 'info' | 'warning' | 'error' | 'critical';
+
+/**
+ * A violation detected by a guardrail plugin
+ */
+export interface GuardrailViolation {
+  pluginName: string;
+  phase: GuardrailPhase;
+  rule: string;
+  severity: ViolationSeverity;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * A modification made by a guardrail plugin
+ */
+export interface GuardrailModification {
+  pluginName: string;
+  phase: GuardrailPhase;
+  field: string;
+  originalValue?: unknown;
+  newValue?: unknown;
+  reason: string;
+}
+
+/**
+ * Context passed through the guardrail pipeline
+ */
+export interface GuardrailContext {
+  // Request metadata
+  requestId: string;
+  provider: string;
+  model: string;
+  timestamp: Date;
+
+  // Phase-specific data (mutable by plugins)
+  messages: ConversationMessage[];
+  prompt?: string;
+  response?: string;
+  toolName?: string;
+  toolArgs?: Record<string, unknown>;
+  toolResult?: unknown;
+
+  // Tracking data (persisted across phases)
+  metadata: Map<string, unknown>; // For plugins to store state
+  violations: GuardrailViolation[]; // Accumulated violations
+  modifications: GuardrailModification[]; // Tracking changes made
+}
+
+/**
+ * Result from a guardrail plugin execution
+ */
+export interface GuardrailResult {
+  action: GuardrailAction;
+  context: GuardrailContext;
+  blockedBy?: string; // Plugin name that blocked
+  blockReason?: string;
+}
+
+/**
+ * Base interface for guardrail plugins
+ */
+export interface GuardrailPlugin {
+  /** Unique plugin name */
+  name: string;
+
+  /** Whether the plugin is currently enabled */
+  enabled: boolean;
+
+  /** Execution priority (lower = runs first) */
+  priority: number;
+
+  /** Which phases this plugin handles */
+  phases: GuardrailPhase[];
+
+  /** Initialize the plugin with its configuration */
+  initialize(config: Record<string, unknown>): Promise<void>;
+
+  /** Execute the plugin for a specific phase */
+  execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult>;
+
+  /** Cleanup plugin resources */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Options for creating a guardrail context
+ */
+export interface CreateContextOptions {
+  requestId?: string;
+  provider?: string;
+  model?: string;
+  messages?: ConversationMessage[];
+  prompt?: string;
+  response?: string;
+  toolName?: string;
+  toolArgs?: Record<string, unknown>;
+  toolResult?: unknown;
+}

package/src/prompts/architecture.ts

@@ -0,0 +1,111 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt for structured architecture and design reviews.
+ */
+export const architecturePrompt: PromptDefinition = {
+  name: 'architecture',
+  description:
+    'Structured architecture or design review from multiple engineering perspectives. Each reviewer focuses on different cross-cutting concerns.',
+  arguments: [
+    {
+      name: 'design',
+      description: 'Description of the architecture, system design, or technical approach',
+      required: true,
+    },
+    {
+      name: 'workloads',
+      description: 'Key use cases, workloads, or scenarios the design must handle',
+      required: true,
+    },
+    {
+      name: 'priorities',
+      description:
+        'Non-functional priorities (e.g., "latency, cost, simplicity, observability")',
+      required: true,
+    },
+    {
+      name: 'uncertainties',
+      description: 'Areas where you feel most unsure or want extra scrutiny',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { design, workloads, priorities, uncertainties } = args;
+
+    if (!design) {
+      throw new Error('design argument is required');
+    }
+    if (!workloads) {
+      throw new Error('workloads argument is required');
+    }
+    if (!priorities) {
+      throw new Error('priorities argument is required');
+    }
+
+    let messageText = `Review this architecture from multiple engineering perspectives:
+
+**DESIGN:**
+${design}
+
+**KEY WORKLOADS/USE CASES:**
+${workloads}
+
+**PRIORITIES:**
+${priorities}
+`;
+
+    if (uncertainties) {
+      messageText += `
+**AREAS OF UNCERTAINTY (extra scrutiny needed):**
+${uncertainties}
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+Each reviewer should focus on a different cross-cutting concern:
+
+1. **Scalability & Performance**
+   - Can this handle the stated workloads?
+   - Where are the bottlenecks?
+   - How does it scale (vertically/horizontally)?
+
+2. **Reliability & Failure Modes**
+   - What happens when components fail?
+   - Are there single points of failure?
+   - How is state handled during failures?
+
+3. **Operational Complexity**
+   - How hard is this to deploy, monitor, and debug?
+   - What operational burden does this create?
+   - How observable is the system?
+
+4. **Developer Experience**
+   - How easy is this to understand and modify?
+   - What's the learning curve?
+   - How testable is this design?
+
+5. **Cost Efficiency**
+   - What are the cost drivers?
+   - Are there cheaper alternatives that meet requirements?
+   - How do costs scale with load?
+
+**For each concern:**
+- Identify specific issues or risks
+- Suggest improvements aligned with the stated priorities
+- Note trade-offs (improving one area may hurt another)
+
+Focus on actionable feedback, not generic advice.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/assumptions.ts

@@ -0,0 +1,80 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt to surface and challenge hidden assumptions in a plan or design.
+ */
+export const assumptionsPrompt: PromptDefinition = {
+  name: 'assumptions',
+  description:
+    'Surface and challenge hidden assumptions in a plan, design, or idea. Identifies implicit premises that could be risky if wrong.',
+  arguments: [
+    {
+      name: 'plan',
+      description: 'The plan, design, or idea to analyze for hidden assumptions',
+      required: true,
+    },
+    {
+      name: 'constraints',
+      description: 'Known hard constraints that are definitely true',
+      required: false,
+    },
+    {
+      name: 'concerns',
+      description: 'Areas where you feel uncertain or worried',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { plan, constraints, concerns } = args;
+
+    if (!plan) {
+      throw new Error('plan argument is required');
+    }
+
+    let messageText = `Please analyze the hidden assumptions in this plan:
+
+**PLAN/DESIGN/IDEA:**
+${plan}
+`;
+
+    if (constraints) {
+      messageText += `
+**KNOWN CONSTRAINTS (definitely true):**
+${constraints}
+`;
+    }
+
+    if (concerns) {
+      messageText += `
+**MY CONCERNS/UNCERTAINTIES:**
+${concerns}
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+Identify the implicit assumptions underlying this plan. For each assumption:
+
+1. **State it explicitly** - What is being assumed without being stated?
+2. **Criticality** (high/medium/low) - How important is this assumption to the plan's success?
+3. **Fragility** (high/medium/low) - How likely is this assumption to be wrong?
+4. **Validation** - How could we test or verify this assumption?
+
+Focus on assumptions that:
+- Are easy to overlook
+- Would cause significant problems if wrong
+- Others analyzing this might miss
+
+Each LLM should try to find assumptions the others might not catch.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/blindspots.ts

@@ -0,0 +1,79 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt to hunt for missing considerations, gaps, and overlooked risks.
+ */
+export const blindspotsPrompt: PromptDefinition = {
+  name: 'blindspots',
+  description:
+    'Hunt for missing considerations, overlooked risks, and gaps in a proposal. Acts as a panel of critical reviewers looking for what might be underweighted.',
+  arguments: [
+    {
+      name: 'proposal',
+      description: 'The plan, code, design, or proposal to review for blindspots',
+      required: true,
+    },
+    {
+      name: 'covered',
+      description: 'What you think you have already addressed or considered',
+      required: false,
+    },
+    {
+      name: 'risk_tolerance',
+      description: 'Your risk tolerance level: low, medium, or high',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { proposal, covered, risk_tolerance } = args;
+
+    if (!proposal) {
+      throw new Error('proposal argument is required');
+    }
+
+    let messageText = `Act as a panel of critical reviewers looking for blindspots.
+
+**PROPOSAL TO REVIEW:**
+${proposal}
+`;
+
+    if (covered) {
+      messageText += `
+**ALREADY CONSIDERED:**
+${covered}
+`;
+    }
+
+    if (risk_tolerance) {
+      messageText += `
+**RISK TOLERANCE:** ${risk_tolerance}
+`;
+    }
+
+    messageText += `
+**YOUR TASK:**
+Each reviewer should identify 2-3 potential blindspots:
+
+1. **Failure modes** - Ways this could fail that aren't being considered
+2. **Missing considerations** - Important factors that are overlooked
+3. **Edge cases** - Scenarios that might break assumptions
+4. **Dependencies** - External factors that could cause problems
+
+For each blindspot:
+- Be specific about WHAT the concern is
+- Explain WHY it's concerning (impact if it happens)
+- Suggest potential mitigations
+
+Look for things that are easy to miss because they seem "obvious" or fall outside the immediate scope. Different reviewers should explore different angles.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};

package/src/prompts/diverge-converge.ts

@@ -0,0 +1,92 @@
+import { PromptDefinition } from './types.js';
+
+/**
+ * Prompt for divergent exploration followed by convergence.
+ */
+export const divergeConvergePrompt: PromptDefinition = {
+  name: 'diverge_converge',
+  description:
+    'Structure divergent thinking (explore many options) followed by convergence (evaluate and select). Maximizes creative exploration before narrowing down.',
+  arguments: [
+    {
+      name: 'challenge',
+      description: 'The problem or challenge to solve',
+      required: true,
+    },
+    {
+      name: 'width',
+      description: 'Exploration width: "wild" for creative/unconventional, "focused" for practical',
+      required: false,
+    },
+    {
+      name: 'convergence_criteria',
+      description: 'What makes a solution "good" - criteria for evaluating options',
+      required: false,
+    },
+  ],
+  buildMessages: (args: Record<string, string>) => {
+    const { challenge, width, convergence_criteria } = args;
+
+    if (!challenge) {
+      throw new Error('challenge argument is required');
+    }
+
+    const explorationMode = width || 'balanced';
+    const criteria = convergence_criteria || 'feasibility, impact, and effort required';
+
+    let messageText = `Let's use divergent-then-convergent thinking:
+
+**CHALLENGE:**
+${challenge}
+
+**EXPLORATION MODE:** ${explorationMode}
+**SUCCESS CRITERIA:** ${criteria}
+
+---
+
+## PHASE 1: DIVERGE
+
+Each LLM should propose 2-3 **substantially DIFFERENT** approaches. The goal is diversity, not agreement.
+
+Guidelines:
+- Maximize variety in your proposals
+- Include at least one unconventional or surprising idea
+- Don't self-censor "crazy" ideas yet
+- Brief descriptions are fine - we'll evaluate later
+`;
+
+    if (explorationMode === 'wild') {
+      messageText += `- Push boundaries - what would you suggest if there were no constraints?
+`;
+    } else if (explorationMode === 'focused') {
+      messageText += `- Stay practical - focus on implementable solutions
+`;
+    }
+
+    messageText += `
+---
+
+## PHASE 2: CONVERGE
+
+After all options are on the table, evaluate them against the success criteria:
+
+1. **Quick assessment** of each option against: ${criteria}
+2. **Identify top 2-3 candidates** that best meet the criteria
+3. **Hybrid opportunities** - can elements from different approaches be combined?
+4. **Recommendation** - which approach (or combination) should we pursue?
+
+---
+
+Start with Phase 1 - generate diverse options first, then we'll converge.`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: messageText,
+        },
+      },
+    ];
+  },
+};