actual-mcp-server 0.5.0

package/dist/src/lib/actual-adapter.js

@@ -0,0 +1,1228 @@
+// Must be the very first import — sets globalThis.navigator before @actual-app/api is evaluated.
+// Required by @actual-app/api v26.3.0+ which uses navigator.platform at module load time.
+import './node-polyfills.js';
+import api from '@actual-app/api';
+// @actual-app/api is a CJS package (no "type" field). In NodeNext/ESM context TypeScript
+// cannot expose its named exports via static import syntax. At runtime the default import
+// IS module.exports, so all methods are accessible as properties.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule,
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ } = api;
+import { EventEmitter } from 'events';
+import observability from '../observability.js';
+import retry from './retry.js';
+import logger from '../logger.js';
+import config from '../config.js';
+import { parseBudgetRegistry } from './budget-registry.js';
+/**
+ * Budget registry — all budgets configured via ACTUAL_* and BUDGET_n_* env vars.
+ * Built once at startup; used by every withActualApi call.
+ */
+const budgetRegistry = parseBudgetRegistry(process.env, {
+    serverUrl: config.ACTUAL_SERVER_URL,
+    password: config.ACTUAL_PASSWORD,
+    syncId: config.ACTUAL_BUDGET_SYNC_ID,
+    encryptionPassword: config.ACTUAL_BUDGET_PASSWORD,
+});
+logger.info(`[ADAPTER] Budget registry: ${budgetRegistry.size} budget(s) — ` +
+    [...budgetRegistry.values()].map(b => `"${b.name}" (${b.serverUrl})`).join(', '));
+/**
+ * Key (lowercased budget name) of the currently active budget.
+ * Null = use the first entry in the registry (the default budget).
+ */
+let activeBudgetKey = null;
+function getActiveBudgetConfig() {
+    if (activeBudgetKey) {
+        const found = budgetRegistry.get(activeBudgetKey);
+        if (found)
+            return found;
+    }
+    return [...budgetRegistry.values()][0];
+}
+/**
+ * Global API session mutex.
+ * @actual-app/api is a singleton with a single SQLite connection — concurrent
+ * init/shutdown pairs corrupt the session.  All callers (reads via withActualApi,
+ * writes via processWriteQueue) must acquire this lock before touching the API.
+ */
+let _apiSessionLock = Promise.resolve();
+function withApiLock(fn) {
+    let release;
+    const prevLock = _apiSessionLock;
+    _apiSessionLock = new Promise(resolve => { release = resolve; });
+    return prevLock.then(() => fn()).finally(() => release());
+}
+/**
+ * Helper to init and shutdown Actual API around each operation
+ * This is CRITICAL for data persistence - shutdown() must be called after every operation
+ * Based on the pattern from https://github.com/s-stefanov/actual-mcp
+ */
+async function withActualApi(operation) {
+    return withApiLock(async () => {
+        try {
+            await initActualApiForOperation();
+            return await operation();
+        }
+        finally {
+            await shutdownActualApi();
+        }
+    });
+}
+/**
+ * Initialize Actual API - based on s-stefanov/actual-mcp pattern
+ * This calls api.init() and api.downloadBudget() for each operation
+ */
+async function initActualApiForOperation() {
+    try {
+        const budget = getActiveBudgetConfig();
+        const DATA_DIR = config.MCP_BRIDGE_DATA_DIR;
+        logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${budget.serverUrl})`);
+        await api.init({
+            dataDir: DATA_DIR,
+            serverURL: budget.serverUrl,
+            password: budget.password || '',
+        });
+        logger.debug('[ADAPTER] Downloading budget');
+        if (budget.encryptionPassword) {
+            const apiWithOptions = api;
+            await apiWithOptions.downloadBudget(budget.syncId, { password: budget.encryptionPassword });
+        }
+        else {
+            await api.downloadBudget(budget.syncId);
+        }
+        logger.debug('[ADAPTER] Actual API initialized for operation');
+    }
+    catch (err) {
+        logger.error('[ADAPTER] Error initializing Actual API:', err);
+        throw err;
+    }
+}
+async function shutdownActualApi() {
+    try {
+        const maybeApi = api;
+        if (typeof maybeApi.shutdown === 'function') {
+            await maybeApi.shutdown();
+            logger.debug('[ADAPTER] Actual API shutdown complete');
+        }
+    }
+    catch (err) {
+        logger.error('[ADAPTER] Error during Actual API shutdown:', err);
+    }
+}
+import { BANK_SYNC_SETTLE_MS, DEFAULT_CONCURRENCY_LIMIT, WRITE_SESSION_DELAY_MS } from './constants.js';
+/**
+ * Very small concurrency limiter for adapter calls. This prevents bursts from
+ * overloading the actual server. It's intentionally tiny and in-memory; replace
+ * with Bottleneck or p-queue for production.
+ */
+let MAX_CONCURRENCY = parseInt(process.env.ACTUAL_API_CONCURRENCY || String(DEFAULT_CONCURRENCY_LIMIT), 10);
+let running = 0;
+const queue = [];
+let writeQueue = [];
+let isProcessingWrites = false;
+let writeSessionTimeout = null;
+async function processWriteQueue() {
+    // Atomically check and set processing flag to prevent race conditions
+    if (isProcessingWrites || writeQueue.length === 0)
+        return;
+    isProcessingWrites = true;
+    // Clear the timeout since we're processing now
+    if (writeSessionTimeout) {
+        clearTimeout(writeSessionTimeout);
+        writeSessionTimeout = null;
+    }
+    const batch = writeQueue.splice(0, writeQueue.length); // Take all current items
+    logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations`);
+    try {
+        await withApiLock(async () => {
+            try {
+                // Initialize API once for all queued writes
+                await initActualApiForOperation();
+                // Process all queued writes in the same session
+                // Each operation handles its own success/failure
+                await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
+                    try {
+                        const result = await operation();
+                        resolve(result);
+                    }
+                    catch (error) {
+                        logger.error('[WRITE QUEUE] Operation failed:', error);
+                        reject(error);
+                    }
+                }));
+                // Explicitly sync changes to server before shutdown
+                // This ensures all write operations are persisted
+                logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
+                try {
+                    await api.sync();
+                    logger.debug(`[WRITE QUEUE] Sync completed`);
+                }
+                catch (syncError) {
+                    logger.error('[WRITE QUEUE] Sync failed:', syncError);
+                    // Don't throw - we still want to shutdown cleanly
+                    // Individual operation errors were already reported to callers
+                }
+                // Shutdown after all writes complete and sync
+                await shutdownActualApi();
+                logger.debug(`[WRITE QUEUE] Batch completed successfully`);
+            }
+            catch (error) {
+                logger.error('[WRITE QUEUE] Fatal error in write queue:', error);
+                // Reject any operations that weren't processed
+                batch.forEach(({ reject }) => {
+                    try {
+                        reject(error);
+                    }
+                    catch (e) {
+                        logger.error('[WRITE QUEUE] Error rejecting operation:', e);
+                    }
+                });
+                await shutdownActualApi();
+            }
+        });
+    }
+    finally {
+        isProcessingWrites = false;
+        // Process any new operations that were queued while we were processing
+        if (writeQueue.length > 0 && writeSessionTimeout === null) {
+            writeSessionTimeout = setTimeout(() => {
+                processWriteQueue();
+            }, WRITE_SESSION_DELAY_MS);
+        }
+    }
+}
+function queueWriteOperation(operation) {
+    return new Promise((resolve, reject) => {
+        writeQueue.push({ operation, resolve, reject });
+        // Clear existing timeout
+        if (writeSessionTimeout) {
+            clearTimeout(writeSessionTimeout);
+        }
+        // Set new timeout to process queue
+        writeSessionTimeout = setTimeout(() => {
+            processWriteQueue();
+        }, WRITE_SESSION_DELAY_MS);
+    });
+}
+function processQueue() {
+    if (running >= MAX_CONCURRENCY)
+        return;
+    const next = queue.shift();
+    if (!next)
+        return;
+    running++;
+    try {
+        next();
+    }
+    catch (e) {
+        // next() will manage its own promise resolution
+        running--;
+        processQueue();
+    }
+}
+function withConcurrency(fn) {
+    if (running < MAX_CONCURRENCY) {
+        running++;
+        return fn().finally(() => {
+            running--;
+            processQueue();
+        });
+    }
+    return new Promise((resolve, reject) => {
+        queue.push(async () => {
+            try {
+                const r = await fn();
+                resolve(r);
+            }
+            catch (err) {
+                reject(err);
+            }
+            finally {
+                running--;
+                processQueue();
+            }
+        });
+    });
+}
+// Expose some helpers for testing concurrency
+export function getConcurrencyState() {
+    return { running, queueLength: queue.length, maxConcurrency: MAX_CONCURRENCY };
+}
+/**
+ * Sync local changes to the Actual Budget server.
+ *
+ * This function should be called after write operations (create, update, delete)
+ * to ensure changes are properly synced to the remote server. Without syncing,
+ * changes may only exist locally and could be lost.
+ *
+ * Note: Adds a small delay to ensure local changes are committed before syncing.
+ */
+async function syncToServer() {
+    try {
+        // Small delay to ensure local changes are committed to the database
+        // before attempting to sync to the server
+        await new Promise(resolve => setTimeout(resolve, 100));
+        // TypeScript doesn't recognize sync in the type definitions, but it exists at runtime
+        console.log('[SYNC] Calling api.sync()...');
+        await api.sync();
+        console.log('[SYNC] api.sync() completed successfully');
+    }
+    catch (err) {
+        // Log but don't throw - sync failures shouldn't break the operation
+        console.error('[SYNC] Sync to server failed:', err);
+    }
+}
+export function setMaxConcurrency(n) {
+    MAX_CONCURRENCY = n;
+}
+/**
+ * Wrap a raw function with the standard adapter retry + concurrency behavior.
+ * Useful for tests that want to exercise retry behavior without calling the real raw methods.
+ */
+export function callWithRetry(fn, opts) {
+    // retry already types the options; forward them directly and let TypeScript
+    // validate shapes rather than using `as any`.
+    return withConcurrency(() => retry(fn, opts));
+}
+export const notifications = new EventEmitter();
+// --- Normalization helpers -------------------------------------------------
+export function normalizeToTransactionArray(raw) {
+    if (!raw)
+        return [];
+    // If already an array of transactions
+    if (Array.isArray(raw) && raw.every(r => typeof r === 'object'))
+        return raw;
+    // If a single transaction object, wrap it
+    if (typeof raw === 'object' && raw !== null && 'id' in raw)
+        return [raw];
+    // If array of ids returned, convert to minimal Transaction objects
+    if (Array.isArray(raw) && raw.every(r => typeof r === 'string')) {
+        return raw.map(id => ({ id }));
+    }
+    // Fallback: try to coerce
+    return Array.isArray(raw) ? raw : [];
+}
+export function normalizeToId(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (raw && typeof raw === 'object' && 'id' in raw) {
+        const idVal = raw['id'];
+        if (typeof idVal === 'string')
+            return idVal;
+    }
+    if (Array.isArray(raw) && raw.length > 0 && typeof raw[0] === 'string')
+        return raw[0];
+    return String(raw ?? '');
+}
+export function normalizeImportResult(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { added: [], updated: [], errors: [] };
+    const r = raw;
+    return {
+        added: Array.isArray(r.added) ? r.added : [],
+        updated: Array.isArray(r.updated) ? r.updated : [],
+        errors: Array.isArray(r.errors) ? r.errors : [],
+    };
+}
+// ---------------------------------------------------------------------------
+export async function getAccounts() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.accounts.list').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+    });
+}
+// addTransactions returns various formats: "ok", array of IDs, or Transaction objects
+export async function addTransactions(txs) {
+    observability.incrementToolCall('actual.transactions.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        // The Actual API expects addTransactions(accountId, transactions, options)
+        // Extract accountId from the first transaction and remove it from transaction objects
+        const txArray = Array.isArray(txs) ? txs : [txs];
+        if (txArray.length === 0) {
+            throw new Error('No transactions provided');
+        }
+        const accountId = txArray[0].account || txArray[0].accountId;
+        if (!accountId) {
+            throw new Error('Transaction must include account or accountId');
+        }
+        // Remove account/accountId from transaction objects as they're passed separately
+        const cleanedTxs = txArray.map(tx => {
+            const { account, accountId: _, ...rest } = tx;
+            return rest;
+        });
+        // API docs say it returns id[], but reality is it can return "ok", array of IDs, or Transaction objects
+        const result = await withConcurrency(() => retry(() => rawAddTransactions(accountId, cleanedTxs, {}), { retries: 2, backoffMs: 200 }));
+        // Handle various return formats
+        if (result === 'ok') {
+            // Transaction created successfully but no IDs returned
+            // We'll need to query the account to get the transaction IDs
+            return ['ok']; // Return success indicator
+        }
+        else if (Array.isArray(result)) {
+            // Could be array of IDs (strings) or array of Transaction objects
+            if (result.length === 0)
+                return [];
+            if (typeof result[0] === 'string')
+                return result;
+            if (typeof result[0] === 'object' && result[0] !== null && 'id' in result[0]) {
+                return result.map((t) => t.id);
+            }
+        }
+        else if (typeof result === 'object' && result !== null && 'id' in result) {
+            // Single Transaction object
+            return [result.id];
+        }
+        return [];
+    });
+}
+export async function importTransactions(accountId, txs) {
+    observability.incrementToolCall('actual.transactions.import').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawImportTransactions(accountId, txs), { retries: 2, backoffMs: 200 }));
+        return raw || { added: [], updated: [], errors: [] };
+    });
+}
+export async function getTransactions(accountId, startDate, endDate) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.transactions.get').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetTransactions(accountId, startDate, endDate), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function getCategories() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.categories.get').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function createCategory(category) {
+    observability.incrementToolCall('actual.categories.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        try {
+            const raw = await withConcurrency(() => retry(() => rawCreateCategory(category), { retries: 0, backoffMs: 200 }));
+            return normalizeToId(raw);
+        }
+        catch (error) {
+            logger.error('[CREATE CATEGORY] Error creating category:', error);
+            // Re-throw the error with proper context
+            if (error instanceof Error) {
+                throw error;
+            }
+            // Handle Actual APIError plain objects: { type: "APIError", message: "..." }
+            const msg = error?.message ? String(error.message) : JSON.stringify(error);
+            throw new Error(msg);
+        }
+    });
+}
+export async function getPayees() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.payees.get').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function createPayee(payee) {
+    observability.incrementToolCall('actual.payees.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreatePayee(payee), { retries: 2, backoffMs: 200 }));
+        return normalizeToId(raw);
+    });
+}
+export async function getBudgetMonths() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.budgets.getMonths').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetBudgetMonths(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function getBudgetMonth(month) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.budgets.getMonth').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetBudgetMonth(month), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function setBudgetAmount(month, categoryId, amount) {
+    observability.incrementToolCall('actual.budgets.setAmount').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Pre-flight: verify category exists — nil/unknown UUIDs silently no-op in Actual Budget
+        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const exists = categories.some((c) => c.id === categoryId);
+        if (!exists) {
+            throw new Error(`Category "${categoryId}" not found. Use actual_categories_get to list available categories.`);
+        }
+        const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200 }));
+        return result;
+    });
+}
+export async function createAccount(account, initialBalance) {
+    observability.incrementToolCall('actual.accounts.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreateAccount(account, initialBalance), { retries: 2, backoffMs: 200 }));
+        const id = normalizeToId(raw);
+        // NO NEED for syncToServer() - shutdown() will handle persistence
+        return id;
+    });
+}
+export async function updateAccount(id, fields) {
+    observability.incrementToolCall('actual.accounts.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateAccount(id, fields), { retries: 2, backoffMs: 200 }));
+        return null;
+    });
+}
+export async function getAccountBalance(id, cutoff) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.accounts.get.balance').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetAccountBalance(id, cutoff), { retries: 2, backoffMs: 200 }));
+    });
+}
+/**
+ * Fetch all accounts with their current balances in a single API session.
+ * Using a single withActualApi session avoids N separate init/shutdown cycles
+ * that would occur if you called getAccountBalance() once per account.
+ */
+export async function getAccountsWithBalances() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.accounts.list').catch(() => { });
+        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const result = [];
+        for (const account of accounts) {
+            try {
+                const balance = await rawGetAccountBalance(account.id);
+                result.push({ ...account, balance_current: balance });
+            }
+            catch {
+                result.push({ ...account, balance_current: null });
+            }
+        }
+        return result;
+    });
+}
+export async function deleteAccount(id) {
+    observability.incrementToolCall('actual.accounts.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawDeleteAccount(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function updateTransaction(id, fields) {
+    observability.incrementToolCall('actual.transactions.update').catch(() => { });
+    // Use write queue to batch concurrent updates in a single budget session
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function updateTransactionBatch(updates) {
+    observability.incrementToolCall('actual.transactions.updateBatch').catch(() => { });
+    // All updates share one queueWriteOperation → one init/sync/shutdown cycle (issue #79).
+    // Sequential loop (not Promise.all) is intentional: concurrent rawUpdateTransaction calls
+    // within one session can interleave withMutation CRDT messages unpredictably.
+    return queueWriteOperation(async () => {
+        const succeeded = [];
+        const failed = [];
+        for (const { id, fields } of updates) {
+            try {
+                await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200 }));
+                succeeded.push({ id });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                failed.push({ id, error: message });
+            }
+        }
+        return { succeeded, failed };
+    });
+}
+export async function deleteTransaction(id) {
+    observability.incrementToolCall('actual.transactions.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawDeleteTransaction(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function updateCategory(id, fields) {
+    observability.incrementToolCall('actual.categories.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateCategory(id, fields), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function deleteCategory(id) {
+    observability.incrementToolCall('actual.categories.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Pre-flight: verify category exists to avoid ECONNRESET on missing id (BUG-1)
+        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const exists = categories.some((c) => c.id === id);
+        if (!exists) {
+            throw new Error(`Category "${id}" not found. Use actual_categories_get to list available categories.`);
+        }
+        await withConcurrency(() => retry(() => rawDeleteCategory(id), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function updatePayee(id, fields) {
+    observability.incrementToolCall('actual.payees.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        const fieldsObj = fields;
+        // Extract `category` — it is NOT a direct column on the payees table in Actual Budget.
+        // The "default category" feature is implemented via rules (condition: payee is X → action: set category).
+        // Passing `category` to rawUpdatePayee would cause: "Field 'category' does not exist on table payees".
+        let categoryValue = undefined; // undefined = not provided
+        let directFields = fieldsObj;
+        if ('category' in fieldsObj) {
+            categoryValue = fieldsObj.category;
+            const { category: _stripped, ...rest } = fieldsObj;
+            directFields = rest;
+        }
+        // Update the payee's direct fields (name, transfer_acct, etc.)
+        if (Object.keys(directFields).length > 0) {
+            await withConcurrency(() => retry(() => rawUpdatePayee(id, directFields), { retries: 2, backoffMs: 200 }));
+        }
+        // Handle category via the rules mechanism (same approach Actual Budget uses internally)
+        if (categoryValue !== undefined) {
+            const existingRules = await withConcurrency(() => retry(() => rawGetPayeeRules(id), { retries: 2, backoffMs: 200 }));
+            // Find an existing "set category" action rule for this payee
+            const setCategoryRule = existingRules.find((rule) => Array.isArray(rule.actions) &&
+                rule.actions.some((a) => a.op === 'set' && a.field === 'category'));
+            if (setCategoryRule) {
+                if (categoryValue === null) {
+                    // null = clear the default category — delete the rule
+                    await withConcurrency(() => retry(() => rawDeleteRule(setCategoryRule.id), { retries: 0, backoffMs: 200 }));
+                    logger.debug(`[UPDATE PAYEE] Cleared default category rule for payee ${id}`);
+                }
+                else {
+                    // Update existing rule's category action value
+                    const updatedRule = {
+                        ...setCategoryRule,
+                        actions: setCategoryRule.actions.map((a) => a.op === 'set' && a.field === 'category' ? { ...a, value: categoryValue } : a),
+                    };
+                    await withConcurrency(() => retry(() => rawUpdateRule(updatedRule), { retries: 0, backoffMs: 200 }));
+                    logger.debug(`[UPDATE PAYEE] Updated default category rule for payee ${id} to category ${categoryValue}`);
+                }
+            }
+            else if (categoryValue !== null) {
+                // Create a new "set category" rule for this payee
+                const newRule = {
+                    stage: null,
+                    conditionsOp: 'and',
+                    conditions: [{ op: 'is', field: 'payee', value: id }],
+                    actions: [{ op: 'set', field: 'category', value: categoryValue }],
+                };
+                await withConcurrency(() => retry(() => rawCreateRule(newRule), { retries: 0, backoffMs: 200 }));
+                logger.debug(`[UPDATE PAYEE] Created default category rule for payee ${id} with category ${categoryValue}`);
+            }
+            // category=null + no existing rule = no-op (already clear)
+        }
+    });
+}
+export async function deletePayee(id) {
+    observability.incrementToolCall('actual.payees.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Pre-flight: verify payee exists to avoid ECONNRESET on missing id (BUG-2)
+        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const exists = payees.some((p) => p.id === id);
+        if (!exists) {
+            throw new Error(`Payee "${id}" not found. Use actual_payees_get to list available payees.`);
+        }
+        await withConcurrency(() => retry(() => rawDeletePayee(id), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function getRules() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.rules.get').catch(() => { });
+        const raw = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        return Array.isArray(raw) ? raw : [];
+    });
+}
+export async function createRule(rule) {
+    observability.incrementToolCall('actual.rules.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreateRule(rule), { retries: 2, backoffMs: 200 }));
+        const id = normalizeToId(raw);
+        return id;
+    });
+}
+export async function updateRule(id, fields) {
+    observability.incrementToolCall('actual.rules.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        // The Actual Budget API validation requires conditions and actions arrays to exist
+        // We must fetch the existing rule and merge with the update fields
+        const rules = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        const existingRule = rules.find((r) => r.id === id);
+        if (!existingRule) {
+            throw new Error(`Rule with id ${id} not found`);
+        }
+        const fieldsObj = fields;
+        const rule = {
+            id,
+            stage: fieldsObj.stage ?? existingRule.stage,
+            conditionsOp: fieldsObj.conditionsOp ?? existingRule.conditionsOp,
+            conditions: fieldsObj.conditions ?? existingRule.conditions ?? [],
+            actions: fieldsObj.actions ?? existingRule.actions ?? [],
+        };
+        logger.debug(`[UPDATE RULE] Updating rule ${id} with merged fields: ${JSON.stringify(rule)}`);
+        await withConcurrency(() => retry(() => rawUpdateRule(rule), { retries: 0, backoffMs: 200 }));
+        logger.debug(`[UPDATE RULE] Update completed for rule ${id}`);
+    });
+}
+export async function deleteRule(id) {
+    observability.incrementToolCall('actual.rules.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function getSchedules() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.schedules.get').catch(() => { });
+        const raw = await withConcurrency(() => retry(() => rawGetSchedules(), { retries: 2, backoffMs: 200 }));
+        return Array.isArray(raw) ? raw : [];
+    });
+}
+export async function createSchedule(schedule) {
+    observability.incrementToolCall('actual.schedules.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Note: rawCreateSchedule(schedule) passes the external schedule object directly.
+        // Do NOT wrap in { schedule: ... } — that would double-nest and break date parsing.
+        const raw = await withConcurrency(() => retry(() => rawCreateSchedule(schedule), { retries: 0, backoffMs: 200 }));
+        const id = normalizeToId(raw);
+        return id;
+    });
+}
+export async function updateSchedule(id, fields, resetNextDate) {
+    observability.incrementToolCall('actual.schedules.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateSchedule(id, fields, resetNextDate), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function deleteSchedule(id) {
+    observability.incrementToolCall('actual.schedules.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawDeleteSchedule(id), { retries: 0, backoffMs: 200 }));
+    });
+}
+export async function setBudgetCarryover(month, categoryId, flag) {
+    observability.incrementToolCall('actual.budgets.setCarryover').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawSetBudgetCarryover(month, categoryId, flag), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function closeAccount(id) {
+    observability.incrementToolCall('actual.accounts.close').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawCloseAccount(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function reopenAccount(id) {
+    observability.incrementToolCall('actual.accounts.reopen').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawReopenAccount(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function getCategoryGroups() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.category_groups.get').catch(() => { });
+        const raw = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        return Array.isArray(raw) ? raw : [];
+    });
+}
+export async function createCategoryGroup(group) {
+    observability.incrementToolCall('actual.category_groups.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreateCategoryGroup(group), { retries: 2, backoffMs: 200 }));
+        const id = normalizeToId(raw);
+        return id;
+    });
+}
+export async function updateCategoryGroup(id, fields) {
+    observability.incrementToolCall('actual.category_groups.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawUpdateCategoryGroup(id, fields), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function deleteCategoryGroup(id) {
+    observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function mergePayees(targetId, mergeIds) {
+    observability.incrementToolCall('actual.payees.merge').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawMergePayees(targetId, mergeIds), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function getPayeeRules(payeeId) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.payees.getPayeeRules').catch(() => { });
+        const allRules = await withConcurrency(() => retry(() => rawGetPayeeRules(payeeId), { retries: 2, backoffMs: 200 }));
+        if (!Array.isArray(allRules))
+            return [];
+        // API ignores payeeId filter — apply post-filter (BUG-3)
+        return allRules.filter((r) => r?.payee_id === payeeId);
+    });
+}
+export async function batchBudgetUpdates(fn) {
+    observability.incrementToolCall('actual.budgets.batchUpdates').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawBatchBudgetUpdates(fn), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function holdBudgetForNextMonth(month, amount) {
+    observability.incrementToolCall('actual.budgets.holdForNextMonth').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawHoldBudgetForNextMonth(month, amount), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function resetBudgetHold(month) {
+    observability.incrementToolCall('actual.budgets.resetHold').catch(() => { });
+    return queueWriteOperation(async () => {
+        await withConcurrency(() => retry(() => rawResetBudgetHold(month), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function runQuery(queryString) {
+    try {
+        return await withActualApi(async () => {
+            observability.incrementToolCall('actual.query.run').catch(() => { });
+            try {
+                // Import validation utilities
+                const { validateQuery, formatValidationErrors } = await import('./query-validator.js');
+                // The Actual Budget runQuery expects an ActualQL query object with serialize() method
+                // Import the q builder dynamically
+                const api = await import('@actual-app/api');
+                const q = api.q;
+                if (!q) {
+                    throw new Error('ActualQL query builder not available. Ensure @actual-app/api is properly installed and the budget is loaded.');
+                }
+                // If already a serialized query object, use it directly
+                if (typeof queryString === 'object' && queryString !== null) {
+                    try {
+                        return await withConcurrency(async () => {
+                            try {
+                                return await rawRunQuery(queryString);
+                            }
+                            catch (err) {
+                                // Catch errors from the query execution to prevent unhandled rejections
+                                const msg = err?.message || String(err);
+                                logger.error(`[ADAPTER] Query execution error: ${msg}`);
+                                if (msg.includes('does not exist in table') || msg.includes('Field') || msg.includes('does not exist')) {
+                                    throw new Error(`Invalid field in query: ${msg}`);
+                                }
+                                throw err;
+                            }
+                        });
+                    }
+                    catch (error) {
+                        throw new Error(`Query execution failed: ${error.message}`);
+                    }
+                }
+                const trimmed = queryString.trim();
+                let query;
+                // Check for GraphQL-like query syntax: query Name { table(...) { fields } }
+                const graphqlMatch = trimmed.match(/^query\s+\w+\s*\{\s*(\w+)\s*\(([^)]*)\)\s*\{([^}]+)\}\s*\}$/is);
+                if (graphqlMatch) {
+                    const [, tableName, argsStr, fieldsStr] = graphqlMatch;
+                    query = q(tableName);
+                    // Parse arguments (e.g., startDate: "2025-06-01", endDate: "2025-11-30")
+                    if (argsStr.trim()) {
+                        const args = argsStr.split(',').map((a) => a.trim());
+                        for (const arg of args) {
+                            const argMatch = arg.match(/^(\w+):\s*"([^"]+)"$/);
+                            if (argMatch) {
+                                const [, key, value] = argMatch;
+                                // Map GraphQL args to ActualQL filters
+                                if (key === 'startDate') {
+                                    query = query.filter({ date: { $gte: value } });
+                                }
+                                else if (key === 'endDate') {
+                                    query = query.filter({ date: { $lte: value } });
+                                }
+                                else {
+                                    // Generic filter for other args
+                                    query = query.filter({ [key]: value });
+                                }
+                            }
+                        }
+                    }
+                    // Parse fields (including nested objects like account { id name })
+                    const fieldNames = [];
+                    const nestedFieldPattern = /(\w+)\s*\{[^}]+\}/g;
+                    const simpleFields = fieldsStr.replace(nestedFieldPattern, '').split(/\s+/).filter((f) => f.trim());
+                    fieldNames.push(...simpleFields.map((f) => f.trim()));
+                    // Extract nested field names (e.g., account, payee, category)
+                    let nestedMatch;
+                    while ((nestedMatch = nestedFieldPattern.exec(fieldsStr)) !== null) {
+                        fieldNames.push(nestedMatch[1]);
+                    }
+                    if (fieldNames.length > 0) {
+                        query = query.select(fieldNames);
+                    }
+                }
+                else {
+                    // Enhanced SQL-like parsing supporting WHERE, ORDER BY, and LIMIT
+                    // Pattern: SELECT [fields] FROM table [WHERE conditions] [ORDER BY field ASC|DESC] [LIMIT n]
+                    const sqlMatch = trimmed.match(/^SELECT\s+(.+?)\s+FROM\s+(\w+)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(\w+)(?:\s+(ASC|DESC))?)?(?:\s+LIMIT\s+(\d+))?$/is);
+                    if (sqlMatch) {
+                        const [, fields, tableName, whereClause, orderField, orderDir, limitStr] = sqlMatch;
+                        // ✅ VALIDATE QUERY BEFORE EXECUTION
+                        const validation = validateQuery(trimmed);
+                        if (!validation.valid) {
+                            const errorMsg = formatValidationErrors(validation);
+                            throw new Error(`Invalid SQL query:\n${errorMsg}\n\nQuery: "${trimmed}"`);
+                        }
+                        query = q(tableName);
+                        // Apply SELECT fields (if not *)
+                        if (fields.trim() !== '*') {
+                            // Strip SQL aliases (AS alias_name) since ActualQL doesn't support them
+                            const fieldList = fields.split(',').map((f) => {
+                                const field = f.trim();
+                                // Remove "AS alias" part if present (case-insensitive)
+                                return field.replace(/\s+AS\s+\w+$/i, '').trim();
+                            });
+                            query = query.select(fieldList);
+                        }
+                        // Apply WHERE conditions
+                        if (whereClause) {
+                            query = parseWhereClause(query, whereClause);
+                        }
+                        // Apply ORDER BY
+                        if (orderField) {
+                            query = query.orderBy({ [orderField]: orderDir?.toUpperCase() === 'DESC' ? 'desc' : 'asc' });
+                        }
+                        // Apply LIMIT
+                        if (limitStr) {
+                            query = query.limit(parseInt(limitStr));
+                        }
+                    }
+                    else {
+                        // Assume it's just a table name
+                        query = q(trimmed);
+                    }
+                }
+                try {
+                    return await withConcurrency(async () => {
+                        try {
+                            return await rawRunQuery(query);
+                        }
+                        catch (err) {
+                            // Catch errors from the query execution to prevent unhandled rejections
+                            const msg = err?.message || String(err);
+                            logger.error(`[ADAPTER] Query execution error: ${msg}`);
+                            if (msg.includes('does not exist in table') || msg.includes('Field') || msg.includes('does not exist')) {
+                                throw new Error(`Invalid field in query: ${msg}`);
+                            }
+                            throw err;
+                        }
+                    });
+                }
+                catch (error) {
+                    // Enhance error messages with helpful context
+                    const errorMsg = error?.message || String(error);
+                    // If the error already contains formatted validation errors (with suggestions), preserve them
+                    if (errorMsg.includes('Invalid SQL query:') && (errorMsg.includes('Available fields:') || errorMsg.includes('Available tables:'))) {
+                        throw error; // Re-throw the well-formatted validation error as-is
+                    }
+                    if (errorMsg.includes('does not exist in the schema') || errorMsg.includes('Invalid field in query') || errorMsg.includes('does not exist in table')) {
+                        throw new Error(`Table or field does not exist. Query: "${trimmed}". Available tables: transactions, accounts, categories, payees, category_groups, schedules, rules. Use dot notation for joins (e.g., payee.name, category.name). Original error: ${errorMsg}`);
+                    }
+                    // Re-throw with original error if no specific handling
+                    throw error;
+                }
+            }
+            catch (error) {
+                // Outer catch for query parsing errors
+                const errorMsg = error?.message || String(error);
+                if (errorMsg.includes('tableName') || errorMsg.includes('expandStar') || errorMsg.includes('Cannot read properties of undefined')) {
+                    throw new Error(`SQL query parsing failed. The Actual Budget query engine has limitations with complex SQL features like COUNT(*), SUM(), GROUP BY, and aggregate functions. Try using simpler queries or ActualQL format instead. See https://actualbudget.org/docs/api/actual-ql/ for supported syntax. Error: ${errorMsg}`);
+                }
+                throw error;
+            }
+        });
+    }
+    catch (error) {
+        // Top-level catch to ensure no unhandled rejections escape
+        const errorMsg = error?.message || String(error);
+        logger.error(`[ADAPTER] Query execution failed: ${errorMsg}`);
+        // If the error already contains formatted validation errors with suggestions, preserve them
+        if (errorMsg.includes('Invalid SQL query:') && (errorMsg.includes('Available fields:') || errorMsg.includes('Available tables:'))) {
+            throw error; // Re-throw the well-formatted validation error without wrapping
+        }
+        throw new Error(`Query execution failed: ${errorMsg}`);
+    }
+}
+// Helper function to parse WHERE clause conditions.
+// Exported so it can be unit-tested directly.
+export function parseWhereClause(query, whereClause) {
+    // Split by AND (simple parser - doesn't handle OR or nested conditions)
+    const conditions = whereClause.split(/\s+AND\s+/i);
+    for (const condition of conditions) {
+        const trimmedCondition = condition.trim();
+        // Handle IN clause: field IN (value1, value2, ...)
+        // [\w.]+ matches both simple fields (amount) and joined fields (category.name)
+        const inMatch = trimmedCondition.match(/^([\w.]+)\s+IN\s+\((.+)\)$/i);
+        if (inMatch) {
+            const [, field, valuesStr] = inMatch;
+            const values = valuesStr.split(',').map(v => {
+                const trimmed = v.trim().replace(/^['"]|['"]$/g, '');
+                // Try to parse as number, otherwise keep as string
+                const num = Number(trimmed);
+                return isNaN(num) ? trimmed : num;
+            });
+            query = query.filter({ [field]: { $oneof: values } });
+            continue;
+        }
+        // Handle comparison operators: field >= value, field <= value, field = value, etc.
+        // [\w.]+ matches both simple fields (amount) and joined fields (category.name, payee.name)
+        const compMatch = trimmedCondition.match(/^([\w.]+)\s*(>=|<=|>|<|=|!=)\s*(.+)$/);
+        if (compMatch) {
+            const [, field, operator, valueStr] = compMatch;
+            const value = valueStr.trim().replace(/^['"]|['"]$/g, '');
+            // Map SQL operators to ActualQL operators
+            const operatorMap = {
+                '>=': '$gte',
+                '<=': '$lte',
+                '>': '$gt',
+                '<': '$lt',
+                '=': '$eq',
+                '!=': '$ne',
+            };
+            const actualOp = operatorMap[operator];
+            if (actualOp) {
+                // Try to parse as number if possible
+                const numValue = Number(value);
+                const finalValue = isNaN(numValue) ? value : numValue;
+                if (actualOp === '$eq') {
+                    // Simple equality can use direct field: value
+                    query = query.filter({ [field]: finalValue });
+                }
+                else {
+                    query = query.filter({ [field]: { [actualOp]: finalValue } });
+                }
+            }
+        }
+    }
+    return query;
+}
+export async function runBankSync(accountId) {
+    try {
+        return await withActualApi(async () => {
+            observability.incrementToolCall('actual.bank.sync').catch(() => { });
+            // Bank sync must NOT be retried — retrying could import duplicate transactions.
+            // Pass { accountId } for a specific account, or {} to sync all linked accounts.
+            const args = accountId != null ? { accountId } : {};
+            // Pre-check: verify bank-linked accounts exist before calling rawRunBankSync.
+            // The SDK silently resolves void for local accounts (account_sync_source: null),
+            // which would otherwise be misreported as success and cause an unnecessary 30s wait.
+            if (accountId != null) {
+                // Per-account check: verify the specified account is bank-linked.
+                const { data: acctRows } = await rawRunQuery(api.q('accounts')
+                    .select(['account_sync_source', 'name'])
+                    .filter({ id: accountId, tombstone: false }));
+                const acct = acctRows?.[0];
+                if (!acct) {
+                    throw new Error(`Bank sync failed: Account not found (id: ${accountId})`);
+                }
+                if (!acct.account_sync_source) {
+                    throw new Error(`Bank sync failed: Account "${acct.name}" is a local account — not configured for bank sync. ` +
+                        `To use bank sync, link your account with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
+                        `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
+                }
+            }
+            else {
+                // Global check: verify at least one bank-linked account exists across the budget.
+                const { data: allAccounts } = await rawRunQuery(api.q('accounts')
+                    .select(['account_sync_source'])
+                    .filter({ tombstone: false }));
+                const linkedCount = allAccounts?.filter(a => a.account_sync_source).length ?? 0;
+                if (linkedCount === 0) {
+                    throw new Error(`Bank sync failed: No accounts are configured for bank sync. ` +
+                        `To use bank sync, link your account(s) with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
+                        `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
+                }
+            }
+            // rawRunBankSync returns void immediately; the actual provider call runs on
+            // a background promise inside the SDK and surfaces errors as unhandledRejection.
+            // We install a temporary listener to capture any BankSyncError and re-throw.
+            let capturedRejection = null;
+            const rejectionHandler = (reason) => {
+                const msg = reason?.message || String(reason);
+                if (reason?.type === 'BankSyncError' ||
+                    msg.includes('BankSyncError') ||
+                    msg.includes('NORDIGEN_ERROR') ||
+                    msg.includes('Rate limit exceeded') ||
+                    msg.includes('Failed syncing account') ||
+                    msg.includes('GoCardless') ||
+                    msg.includes('SimpleFIN')) {
+                    capturedRejection = reason;
+                }
+            };
+            process.on('unhandledRejection', rejectionHandler);
+            try {
+                await rawRunBankSync(args);
+                // Wait for the SDK's background promise to resolve/reject.
+                // Provider errors (rate limits, auth failures) arrive in < 3s in practice;
+                // BANK_SYNC_SETTLE_MS gives a comfortable margin to catch them.
+                await new Promise(resolve => setTimeout(resolve, BANK_SYNC_SETTLE_MS));
+                if (capturedRejection !== null)
+                    throw capturedRejection;
+            }
+            finally {
+                process.off('unhandledRejection', rejectionHandler);
+            }
+        });
+    }
+    catch (error) {
+        const errorMsg = error?.message || String(error);
+        // Network / connectivity errors (includes "fetch failed" from Node.js native fetch)
+        if (errorMsg.includes('fetch failed') ||
+            errorMsg.includes('network-failure') ||
+            errorMsg.includes('ECONNREFUSED') ||
+            errorMsg.includes('ENOTFOUND') ||
+            errorMsg.includes('Authentication failed')) {
+            throw new Error(`Bank sync failed: Cannot connect to Actual Budget server. ` +
+                `Check that ACTUAL_SERVER_URL is reachable from the MCP server container. (${errorMsg})`);
+        }
+        // Account not configured for bank sync
+        if (errorMsg.includes('No bank account') ||
+            errorMsg.includes('not configured') ||
+            errorMsg.includes('not linked') ||
+            !errorMsg ||
+            errorMsg === '{}') {
+            throw new Error(`Bank sync failed: The ${accountId ? 'specified account is' : 'accounts are'} not configured for bank sync. ` +
+                `To use bank sync, you must first link your account(s) with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
+                `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
+        }
+        // GoCardless / SimpleFIN provider-level errors
+        // BankSyncError objects (from @actual-app/api) may have { type, category, code, message }
+        const bankSyncCategory = error?.category || '';
+        if (errorMsg.includes('Rate limit exceeded') ||
+            errorMsg.includes('RATE_LIMIT_EXCEEDED') ||
+            bankSyncCategory === 'RATE_LIMIT_EXCEEDED') {
+            const reset = error?.details?.rateLimitHeaders?.http_x_ratelimit_account_success_reset;
+            const retryIn = reset ? ` Retry in ~${Math.ceil(Number(reset) / 60)} minute(s).` : '';
+            throw new Error(`Bank sync failed: GoCardless rate limit exceeded for this account.${retryIn} ` +
+                `(NORDIGEN RATE_LIMIT_EXCEEDED — account success quota exhausted)`);
+        }
+        if (error?.type === 'BankSyncError' ||
+            errorMsg.includes('BankSyncError') ||
+            errorMsg.includes('NORDIGEN_ERROR') ||
+            errorMsg.includes('Failed syncing account')) {
+            throw new Error(`Bank sync failed: Provider error — ${errorMsg}`);
+        }
+        throw new Error(`Bank sync failed: ${errorMsg}`);
+    }
+}
+export async function getBudgets() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.budgets.getAll').catch(() => { });
+        const raw = await withConcurrency(() => retry(() => rawGetBudgets(), { retries: 2, backoffMs: 200 }));
+        return Array.isArray(raw) ? raw : [];
+    });
+}
+/**
+ * Switch the active budget by name (case-insensitive, partial match supported).
+ * The budget must be pre-configured via BUDGET_n_NAME env vars.
+ * Switching is instant — no API call required; the next withActualApi
+ * call will automatically connect to the new budget's server and sync ID.
+ */
+export function switchBudget(name) {
+    const key = name.toLowerCase();
+    let found = budgetRegistry.get(key);
+    let foundKey = key;
+    if (!found) {
+        // Partial / substring match
+        for (const [k, v] of budgetRegistry) {
+            if (k.includes(key) || key.includes(k)) {
+                found = v;
+                foundKey = k;
+                break;
+            }
+        }
+    }
+    if (!found) {
+        const available = [...budgetRegistry.values()].map(b => `"${b.name}"`).join(', ');
+        throw new Error(`Budget "${name}" not found in configuration. ` +
+            `Available budgets: ${available}. ` +
+            `Add BUDGET_n_NAME/SYNC_ID/SERVER_URL vars to configure additional budgets.`);
+    }
+    activeBudgetKey = foundKey;
+    logger.info(`[ADAPTER] Active budget switched to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
+    return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+}
+/**
+ * Return all configured budgets from the registry (for listing in actual_budgets_list_available).
+ */
+export function getBudgetRegistry() {
+    return [...budgetRegistry.values()].map(b => ({
+        name: b.name,
+        syncId: b.syncId,
+        serverUrl: b.serverUrl,
+        hasEncryption: !!b.encryptionPassword,
+    }));
+}
+/**
+ * Get the UUID for any Account, Payee, Category or Schedule by name.
+ * Allowed types: 'accounts', 'schedules', 'categories', 'payees'
+ */
+export async function getIDByName(type, name) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.getIDByName').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetIDByName(type, name), { retries: 2, backoffMs: 200 }));
+    });
+}
+/**
+ * Get the current Actual Budget server version.
+ * Returns { version: string } on success, { error: string } on failure.
+ */
+export async function getServerVersion() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.getServerVersion').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetServerVersion(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export default {
+    getAccounts,
+    getAccountsWithBalances,
+    addTransactions,
+    importTransactions,
+    getTransactions,
+    getCategories,
+    createCategory,
+    getPayees,
+    createPayee,
+    getBudgetMonths,
+    getBudgetMonth,
+    setBudgetAmount,
+    createAccount,
+    updateAccount,
+    getAccountBalance,
+    deleteAccount,
+    updateTransaction,
+    deleteTransaction,
+    updateCategory,
+    deleteCategory,
+    updatePayee,
+    deletePayee,
+    getRules,
+    createRule,
+    updateRule,
+    deleteRule,
+    setBudgetCarryover,
+    closeAccount,
+    reopenAccount,
+    getCategoryGroups,
+    createCategoryGroup,
+    updateCategoryGroup,
+    deleteCategoryGroup,
+    mergePayees,
+    getPayeeRules,
+    batchBudgetUpdates,
+    holdBudgetForNextMonth,
+    resetBudgetHold,
+    runQuery,
+    runBankSync,
+    getBudgets,
+    switchBudget,
+    getBudgetRegistry,
+    getIDByName,
+    getServerVersion,
+    getSchedules,
+    createSchedule,
+    updateSchedule,
+    deleteSchedule,
+    updateTransactionBatch,
+    notifications,
+};