error-pattern-safety

# 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:** ```javascript // 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:** ```javascript // 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** ```javascript 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) ```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) ```javascript 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 ```javascript // 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** ```go { 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 // 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 ```go // 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):** ```go Pattern: `.*error.*` // Can match empty at start/end ``` **After (safe):** ```go 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` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/github) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-11 -->