groundswell 0.0.2 → 1.0.0

package/dist/utils/restart-analysis.js

@@ -0,0 +1,426 @@
+/**
+ * Error analysis utilities for step restart decisions
+ *
+ * Provides pure, side-effect-free functions for analyzing WorkflowError instances
+ * to determine if a step should be restarted, with structured restart analysis
+ * including reason, suggested action, and success probability estimation.
+ *
+ * @module restart-analysis
+ */
+/**
+ * Transient error codes that typically indicate temporary failures
+ *
+ * These errors are usually resolved by retrying the operation after a delay.
+ * The constant uses const assertion for type safety and better TypeScript inference.
+ *
+ * **Error Categories:**
+ * - `TIMEOUT`: Operation timed out waiting for response
+ * - `RATE_LIMIT`: API rate limit exceeded (HTTP 429)
+ * - `NETWORK_ERROR`: Network connectivity issues
+ * - `SERVICE_UNAVAILABLE`: Service temporarily unavailable (HTTP 503)
+ *
+ * @example
+ * ```ts
+ * if (TRANSIENT_ERROR_SET.has('TIMEOUT')) {
+ *   // This is a transient error, safe to retry
+ * }
+ * ```
+ */
+const TRANSIENT_ERROR_CODES = [
+    'TIMEOUT',
+    'RATE_LIMIT',
+    'NETWORK_ERROR',
+    'SERVICE_UNAVAILABLE',
+];
+/**
+ * Set-based lookup for O(1) transient error code checking
+ *
+ * Using a Set provides constant-time lookup performance compared to
+ * array includes() which is O(n). This is important for hot paths
+ * in retry logic.
+ */
+const TRANSIENT_ERROR_SET = new Set(TRANSIENT_ERROR_CODES);
+/**
+ * Check if an error is a transient (temporary) error
+ *
+ * Transient errors are temporary faults that typically resolve themselves
+ * quickly without intervention. These are safe to retry with a high
+ * probability of success.
+ *
+ * **Detection Strategy:**
+ * 1. Check error.message against transient error codes (most reliable)
+ * 2. WorkflowError doesn't have a 'code' property, so message is used as fallback
+ *
+ * @param error - The WorkflowError to analyze
+ * @returns `true` if the error is transient and should be retried
+ *
+ * @example
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'TIMEOUT',
+ *   original: new Error('Request timeout'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * if (isTransientError(error)) {
+ *   // Safe to retry with high success probability
+ * }
+ * ```
+ *
+ * @remarks
+ * **Gotcha:** WorkflowError interface doesn't have a 'code' property,
+ * so this function uses error.message as fallback. This is consistent
+ * with the pattern used in src/decorators/step.ts:48.
+ */
+function isTransientError(error) {
+    // GOTCHA: WorkflowError doesn't have 'code' property
+    // Use error.message as fallback (consistent with step decorator pattern)
+    const errorCode = error.message;
+    return TRANSIENT_ERROR_CODES.includes(errorCode);
+}
+/**
+ * Check if an error matches a specific error criterion
+ *
+ * Handles all three ErrorCriterion variants:
+ * 1. **By error code** - Exact string match or regex pattern matching
+ * 2. **By recoverable flag** - Match recoverable vs non-recoverable errors
+ * 3. **Custom predicate** - Function for complex matching logic
+ *
+ * **CRITICAL:** Function criteria MUST be checked first at runtime.
+ * Functions can have properties in JavaScript, so discriminant checks like
+ * `'code' in criterion` will return `true` for functions with a `code` property,
+ * breaking type narrowing.
+ *
+ * @param error - The WorkflowError to check against the criterion
+ * @param criterion - The ErrorCriterion to match against
+ * @returns `true` if the error matches the criterion
+ *
+ * @example String code matching
+ * ```ts
+ * const criterion: ErrorCriterion = { code: 'TIMEOUT' };
+ * const error: WorkflowError = { message: 'TIMEOUT', ... };
+ * matchesCriterion(error, criterion); // true
+ * ```
+ *
+ * @example Regex code matching
+ * ```ts
+ * const criterion: ErrorCriterion = { code: /TIMEOUT|NETWORK_ERROR/ };
+ * const error: WorkflowError = { message: 'TIMEOUT', ... };
+ * matchesCriterion(error, criterion); // true
+ * ```
+ *
+ * @example Recoverable flag matching
+ * ```ts
+ * const criterion: ErrorCriterion = { recoverable: true };
+ * const error: WorkflowError = {
+ *   message: 'Temporary failure',
+ *   original: { recoverable: true },
+ *   ...
+ * };
+ * matchesCriterion(error, criterion); // true
+ * ```
+ *
+ * @example Custom predicate
+ * ```ts
+ * const criterion: ErrorCriterion = (error) => {
+ *   return error.message.includes('timeout') ||
+ *          error.message.includes('network');
+ * };
+ * matchesCriterion(error, criterion); // true if message contains keywords
+ * ```
+ *
+ * @remarks
+ * **Runtime Safety Pattern:**
+ * ```ts
+ * // CORRECT: Check function FIRST
+ * if (typeof criterion === 'function') {
+ *   return criterion(error);
+ * }
+ * // Now safe to use discriminant checks
+ * if ('code' in criterion) { ... }
+ * ```
+ *
+ * **Why this matters:**
+ * ```ts
+ * const func = () => true;
+ * func.code = 'TIMEOUT'; // Functions can have properties!
+ * 'code' in func // true! (TypeScript would incorrectly narrow type)
+ * ```
+ */
+function matchesCriterion(error, criterion) {
+    // CRITICAL: Check typeof first for function type narrowing
+    // Functions can have properties, breaking discriminant checks
+    if (typeof criterion === 'function') {
+        return criterion(error);
+    }
+    // Object type checks (type narrowing works after typeof check)
+    if ('code' in criterion) {
+        // GOTCHA: Use error.message as fallback for error.code
+        // WorkflowError doesn't have a code property (step.ts:48 pattern)
+        const errorCode = error.message;
+        return typeof criterion.code === 'string'
+            ? errorCode === criterion.code
+            : criterion.code.test(errorCode);
+    }
+    if ('recoverable' in criterion) {
+        // Check error.original for recoverable property
+        const original = error.original;
+        if (original && 'recoverable' in original) {
+            return original.recoverable === criterion.recoverable;
+        }
+        // If no recoverable field, default to true for backward compatibility
+        return criterion.recoverable;
+    }
+    return false;
+}
+/**
+ * Estimate the probability of success for a retry attempt
+ *
+ * Returns a value between 0.0 and 1.0 indicating the likelihood that
+ * retrying the operation will succeed.
+ *
+ * **Probability Interpretation:**
+ * - `0.0 - 0.3`: Low probability - consider abort or rebuild
+ * - `0.4 - 0.6`: Moderate probability - retry with caution
+ * - `0.7 - 1.0`: High probability - safe to retry
+ *
+ * **Estimation Strategy:**
+ * 1. Transient errors: 0.8 (high probability - these typically resolve)
+ * 2. Permanent errors (auth, validation): 0.0 (no chance - won't fix themselves)
+ * 3. Unknown errors: 0.5 (moderate probability - best effort guess)
+ *
+ * @param error - The WorkflowError to analyze
+ * @returns Success probability estimate (0.0 to 1.0)
+ *
+ * @example
+ * ```ts
+ * const timeoutError: WorkflowError = { message: 'TIMEOUT', ... };
+ * estimateSuccessProbability(timeoutError); // 0.8 (high)
+ *
+ * const authError: WorkflowError = { message: 'UNAUTHORIZED', ... };
+ * estimateSuccessProbability(authError); // 0.0 (none)
+ *
+ * const unknownError: WorkflowError = { message: 'UNKNOWN_ERROR', ... };
+ * estimateSuccessProbability(unknownError); // 0.5 (moderate)
+ * ```
+ */
+function estimateSuccessProbability(error) {
+    // Check if transient error first
+    if (isTransientError(error)) {
+        return 0.8; // High probability for transient errors
+    }
+    // Check error message for permanent error patterns
+    const msg = error.message.toLowerCase();
+    if (msg.includes('unauthorized') ||
+        msg.includes('forbidden') ||
+        msg.includes('invalid') ||
+        msg.includes('authentication') ||
+        msg.includes('auth')) {
+        return 0.0; // No chance for auth/validation errors
+    }
+    // Default: moderate probability
+    return 0.5;
+}
+/**
+ * Analyze a WorkflowError to determine if a step should be restarted
+ *
+ * This is a pure, side-effect-free function that provides intelligent error
+ * analysis for step retry decisions. It returns a structured `RestartAnalysis`
+ * object with the restart decision, reasoning, suggested action, and success
+ * probability estimation.
+ *
+ * **Analysis Flow:**
+ * 1. Check `error.original?.recoverable` - if `false`, return abort immediately
+ * 2. Check if error is transient - if yes, return retry with high probability
+ * 3. If `stepOptions.retryOn` provided, iterate through criteria
+ * 4. For each criterion, call `matchesCriterion(error, criterion)`
+ * 5. If any criterion matches, return restart with analysis
+ * 6. Default: return no restart with abort action
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs or external state
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @param error - The WorkflowError to analyze
+ * @param stepOptions - Optional step configuration with retry criteria
+ * @returns Structured restart analysis with decision and reasoning
+ *
+ * @example Transient error - automatic restart
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'TIMEOUT',
+ *   original: new Error('Request timeout'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error);
+ * // Returns:
+ * // {
+ * //   shouldRestart: true,
+ * //   reason: 'Transient error detected: TIMEOUT',
+ * //   suggestedAction: 'retry',
+ * //   estimatedSuccessProbability: 0.8
+ * // }
+ * ```
+ *
+ * @example Non-recoverable error - abort
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'Invalid configuration',
+ *   original: { recoverable: false },
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error);
+ * // Returns:
+ * // {
+ * //   shouldRestart: false,
+ * //   reason: 'Error is marked as non-recoverable: Invalid configuration',
+ * //   suggestedAction: 'abort',
+ * //   estimatedSuccessProbability: 0.0
+ * // }
+ * ```
+ *
+ * @example Custom retry criteria
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'ETIMEDOUT',
+ *   original: new Error('Connection timeout'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const stepOptions = {
+ *   retryOn: [
+ *     { code: 'ETIMEDOUT' },
+ *     { code: /NETWORK_ERROR/ },
+ *     { recoverable: true }
+ *   ]
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error, stepOptions);
+ * // Returns:
+ * // {
+ * //   shouldRestart: true,
+ * //   reason: 'Error matches retry criteria: ETIMEDOUT',
+ * //   suggestedAction: 'retry',
+ * //   estimatedSuccessProbability: 0.5
+ * // }
+ * ```
+ *
+ * @example No matching criteria - default abort
+ * ```ts
+ * const error: WorkflowError = {
+ *   message: 'AUTH_FAILED',
+ *   original: new Error('Authentication failed'),
+ *   workflowId: 'wf-123',
+ *   state: {},
+ *   logs: []
+ * };
+ *
+ * const stepOptions = {
+ *   retryOn: [{ code: 'TIMEOUT' }]
+ * };
+ *
+ * const analysis = analyzeErrorForRestart(error, stepOptions);
+ * // Returns:
+ * // {
+ * //   shouldRestart: false,
+ * //   reason: 'No matching retry criteria for error: AUTH_FAILED',
+ * //   suggestedAction: 'abort',
+ * //   estimatedSuccessProbability: 0.0
+ * // }
+ * ```
+ *
+ * @remarks
+ * **Integration with @Step Decorator:**
+ * This function is designed to be used by the @Step decorator's retry loop
+ * (src/decorators/step.ts:115-228) to provide structured analysis for
+ * stepRetry events.
+ *
+ * **ErrorCriterion Pattern:**
+ * The function follows the existing pattern in src/decorators/step.ts:40-65
+ * for matching criteria against errors.
+ *
+ * **Gotchas:**
+ * - WorkflowError doesn't have a 'code' property - uses message as fallback
+ * - Always check `typeof criterion === 'function'` FIRST for type safety
+ * - Check error.original?.recoverable for recoverable flag
+ *
+ * @see {@link RestartAnalysis} - Return type structure
+ * @see {@link ErrorCriterion} - Retry criterion types
+ * @see {@link WorkflowError} - Input error type
+ */
+export function analyzeErrorForRestart(error, stepOptions) {
+    // STEP 1: Check recoverable flag (if available)
+    const original = error.original;
+    if (original && 'recoverable' in original && !original.recoverable) {
+        return {
+            shouldRestart: false,
+            reason: `Error is marked as non-recoverable: ${error.message}`,
+            suggestedAction: 'abort',
+            estimatedSuccessProbability: 0.0,
+        };
+    }
+    // STEP 2: Check if transient error
+    if (isTransientError(error)) {
+        return {
+            shouldRestart: true,
+            reason: `Transient error detected: ${error.message}`,
+            suggestedAction: 'retry',
+            estimatedSuccessProbability: 0.8,
+        };
+    }
+    // STEP 3: Check retry criteria if provided
+    if (stepOptions?.retryOn && stepOptions.retryOn.length > 0) {
+        for (const criterion of stepOptions.retryOn) {
+            if (matchesCriterion(error, criterion)) {
+                return {
+                    shouldRestart: true,
+                    reason: `Error matches retry criteria: ${error.message}`,
+                    suggestedAction: 'retry',
+                    estimatedSuccessProbability: estimateSuccessProbability(error),
+                };
+            }
+        }
+    }
+    // STEP 4: Default: no restart
+    return {
+        shouldRestart: false,
+        reason: `No matching retry criteria for error: ${error.message}`,
+        suggestedAction: 'abort',
+        estimatedSuccessProbability: 0.0,
+    };
+}
+/**
+ * Transient error codes constant
+ *
+ * Exported for testing and external use. Use TRANSIENT_ERROR_SET
+ * for O(1) lookup performance.
+ *
+ * @example
+ * ```ts
+ * import { TRANSIENT_ERROR_CODES } from './restart-analysis.js';
+ *
+ * if (TRANSIENT_ERROR_CODES.includes('TIMEOUT')) {
+ *   // Handle transient error
+ * }
+ * ```
+ */
+export { TRANSIENT_ERROR_CODES };
+/**
+ * Transient error code set for O(1) lookup
+ *
+ * Exported for testing and external use. Prefer this over
+ * TRANSIENT_ERROR_CODES for performance-critical code.
+ */
+export { TRANSIENT_ERROR_SET };
+//# sourceMappingURL=restart-analysis.js.map

