@firela/billclaw-core 0.2.0 → 0.4.0

package/dist/errors/errors.js

@@ -1,8 +1,9 @@
 /**
  * Error handling utilities for BillClaw
  *
- * Provides user-friendly error messages, recovery suggestions,
- * and troubleshooting guides.
+ * Provides dual-mode error handling:
+ * - Machine-readable: For AI agents (error codes, severity, executable actions)
+ * - Human-readable: For display (title, message, suggestions)
  *
  * Framework-agnostic: Logger is provided via runtime abstraction.
  */
@@ -29,45 +30,121 @@ export var ErrorCategory;
     ErrorCategory["UNKNOWN"] = "unknown";
 })(ErrorCategory || (ErrorCategory = {}));
 /**
- * Create a user-friendly error
+ * Error codes for programmatic error handling
+ * Used by AI agents for switch/case logic and decision making
  */
-export function createUserError(category, title, message, suggestions, docsLink, originalError) {
+export const ERROR_CODES = {
+    // Lock errors
+    LOCK_ACQUISITION_FAILED: "LOCK_ACQUISITION_FAILED",
+    LOCK_TIMEOUT: "LOCK_TIMEOUT",
+    LOCK_STALE: "LOCK_STALE",
+    // Credential errors
+    CREDENTIALS_NOT_FOUND: "CREDENTIALS_NOT_FOUND",
+    CREDENTIALS_STORAGE_FAILED: "CREDENTIALS_STORAGE_FAILED",
+    CREDENTIALS_KEYCHAIN_FAILED: "CREDENTIALS_KEYCHAIN_FAILED",
+    // Network errors
+    NETWORK_CONNECTION_REFUSED: "NETWORK_CONNECTION_REFUSED",
+    NETWORK_TIMEOUT: "NETWORK_TIMEOUT",
+    NETWORK_DNS_FAILED: "NETWORK_DNS_FAILED",
+    NETWORK_GENERIC: "NETWORK_GENERIC",
+    // Plaid errors
+    PLAID_ITEM_LOGIN_REQUIRED: "PLAID_ITEM_LOGIN_REQUIRED",
+    PLAID_INVALID_ACCESS_TOKEN: "PLAID_INVALID_ACCESS_TOKEN",
+    PLAID_PRODUCT_NOT_READY: "PLAID_PRODUCT_NOT_READY",
+    PLAID_RATE_LIMIT_EXCEEDED: "PLAID_RATE_LIMIT_EXCEEDED",
+    PLAID_INSTITUTION_DOWN: "PLAID_INSTITUTION_DOWN",
+    PLAID_INVALID_CREDENTIALS: "PLAID_INVALID_CREDENTIALS",
+    PLAID_API_ERROR: "PLAID_API_ERROR",
+    // Gmail errors
+    GMAIL_AUTH_FAILED: "GMAIL_AUTH_FAILED",
+    GMAIL_ACCESS_DENIED: "GMAIL_ACCESS_DENIED",
+    GMAIL_API_NOT_FOUND: "GMAIL_API_NOT_FOUND",
+    GMAIL_RATE_LIMIT_EXCEEDED: "GMAIL_RATE_LIMIT_EXCEEDED",
+    GMAIL_API_ERROR: "GMAIL_API_ERROR",
+    // Storage errors
+    STORAGE_DISK_FULL: "STORAGE_DISK_FULL",
+    STORAGE_WRITE_FAILED: "STORAGE_WRITE_FAILED",
+    STORAGE_READ_FAILED: "STORAGE_READ_FAILED",
+    // File system errors
+    FS_PERMISSION_DENIED: "FS_PERMISSION_DENIED",
+    FS_NOT_FOUND: "FS_NOT_FOUND",
+    FS_GENERIC: "FS_GENERIC",
+    // Config errors
+    CONFIG_INVALID: "CONFIG_INVALID",
+    CONFIG_MISSING: "CONFIG_MISSING",
+    CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+    // Generic
+    UNKNOWN_ERROR: "UNKNOWN_ERROR",
+};
+/**
+ * Create a user-friendly error with dual-mode support
+ *
+ * @param errorCode - Machine-readable error code
+ * @param category - Error category
+ * @param severity - Error severity level
+ * @param recoverable - Whether the error is recoverable
+ * @param humanReadable - Human-readable error information
+ * @param nextActions - AI-executable recovery actions
+ * @param entities - Structured entity references
+ * @param originalError - Original error for debugging
+ */
+export function createUserError(errorCode, category, severity, recoverable, humanReadable, nextActions, entities, originalError) {
     return {
         type: "UserError",
+        errorCode,
         category,
-        title,
-        message,
-        suggestions,
-        docsLink,
-        error: originalError,
+        severity,
+        recoverable,
+        humanReadable,
+        nextActions,
+        entities,
+        originalError,
+        timestamp: new Date().toISOString(),
     };
 }
 /**
  * Format error for display to user
+ * Uses the humanReadable field for user-friendly output
  */
 export function formatError(error) {
     const lines = [];
-    // Header with category emoji
+    // Header with category emoji and severity
     const categoryEmoji = getCategoryEmoji(error.category);
-    lines.push(`${categoryEmoji} ${error.title}`);
+    const severityIndicator = getSeverityIndicator(error.severity);
+    lines.push(`${categoryEmoji} ${error.humanReadable.title} ${severityIndicator}`);
     lines.push("");
     // Message
-    lines.push(error.message);
+    lines.push(error.humanReadable.message);
     lines.push("");
     // Suggestions
-    if (error.suggestions.length > 0) {
+    if (error.humanReadable.suggestions.length > 0) {
         lines.push("Suggestions:");
-        for (let i = 0; i < error.suggestions.length; i++) {
-            lines.push(`   ${i + 1}. ${error.suggestions[i]}`);
+        for (let i = 0; i < error.humanReadable.suggestions.length; i++) {
+            lines.push(`   ${i + 1}. ${error.humanReadable.suggestions[i]}`);
         }
     }
     // Docs link
-    if (error.docsLink) {
+    if (error.humanReadable.docsLink) {
         lines.push("");
-        lines.push(`Learn more: ${error.docsLink}`);
+        lines.push(`Learn more: ${error.humanReadable.docsLink}`);
     }
+    // Error code (for debugging/Support)
+    lines.push("");
+    lines.push(`Error code: ${error.errorCode}`);
     return lines.join("\n");
 }
+/**
+ * Get severity indicator for display
+ */
+function getSeverityIndicator(severity) {
+    const indicators = {
+        fatal: "🔴",
+        error: "❌",
+        warning: "⚠️",
+        info: "ℹ️",
+    };
+    return indicators[severity] || "";
+}
 /**
  * Get emoji for error category
  */
@@ -90,107 +167,245 @@ function getCategoryEmoji(category) {
 /**
  * Parse Plaid error codes and create user-friendly errors
  */
-export function parsePlaidError(error) {
+export function parsePlaidError(error, accountId) {
     const errorCode = error.error_code || "UNKNOWN";
     const errorMessage = error.error_message || error.display_message || "An error occurred";
     const requestId = error.request_id;
     // Login required
     if (errorCode === "ITEM_LOGIN_REQUIRED" ||
         error.error_type === "ITEM_LOGIN_REQUIRED") {
-        return createUserError(ErrorCategory.PLAID_AUTH, "Account Re-Authentication Required", "Your bank account requires re-authentication. This happens when your bank credentials have changed or expired.", [
-            "Re-authenticate via your adapter's setup command",
-            "This will open a secure browser window where you can log into your bank",
-            "After re-authentication, your transactions will sync normally",
-        ], "https://plaid.com/docs/errors/#item-login-required");
+        return createUserError(ERROR_CODES.PLAID_ITEM_LOGIN_REQUIRED, ErrorCategory.PLAID_AUTH, "error", true, {
+            title: "Account Re-Authentication Required",
+            message: "Your bank account requires re-authentication. This happens when your bank credentials have changed or expired.",
+            suggestions: [
+                "Re-authenticate via your adapter's setup command",
+                "This will open a secure browser window where you can log into your bank",
+                "After re-authentication, your transactions will sync normally",
+            ],
+            docsLink: "https://plaid.com/docs/errors/#item-login-required",
+        }, [
+            {
+                type: "oauth_reauth",
+                tool: "plaid_oauth",
+                params: { accountId, item_id: error.item_id },
+                description: "Trigger OAuth re-authentication flow",
+            },
+        ], { accountId, itemId: error.item_id, institutionId: error.institution_id });
     }
     // Invalid credentials
     if (errorCode === "INVALID_ACCESS_TOKEN" ||
         error.error_type === "INVALID_ACCESS_TOKEN") {
-        return createUserError(ErrorCategory.PLAID_AUTH, "Invalid Access Token", "Your access token is invalid. This can happen if the token was revoked or corrupted.", [
-            "Run your adapter's setup command to reconnect your account",
-            "If this persists, remove and re-add the account",
-        ], "https://plaid.com/docs/errors/#invalid-access-token");
+        return createUserError(ERROR_CODES.PLAID_INVALID_ACCESS_TOKEN, ErrorCategory.PLAID_AUTH, "error", true, {
+            title: "Invalid Access Token",
+            message: "Your access token is invalid. This can happen if the token was revoked or corrupted.",
+            suggestions: [
+                "Run your adapter's setup command to reconnect your account",
+                "If this persists, remove and re-add the account",
+            ],
+            docsLink: "https://plaid.com/docs/errors/#invalid-access-token",
+        }, [
+            {
+                type: "oauth_reauth",
+                tool: "plaid_oauth",
+                params: { accountId },
+                description: "Re-authenticate to get a new access token",
+            },
+        ], { accountId, itemId: error.item_id });
     }
     // Product not ready
     if (errorCode === "PRODUCT_NOT_READY") {
-        return createUserError(ErrorCategory.PLAID_API, "Account Not Ready", "Your account is not fully set up yet. Plaid is still processing your account information.", [
-            "Wait a few minutes and try again",
-            "If this persists, contact Plaid support",
-        ], "https://plaid.com/docs/errors/#product-not-ready");
+        return createUserError(ERROR_CODES.PLAID_PRODUCT_NOT_READY, ErrorCategory.PLAID_API, "warning", true, {
+            title: "Account Not Ready",
+            message: "Your account is not fully set up yet. Plaid is still processing your account information.",
+            suggestions: [
+                "Wait a few minutes and try again",
+                "If this persists, contact Plaid support",
+            ],
+            docsLink: "https://plaid.com/docs/errors/#product-not-ready",
+        }, [
+            {
+                type: "retry",
+                delayMs: 60000,
+                description: "Retry after 1 minute",
+            },
+        ], { accountId, itemId: error.item_id });
     }
     // Rate limit
     if (errorCode === "RATE_LIMIT_EXCEEDED") {
-        return createUserError(ErrorCategory.PLAID_API, "API Rate Limit Exceeded", "Too many requests have been made to the Plaid API. Please wait before trying again.", [
-            "Wait a few minutes before syncing again",
-            "Consider syncing less frequently (e.g., daily instead of hourly)",
-            "If you need higher rate limits, upgrade your Plaid plan",
-        ], "https://plaid.com/docs/errors/#rate-limit-exceeded");
+        return createUserError(ERROR_CODES.PLAID_RATE_LIMIT_EXCEEDED, ErrorCategory.PLAID_API, "warning", true, {
+            title: "API Rate Limit Exceeded",
+            message: "Too many requests have been made to the Plaid API. Please wait before trying again.",
+            suggestions: [
+                "Wait a few minutes before syncing again",
+                "Consider syncing less frequently (e.g., daily instead of hourly)",
+                "If you need higher rate limits, upgrade your Plaid plan",
+            ],
+            docsLink: "https://plaid.com/docs/errors/#rate-limit-exceeded",
+        }, [
+            {
+                type: "retry",
+                delayMs: 300000, // 5 minutes
+                description: "Retry after 5 minutes",
+            },
+        ], { accountId });
     }
     // Institution down
     if (errorCode === "INSTITUTION_DOWN") {
-        return createUserError(ErrorCategory.PLAID_API, "Bank temporarily unavailable", "Your bank's systems are temporarily down for maintenance.", [
-            "Wait a few minutes and try again",
-            "Check your bank's website for service status updates",
-            "Your transactions will sync automatically once the bank is back online",
-        ], undefined);
+        return createUserError(ERROR_CODES.PLAID_INSTITUTION_DOWN, ErrorCategory.PLAID_API, "warning", true, {
+            title: "Bank temporarily unavailable",
+            message: "Your bank's systems are temporarily down for maintenance.",
+            suggestions: [
+                "Wait a few minutes and try again",
+                "Check your bank's website for service status updates",
+                "Your transactions will sync automatically once the bank is back online",
+            ],
+        }, [
+            {
+                type: "retry",
+                delayMs: 300000, // 5 minutes
+                description: "Retry after 5 minutes",
+            },
+        ], {
+            accountId,
+            institutionId: error.institution_id,
+        });
     }
     // Invalid credentials
     if (errorCode === "INVALID_CREDENTIALS") {
-        return createUserError(ErrorCategory.PLAID_API, "Invalid API Credentials", "The Plaid API credentials configured are invalid.", [
-            "Configure your Plaid client ID and secret",
-            "Verify your credentials at https://dashboard.plaid.com",
-        ], "https://dashboard.plaid.com");
+        return createUserError(ERROR_CODES.PLAID_INVALID_CREDENTIALS, ErrorCategory.PLAID_API, "error", false, {
+            title: "Invalid API Credentials",
+            message: "The Plaid API credentials configured are invalid.",
+            suggestions: [
+                "Configure your Plaid client ID and secret",
+                "Verify your credentials at https://dashboard.plaid.com",
+            ],
+            docsLink: "https://dashboard.plaid.com",
+        }, [
+            {
+                type: "config_change",
+                params: { setting: "plaid_credentials" },
+                description: "Update Plaid API credentials",
+            },
+        ], {});
     }
     // Generic Plaid error
-    return createUserError(ErrorCategory.PLAID_API, "Plaid API Error", `${errorMessage}${requestId ? ` (Request ID: ${requestId})` : ""}`, [
-        "Try again in a few minutes",
-        "Check Plaid status at https://status.plaid.com",
-    ], "https://plaid.com/docs/errors/");
+    return createUserError(ERROR_CODES.PLAID_API_ERROR, ErrorCategory.PLAID_API, "error", true, {
+        title: "Plaid API Error",
+        message: `${errorMessage}${requestId ? ` (Request ID: ${requestId})` : ""}`,
+        suggestions: [
+            "Try again in a few minutes",
+            "Check Plaid status at https://status.plaid.com",
+        ],
+        docsLink: "https://plaid.com/docs/errors/",
+    }, [
+        {
+            type: "retry",
+            delayMs: 60000,
+            description: "Retry after 1 minute",
+        },
+    ], { accountId, itemId: error.item_id });
 }
 /**
  * Parse Gmail API errors and create user-friendly errors
  */
-export function parseGmailError(error) {
+export function parseGmailError(error, accountId) {
     const statusCode = error.status || error.code || 0;
     // Unauthorized
     if (statusCode === 401) {
-        return createUserError(ErrorCategory.GMAIL_AUTH, "Gmail Authentication Failed", "Your Gmail access has expired or been revoked. You need to re-authenticate.", [
-            "Re-authenticate with Gmail via your adapter's setup command",
-            "Make sure you grant read-only access to your Gmail",
-            "Check that Google Cloud OAuth credentials are valid",
-        ], "https://developers.google.com/gmail/api/auth");
+        return createUserError(ERROR_CODES.GMAIL_AUTH_FAILED, ErrorCategory.GMAIL_AUTH, "error", true, {
+            title: "Gmail Authentication Failed",
+            message: "Your Gmail access has expired or been revoked. You need to re-authenticate.",
+            suggestions: [
+                "Re-authenticate with Gmail via your adapter's setup command",
+                "Make sure you grant read-only access to your Gmail",
+                "Check that Google Cloud OAuth credentials are valid",
+            ],
+            docsLink: "https://developers.google.com/gmail/api/auth",
+        }, [
+            {
+                type: "oauth_reauth",
+                tool: "gmail_oauth",
+                params: { accountId },
+                description: "Re-authenticate with Gmail",
+            },
+        ], { accountId });
     }
     // Forbidden
     if (statusCode === 403) {
-        return createUserError(ErrorCategory.GMAIL_API, "Gmail Access Denied", "Access to Gmail was denied. This usually means the OAuth token lacks the required permissions.", [
-            "Make sure the Gmail API is enabled in Google Cloud Console",
-            "Verify that the OAuth consent screen includes 'gmail.readonly' scope",
-            "Re-authenticate to grant proper permissions",
-        ], "https://developers.google.com/gmail/api/auth");
+        return createUserError(ERROR_CODES.GMAIL_ACCESS_DENIED, ErrorCategory.GMAIL_API, "error", false, {
+            title: "Gmail Access Denied",
+            message: "Access to Gmail was denied. This usually means the OAuth token lacks the required permissions.",
+            suggestions: [
+                "Make sure the Gmail API is enabled in Google Cloud Console",
+                "Verify that the OAuth consent screen includes 'gmail.readonly' scope",
+                "Re-authenticate to grant proper permissions",
+            ],
+            docsLink: "https://developers.google.com/gmail/api/auth",
+        }, [
+            {
+                type: "oauth_reauth",
+                tool: "gmail_oauth",
+                params: { accountId },
+                description: "Re-authenticate with proper permissions",
+            },
+        ], { accountId });
     }
     // Not found
     if (statusCode === 404) {
-        return createUserError(ErrorCategory.GMAIL_API, "Gmail API Not Found", "The Gmail API endpoint could not be found. This may be a configuration issue.", [
-            "Verify the Gmail API is enabled in your Google Cloud project",
-            "Check that the API name is correct: 'gmail.api'",
-            "Try re-enabling the Gmail API in Google Cloud Console",
-        ], "https://console.cloud.google.com/apis/library/gmail-api");
+        return createUserError(ERROR_CODES.GMAIL_API_NOT_FOUND, ErrorCategory.GMAIL_API, "error", false, {
+            title: "Gmail API Not Found",
+            message: "The Gmail API endpoint could not be found. This may be a configuration issue.",
+            suggestions: [
+                "Verify the Gmail API is enabled in your Google Cloud project",
+                "Check that the API name is correct: 'gmail.api'",
+                "Try re-enabling the Gmail API in Google Cloud Console",
+            ],
+            docsLink: "https://console.cloud.google.com/apis/library/gmail-api",
+        }, [
+            {
+                type: "config_change",
+                params: { setting: "gmail_api_enabled" },
+                description: "Enable Gmail API in Google Cloud Console",
+            },
+        ], {});
     }
     // Rate limit
     if (statusCode === 429) {
-        return createUserError(ErrorCategory.GMAIL_API, "Gmail API Rate Limit Exceeded", "Too many requests have been made to the Gmail API. You've hit the daily quota limit.", [
-            "Wait until tomorrow when the quota resets",
-            "Reduce sync frequency to avoid hitting the limit",
-            "Consider using Gmail push notifications instead of polling",
-            "Free tier: 250 quota units/day",
-        ], "https://developers.google.com/gmail/api/v1/quota");
+        return createUserError(ERROR_CODES.GMAIL_RATE_LIMIT_EXCEEDED, ErrorCategory.GMAIL_API, "warning", true, {
+            title: "Gmail API Rate Limit Exceeded",
+            message: "Too many requests have been made to the Gmail API. You've hit the daily quota limit.",
+            suggestions: [
+                "Wait until tomorrow when the quota resets",
+                "Reduce sync frequency to avoid hitting the limit",
+                "Consider using Gmail push notifications instead of polling",
+                "Free tier: 250 quota units/day",
+            ],
+            docsLink: "https://developers.google.com/gmail/api/v1/quota",
+        }, [
+            {
+                type: "wait",
+                description: "Wait until quota resets (usually daily)",
+            },
+        ], { accountId });
     }
     // Generic Gmail error
-    return createUserError(ErrorCategory.GMAIL_API, "Gmail API Error", error.message || "An error occurred while communicating with Gmail", [
-        "Check your internet connection",
-        "Verify Gmail API is enabled in Google Cloud Console",
-        "Try again in a few minutes",
-    ], "https://developers.google.com/gmail/api");
+    return createUserError(ERROR_CODES.GMAIL_API_ERROR, ErrorCategory.GMAIL_API, "error", true, {
+        title: "Gmail API Error",
+        message: error.message ||
+            "An error occurred while communicating with Gmail",
+        suggestions: [
+            "Check your internet connection",
+            "Verify Gmail API is enabled in Google Cloud Console",
+            "Try again in a few minutes",
+        ],
+        docsLink: "https://developers.google.com/gmail/api",
+    }, [
+        {
+            type: "retry",
+            delayMs: 60000,
+            description: "Retry after 1 minute",
+        },
+    ], { accountId });
 }
 /**
  * Parse network errors
@@ -200,36 +415,76 @@ export function parseNetworkError(error) {
     // Connection refused
     if (message.includes("econnrefused") ||
         message.includes("connection refused")) {
-        return createUserError(ErrorCategory.NETWORK, "Connection Refused", "Could not connect to the server. The service may be down or your network is blocking the connection.", [
-            "Check your internet connection",
-            "Verify you're not behind a firewall or proxy",
-            "If using a VPN, try disconnecting it",
-            "Check if the service is temporarily down",
-        ], undefined);
+        return createUserError(ERROR_CODES.NETWORK_CONNECTION_REFUSED, ErrorCategory.NETWORK, "error", true, {
+            title: "Connection Refused",
+            message: "Could not connect to the server. The service may be down or your network is blocking the connection.",
+            suggestions: [
+                "Check your internet connection",
+                "Verify you're not behind a firewall or proxy",
+                "If using a VPN, try disconnecting it",
+                "Check if the service is temporarily down",
+            ],
+        }, [
+            {
+                type: "retry",
+                delayMs: 30000,
+                description: "Retry after 30 seconds",
+            },
+        ], {}, error);
     }
     // Timeout
     if (message.includes("timeout") || message.includes("timed out")) {
-        return createUserError(ErrorCategory.NETWORK, "Request Timeout", "The request took too long to complete. This could be due to slow network or server issues.", [
-            "Check your internet connection speed",
-            "Try again in a few minutes",
-            "If syncing many transactions, consider reducing the date range",
-        ], undefined);
+        return createUserError(ERROR_CODES.NETWORK_TIMEOUT, ErrorCategory.NETWORK, "warning", true, {
+            title: "Request Timeout",
+            message: "The request took too long to complete. This could be due to slow network or server issues.",
+            suggestions: [
+                "Check your internet connection speed",
+                "Try again in a few minutes",
+                "If syncing many transactions, consider reducing the date range",
+            ],
+        }, [
+            {
+                type: "retry",
+                delayMs: 60000,
+                description: "Retry after 1 minute",
+            },
+        ], {}, error);
     }
     // DNS resolution failed
     if (message.includes("enotfound") || message.includes("getaddrinfo")) {
-        return createUserError(ErrorCategory.NETWORK, "DNS Resolution Failed", "Could not resolve the server address. This might be a DNS or network configuration issue.", [
-            "Check your internet connection",
-            "Try switching to a different DNS server (e.g., 8.8.8.8)",
-            "Flush your DNS cache",
-            "If you're using a VPN, try disconnecting it",
-        ], undefined);
+        return createUserError(ERROR_CODES.NETWORK_DNS_FAILED, ErrorCategory.NETWORK, "error", false, {
+            title: "DNS Resolution Failed",
+            message: "Could not resolve the server address. This might be a DNS or network configuration issue.",
+            suggestions: [
+                "Check your internet connection",
+                "Try switching to a different DNS server (e.g., 8.8.8.8)",
+                "Flush your DNS cache",
+                "If you're using a VPN, try disconnecting it",
+            ],
+        }, [
+            {
+                type: "manual_intervention",
+                description: "Manual network configuration may be required",
+            },
+        ], {}, error);
     }
     // Generic network error
-    return createUserError(ErrorCategory.NETWORK, "Network Error", error.message || "An error occurred while communicating with the server", [
-        "Check your internet connection",
-        "Try again in a few minutes",
-        "If the problem persists, check your network settings",
-    ], undefined);
+    return createUserError(ERROR_CODES.NETWORK_GENERIC, ErrorCategory.NETWORK, "error", true, {
+        title: "Network Error",
+        message: error.message ||
+            "An error occurred while communicating with the server",
+        suggestions: [
+            "Check your internet connection",
+            "Try again in a few minutes",
+            "If the problem persists, check your network settings",
+        ],
+    }, [
+        {
+            type: "retry",
+            delayMs: 60000,
+            description: "Retry after 1 minute",
+        },
+    ], {}, error);
 }
 /**
  * Parse file system errors
@@ -239,31 +494,69 @@ export function parseFileSystemError(error, filePath) {
     const message = error.message;
     // Permission denied
     if (code === "EACCES" || code === "EPERM") {
-        return createUserError(ErrorCategory.FILE_SYSTEM, "Permission Denied", `Cannot access ${filePath || "file or directory"}. You don't have the required permissions.`, [
-            "Check file/directory permissions",
-            "Ensure the user has read/write access to the data directory",
-        ], undefined);
+        return createUserError(ERROR_CODES.FS_PERMISSION_DENIED, ErrorCategory.FILE_SYSTEM, "error", false, {
+            title: "Permission Denied",
+            message: `Cannot access ${filePath || "file or directory"}. You don't have the required permissions.`,
+            suggestions: [
+                "Check file/directory permissions",
+                "Ensure the user has read/write access to the data directory",
+            ],
+        }, [
+            {
+                type: "manual_intervention",
+                description: "Fix file/directory permissions manually",
+            },
+        ], { filePath }, error);
     }
     // No space left
     if (code === "ENOSPC") {
-        return createUserError(ErrorCategory.STORAGE, "Disk Full", "No space left on device. Cannot save transactions.", [
-            "Free up disk space by deleting unnecessary files",
-            "Consider moving the BillClaw data directory to a drive with more space",
-        ], undefined);
+        return createUserError(ERROR_CODES.STORAGE_DISK_FULL, ErrorCategory.STORAGE, "fatal", false, {
+            title: "Disk Full",
+            message: "No space left on device. Cannot save transactions.",
+            suggestions: [
+                "Free up disk space by deleting unnecessary files",
+                "Consider moving the BillClaw data directory to a drive with more space",
+            ],
+        }, [
+            {
+                type: "manual_intervention",
+                description: "Free up disk space manually",
+            },
+        ], {}, error);
     }
     // Directory not found
     if (code === "ENOENT" && message.includes("no such file")) {
-        return createUserError(ErrorCategory.FILE_SYSTEM, "File or Directory Not Found", `The file or directory ${filePath || ""} does not exist.`, [
-            "Run setup to initialize BillClaw",
-            "Verify the data directory path is correct",
-        ], undefined);
+        return createUserError(ERROR_CODES.FS_NOT_FOUND, ErrorCategory.FILE_SYSTEM, "error", false, {
+            title: "File or Directory Not Found",
+            message: `The file or directory ${filePath || ""} does not exist.`,
+            suggestions: [
+                "Run setup to initialize BillClaw",
+                "Verify the data directory path is correct",
+            ],
+        }, [
+            {
+                type: "config_change",
+                params: { setting: "data_directory" },
+                description: "Update data directory path",
+            },
+        ], { filePath }, error);
     }
     // Generic file system error
-    return createUserError(ErrorCategory.FILE_SYSTEM, "File System Error", message || "An error occurred while accessing the file system", [
-        "Check file/directory permissions",
-        "Ensure the data directory exists and is writable",
-        "Try running setup to reinitialize",
-    ], undefined);
+    return createUserError(ERROR_CODES.FS_GENERIC, ErrorCategory.FILE_SYSTEM, "error", true, {
+        title: "File System Error",
+        message: message ||
+            "An error occurred while accessing the file system",
+        suggestions: [
+            "Check file/directory permissions",
+            "Ensure the data directory exists and is writable",
+            "Try running setup to reinitialize",
+        ],
+    }, [
+        {
+            type: "manual_intervention",
+            description: "Manual intervention may be required",
+        },
+    ], { filePath }, error);
 }
 /**
  * Type guard to check if error is a UserError
@@ -272,23 +565,29 @@ export function isUserError(error) {
     return (typeof error === "object" &&
         error !== null &&
         "type" in error &&
-        error.type === "UserError");
+        error.type === "UserError" &&
+        "errorCode" in error &&
+        "humanReadable" in error);
 }
 /**
  * Log error with context for debugging
  */
 export function logError(logger, error, context) {
     const logData = {
-        timestamp: new Date().toISOString(),
+        timestamp: isUserError(error) ? error.timestamp : new Date().toISOString(),
+        errorCode: isUserError(error) ? error.errorCode : undefined,
         category: isUserError(error) ? error.category : ErrorCategory.UNKNOWN,
-        message: error.message,
+        severity: isUserError(error) ? error.severity : undefined,
+        recoverable: isUserError(error) ? error.recoverable : undefined,
+        message: isUserError(error) ? error.humanReadable.message : error.message,
+        entities: isUserError(error) ? error.entities : undefined,
         context,
     };
-    if (isUserError(error) && error.error) {
+    if (isUserError(error) && error.originalError) {
         logData.originalError = {
-            name: error.error.name,
-            message: error.error.message,
-            stack: error.error.stack,
+            name: error.originalError.name,
+            message: error.originalError.message,
+            stack: error.originalError.stack,
         };
     }
     logger?.error?.("BillClaw error:", JSON.stringify(logData, null, 2));