error-pattern-safety

name	error-pattern-safety
description	Error Pattern Safety Guidelines for Agentic Engines

Error Pattern Safety Guidelines

This document outlines the safety guidelines for error pattern regex in agentic engines to prevent infinite loops in JavaScript.

The Problem

When using regex patterns with the JavaScript global flag (/pattern/g), patterns that can match zero-width (empty strings) can cause infinite loops. This happens because:

1. JavaScript's regex.exec() with the g flag uses lastIndex to track position
2. When a pattern matches zero-width, lastIndex doesn't advance
3. The same position is matched repeatedly, causing an infinite loop

Dangerous Pattern Examples

❌ NEVER USE THESE PATTERNS:

// Pure .* - matches everything including empty string at end
/.*/g

// Single character with * - matches zero or more (including zero)
/a*/g

// Patterns that can match empty string
/(x|y)*/g

Safe Pattern Examples

✅ ALWAYS USE PATTERNS LIKE THESE:

// Required prefix before .*
/error.*/gi
/error.*permission.*denied/gi

// Specific structure with required content
/\[(\d{4}-\d{2}-\d{2})\]\s+(ERROR):\s+(.+)/g

// Required characters throughout
/access denied.*user.*not authorized/gi

Pattern Safety Rules

1. Always require at least one character match

   • Use .+ instead of .* when you need "something"
   • Ensure pattern has required prefix/suffix

2. Never use bare .* as the entire pattern

   • Always combine with required text: error.*
   • Never just .* or .*?

3. Test patterns against empty string

   const regex = /your-pattern/g;
   if (regex.test("")) {
     throw new Error("Pattern matches empty string - DANGEROUS!");
   }
   

4. Use specific anchors when possible

   • Start: ^error.*
   • End: .*error$
   • Word boundaries: \berror\b

Validation Tests

All error patterns must pass these tests:

Go Tests (pkg/workflow/engine_error_patterns_infinite_loop_test.go)

// Test that pattern doesn't match empty string
func TestPatternSafety(t *testing.T) {
    pattern := "your-pattern"
    regex := regexp.MustCompile(pattern)
    
    if regex.MatchString("") {
        t.Error("Pattern matches empty string!")
    }
}

JavaScript Tests (pkg/workflow/js/validate_errors.test.cjs)

test("should not match empty string", () => {
  const regex = new RegExp("your-pattern", "g");
  expect(regex.test("")).toBe(false);
});

Safety Mechanisms in validate_errors.cjs

The validate_errors.cjs script has built-in protections:

1. Zero-width detection: Checks if regex.lastIndex stops advancing
2. Iteration warning: Warns at 1000 iterations
3. Hard limit: Stops at 10,000 iterations to prevent hang

// Safety check in validate_errors.cjs
if (regex.lastIndex === lastIndex) {
  core.error(`Infinite loop detected! Pattern: ${pattern.pattern}`);
  break;
}

Adding New Error Patterns

When adding new error patterns to engines:

1. Write the pattern with required content

   {
       Pattern:      `(?i)error.*permission.*denied`,
       LevelGroup:   0,
       MessageGroup: 0,
       Description:  "Permission denied error",
   }
   

2. Test against empty string

   • Run: make test-unit
   • Checks: TestAllEnginePatternsSafe

3. Test with actual log samples

   • Ensure it matches real errors
   • Ensure it doesn't match informational text

4. Document the pattern

   • Add clear description
   • Note what it's designed to catch

Pattern Conversion: Go to JavaScript

Patterns are converted from Go to JavaScript:

// Go pattern (case-insensitive flag)
Pattern: `(?i)error.*permission.*denied`

// Converted to JavaScript
new RegExp("error.*permission.*denied", "gi")

The (?i) prefix is removed because JavaScript uses the i flag instead.

Examples from Current Codebase

✅ Safe Patterns

// Requires "error" prefix
Pattern: `(?i)error.*permission.*denied`

// Requires specific timestamp format
Pattern: `(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)\s+\[(ERROR)\]\s+(.+)`

// Requires "access denied" prefix
Pattern: `(?i)access denied.*user.*not authorized`

How to Fix Unsafe Patterns

If you find a pattern that matches empty string:

Before (unsafe):

Pattern: `.*error.*`  // Can match empty at start/end

After (safe):

Pattern: `error.*`     // Requires "error" at start
// OR
Pattern: `.*error.+`   // Requires "error" and at least one char after
// OR
Pattern: `\berror\b.*` // Requires word "error"

Testing Checklist

Before committing pattern changes:

• Run make test-unit
• Check TestAllEnginePatternsSafe passes
• Check TestErrorPatternsNoInfiniteLoopPotential passes
• Run JavaScript tests: cd pkg/workflow/js && npm test
• Verify pattern matches intended error messages
• Verify pattern doesn't match informational text

References

• Go regex syntax: https://pkg.go.dev/regexp/syntax
• JavaScript regex: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
• Test files:
  • pkg/workflow/engine_error_patterns_infinite_loop_test.go
  • pkg/workflow/js/validate_errors.test.cjs
  • pkg/workflow/error_pattern_tuning_test.go