package/dist/utils/restart-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-analysis.js","sourceRoot":"","sources":["../../src/utils/restart-analysis.ts"],"names":[],"mappings":"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"}

package/dist/utils/session-serialization.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Session serialization utilities
+ *
+ * @module
+ * @remarks
+ * Provides safe serialization/deserialization of SessionState objects
+ * containing SDK message types with circular reference handling.
+ *
+ * Handles edge cases including:
+ * - Circular references from application code
+ * - Non-serializable values (functions, Symbols)
+ * - Unknown type fields in SDK messages
+ * - Type validation during deserialization
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = { history: [], lastResult: null };
+ * const json = serializeSession(state);
+ * const restored = deserializeSession(json);
+ * console.log(restored); // { history: [], lastResult: null }
+ * ```
+ */
+import type { SessionState } from "../types/providers.js";
+/**
+ * Error thrown when session serialization fails
+ *
+ * @remarks
+ * Provides detailed error context for debugging serialization issues.
+ * Includes the property path and value that caused the failure.
+ *
+ * @public
+ */
+export declare class SessionSerializationError extends Error {
+    readonly path: string;
+    readonly value: unknown;
+    /**
+     * Creates a new SessionSerializationError
+     *
+     * @param message - Human-readable error message
+     * @param path - Property path where the error occurred (e.g., "history.0.tool_use_result")
+     * @param value - The value that caused the serialization failure
+     */
+    constructor(message: string, path: string, value: unknown);
+}
+/**
+ * Serialize a SessionState to JSON string
+ *
+ * @remarks
+ * Converts a SessionState object to a JSON string with special handling
+ * for non-serializable values and circular references. The resulting JSON
+ * is pretty-printed with 2-space indentation for readability.
+ *
+ * Handles edge cases from SDK message types:
+ * - `SDKUserMessage.tool_use_result` (unknown type)
+ * - `SDKResultMessage.result` (unknown type)
+ * - `SDKResultMessage.structured_output` (unknown type)
+ *
+ * Throws {@link SessionSerializationError} if serialization fails,
+ * with contextual information about the failure.
+ *
+ * @param state - The session state to serialize
+ * @returns JSON string representation of the session
+ * @throws {SessionSerializationError} If serialization fails
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = {
+ *   history: [],
+ *   lastResult: null
+ * };
+ *
+ * const json = serializeSession(state);
+ * console.log(json); // Pretty-printed JSON string
+ *
+ * // Round-trip serialization
+ * const restored = deserializeSession(json);
+ * expect(restored).toEqual(state);
+ * ```
+ */
+export declare function serializeSession(state: SessionState): string;
+/**
+ * Reconstruct a SessionState from JSON string
+ *
+ * @remarks
+ * Parses a JSON string and validates that it has the correct SessionState
+ * structure. Performs runtime type validation to ensure data integrity
+ * and catch corrupted or malformed session data early.
+ *
+ * Throws {@link SessionSerializationError} if deserialization fails or
+ * if the data doesn't match the expected SessionState structure.
+ *
+ * @param data - JSON string representation of the session
+ * @returns Reconstructed SessionState object
+ * @throws {SessionSerializationError} If deserialization fails or data is invalid
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = {
+ *   history: [],
+ *   lastResult: null
+ * };
+ *
+ * const json = serializeSession(state);
+ * const restored = deserializeSession(json);
+ *
+ * // Round-trip equality test
+ * expect(restored.history).toEqual(state.history);
+ * expect(restored.lastResult).toEqual(state.lastResult);
+ * ```
+ */
+export declare function deserializeSession(data: string): SessionState;
+//# sourceMappingURL=session-serialization.d.ts.map

package/dist/utils/session-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-serialization.d.ts","sourceRoot":"","sources":["../../src/utils/session-serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAUhC,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,OAAO;IAVhC;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO;CAKjC;AAwFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAY5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAmB7D"}