actual-mcp-server 0.6.27 → 0.6.29

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.27 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.29 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.27",
+    "version": "0.6.29",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
         "verify-tools": "npm run build && node scripts/verify-tools.js",
         "check:coverage": "node scripts/list-actual-api-methods.mjs",
         "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
+        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
         "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
         "test:e2e": "npx playwright test",
         "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",

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

@@ -0,0 +1,80 @@
+// Auth-rate-limit retry subsystem for the Actual adapter (#166 split out of
+// actual-adapter.ts). Self-contained: the two observability counters are
+// mutated ONLY here (withAuthRetry / the reset), so the mutable state never
+// crosses a module boundary. actual-adapter reads the counts via
+// getAuthRetryCounts() for getConcurrencyState, and wraps api.init() with
+// withAuthRetry. Linked issue: #127.
+import { DEFAULT_RETRY_ATTEMPTS, MAX_RETRY_DELAY_MS } from '../constants.js';
+import logger from '../../logger.js';
+let authRetryCount = 0; // monotonic, observability
+let authRetryFailureCount = 0; // increments only when retry budget exhausted
+// The auth-rate-limit path uses a deliberately LARGER backoff than the generic
+// retry helper because Actual Budget's auth rate-limiter operates on a multi-
+// second sliding window, not a per-request burst. The generic 200ms base
+// would exhaust within 1.4s, well inside the upstream's window.
+//
+// Empirically (2026-05-06, #127):
+//   - 200ms base = 1.4s total: too short, every retry hits the throttle.
+//   - 2000ms base = 14s total: insufficient under heavy auth pressure.
+//   - 5000ms base = 5s + 10s + 10s = 25s total (each step capped by
+//     MAX_RETRY_DELAY_MS): clears the window in light-pressure scenarios.
+//
+// Beyond 25s, blocking the API mutex starts to harm tail latency for unrelated
+// tool calls. The long-term fix for sustained pressure is session reuse.
+const AUTH_RETRY_BASE_BACKOFF_MS = 5000;
+export function isRetryableAuthError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.message.includes('Authentication failed: too-many-requests') ||
+        err.message.includes('Authentication failed: network-failure'));
+}
+/**
+ * Wrap an operation with retry-on-rate-limit. Used to wrap api.init() so
+ * transient too-many-requests errors are absorbed transparently. The retry
+ * budget is capped at DEFAULT_RETRY_ATTEMPTS (3) attempts and total wallclock
+ * is bounded by MAX_RETRY_DELAY_MS via exponential backoff.
+ *
+ * Test-friendly: opts.maxRetries / opts.baseBackoffMs override the defaults
+ * so unit tests can run fast.
+ *
+ * Log hygiene: never logs the upstream URL, password, or any config-derived
+ * value, only the error class and the Actual error code plus the attempt counter.
+ */
+export async function withAuthRetry(operation, opts) {
+    const maxRetries = opts?.maxRetries ?? DEFAULT_RETRY_ATTEMPTS;
+    const baseBackoffMs = opts?.baseBackoffMs ?? AUTH_RETRY_BASE_BACKOFF_MS;
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (err) {
+            if (!isRetryableAuthError(err))
+                throw err;
+            attempt++;
+            if (attempt > maxRetries) {
+                // Budget exhausted: log + bump failure counter, but do NOT bump
+                // authRetryCount, which measures successful retry-and-sleep cycles.
+                authRetryFailureCount++;
+                const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
+                logger.error(`[ADAPTER] Auth retry exhausted after ${maxRetries} retries (last code: ${code})`);
+                throw err;
+            }
+            // We're going to retry: count it and sleep with exponential backoff.
+            authRetryCount++;
+            const delay = Math.min(baseBackoffMs * Math.pow(2, attempt - 1), MAX_RETRY_DELAY_MS);
+            const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
+            logger.debug(`[ADAPTER] Auth retry ${attempt}/${maxRetries} (code: ${code}) after ${delay}ms`);
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+}
+/** Read-only snapshot of the auth-retry counters for getConcurrencyState. */
+export function getAuthRetryCounts() {
+    return { authRetries: authRetryCount, authRetryFailures: authRetryFailureCount };
+}
+/** Test-only: reset the auth retry observability counters. */
+export function _resetAuthRetryCountersForTests() {
+    authRetryCount = 0;
+    authRetryFailureCount = 0;
+}

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

@@ -0,0 +1,56 @@
+// In-memory concurrency limiter for adapter calls (#166 split out of
+// actual-adapter.ts). Self-contained: MAX_CONCURRENCY / running / queue are
+// mutated ONLY by the functions here, so the mutable state never crosses a
+// module boundary. It prevents bursts from overloading the Actual server.
+// Intentionally tiny; replace with Bottleneck or p-queue for production.
+import { DEFAULT_CONCURRENCY_LIMIT } from '../constants.js';
+let MAX_CONCURRENCY = parseInt(process.env.ACTUAL_API_CONCURRENCY || String(DEFAULT_CONCURRENCY_LIMIT), 10);
+let running = 0;
+const queue = [];
+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();
+    }
+}
+export 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();
+            }
+        });
+    });
+}
+export function setMaxConcurrency(n) {
+    MAX_CONCURRENCY = n;
+}
+/** Read-only snapshot of the limiter state for getConcurrencyState. */
+export function getConcurrencySnapshot() {
+    return { running, queueLength: queue.length, maxConcurrency: MAX_CONCURRENCY };
+}

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

@@ -0,0 +1,43 @@
+// Pure response-normalisation helpers for the Actual adapter (#166 split out of
+// actual-adapter.ts). No module state, no side effects: they only coerce the
+// varied raw shapes the @actual-app/api returns (id string, id array, object,
+// array of objects) into the canonical shapes the tools expect. Re-exported
+// from actual-adapter.ts so the public surface and all importers are unchanged.
+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 : [],
+    };
+}

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

@@ -0,0 +1,107 @@
+// SQL-to-ActualQL WHERE translation for actual_query_run (#166 split out of
+// actual-adapter.ts). Pure: it only transforms a query builder via .filter()
+// calls and string parsing, with no module state or side effects. parseWhereClause
+// is re-exported from actual-adapter.ts and is unit-tested directly. The #178
+// operator support (LIKE / NOT LIKE / IS NULL, throw-on-unsupported) lives here.
+// Strip a single pair of surrounding quotes from a SQL value literal.
+function _stripWhereQuotes(s) {
+    return s.trim().replace(/^['"]|['"]$/g, '');
+}
+// Coerce a SQL value literal to a number when it looks numeric, else keep the
+// (unquoted) string. Used for IN lists and comparison operands. Empty stays a
+// string so an empty literal is not silently turned into 0.
+function _coerceWhereValue(s) {
+    const v = _stripWhereQuotes(s);
+    if (v === '')
+        return v;
+    const n = Number(v);
+    return isNaN(n) ? v : n;
+}
+export function parseWhereClause(query, whereClause) {
+    // OR is not supported. Detect it up front and fail loudly. Without this guard
+    // a clause like `amount = 100 OR amount < 0` is left as a single fragment by
+    // the AND-splitter, and the comparison regex's greedy value capture swallows
+    // `100 OR amount < 0` into the operand, running a silently-wrong filter rather
+    // than erroring. That silent mishandling is exactly what #178 set out to stop.
+    // This shares the AND-splitter's quote-naive simplicity: an " OR " inside a
+    // quoted value is a known limitation, the same as " AND ".
+    if (/\sOR\s/i.test(whereClause)) {
+        throw new Error(`Unsupported WHERE condition: OR is not supported. ` +
+            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
+            `Combine conditions with AND only.`);
+    }
+    // Split by AND. This is a simple parser: it does not handle OR or nested /
+    // parenthesised conditions (see the unsupported-operator throw below).
+    const conditions = whereClause.split(/\s+AND\s+/i);
+    for (const condition of conditions) {
+        const trimmedCondition = condition.trim();
+        if (!trimmedCondition)
+            continue;
+        // IS NULL / IS NOT NULL: lets callers find unmerged rows (e.g. imported_payee
+        // IS NULL). ActualQL treats `field: null` as IS NULL and `$ne: null` as IS NOT NULL.
+        const nullMatch = trimmedCondition.match(/^([\w.]+)\s+IS\s+(NOT\s+)?NULL$/i);
+        if (nullMatch) {
+            const [, field, not] = nullMatch;
+            query = not
+                ? query.filter({ [field]: { $ne: null } })
+                : query.filter({ [field]: null });
+            continue;
+        }
+        // NOT LIKE (checked before LIKE so the longer keyword wins).
+        const notLikeMatch = trimmedCondition.match(/^([\w.]+)\s+NOT\s+LIKE\s+(.+)$/i);
+        if (notLikeMatch) {
+            const [, field, valueStr] = notLikeMatch;
+            query = query.filter({ [field]: { $notlike: _stripWhereQuotes(valueStr) } });
+            continue;
+        }
+        // LIKE: pattern match. ActualQL's $like runs through NORMALISE + UNICODE_LIKE,
+        // so it is case-insensitive and accent-insensitive. Use % as the wildcard,
+        // e.g. imported_payee LIKE '%amazon%'.
+        const likeMatch = trimmedCondition.match(/^([\w.]+)\s+LIKE\s+(.+)$/i);
+        if (likeMatch) {
+            const [, field, valueStr] = likeMatch;
+            query = query.filter({ [field]: { $like: _stripWhereQuotes(valueStr) } });
+            continue;
+        }
+        // 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(_coerceWhereValue);
+            query = query.filter({ [field]: { $oneof: values } });
+            continue;
+        }
+        // Comparison operators: 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 operatorMap = {
+                '>=': '$gte',
+                '<=': '$lte',
+                '>': '$gt',
+                '<': '$lt',
+                '=': '$eq',
+                '!=': '$ne',
+            };
+            const actualOp = operatorMap[operator];
+            const finalValue = _coerceWhereValue(valueStr);
+            if (actualOp === '$eq') {
+                // Simple equality can use the direct field: value shorthand.
+                query = query.filter({ [field]: finalValue });
+            }
+            else {
+                query = query.filter({ [field]: { [actualOp]: finalValue } });
+            }
+            continue;
+        }
+        // Nothing matched. Refuse to silently drop the condition: dropping it would
+        // run the query UNFILTERED and hand back misleading "matches everything"
+        // results. Fail loudly with an actionable error instead. See #178.
+        throw new Error(`Unsupported WHERE condition: "${trimmedCondition}". ` +
+            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
+            `OR, REGEXP, NOT IN, and parenthesised groups are not yet supported.`);
+    }
+    return query;
+}

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

@@ -11,7 +11,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
-import retry from './retry.js';
+import retry, { isRetryableError } from './retry.js';
 import logger from '../logger.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
@@ -130,17 +130,13 @@ function _hasPooledConnection(sessionId) {
  * actually corrupted but the error pattern doesn't match, the next call's op
  * will surface the same root cause and we'll catch it then.
  */
+// Whether an error is infrastructure-level (drop the pooled connection so the
+// next call re-inits cleanly). This is the SAME class as "retryable", so it
+// delegates to isRetryableError (#177): the pool-drop decision and the retry
+// decision share one pattern list and cannot drift. A consistency test pins
+// this equivalence.
 function _shouldDropPoolOnError(err) {
-    if (!(err instanceof Error))
-        return false;
-    const msg = err.message || '';
-    return (msg.includes('Authentication failed') ||
-        msg.includes('ECONNRESET') ||
-        msg.includes('ECONNREFUSED') ||
-        msg.includes('socket hang up') ||
-        msg.includes('ETIMEDOUT') ||
-        msg.includes('out of memory') ||
-        msg.includes('ENOMEM'));
+    return isRetryableError(err);
 }
 /**
  * Enforce per-request budget ACL before any pool branching or lock acquisition.
@@ -377,84 +373,11 @@ export function _setSkipApiInitForTests(value) {
 // The retry budget is bounded so a rate-limited init cannot indefinitely
 // hold the API mutex (withApiLock) and starve other operations.
 // ----------------------------------------------------------------------------
-let authRetryCount = 0; // monotonic, observability
-let authRetryFailureCount = 0; // increments only when retry budget exhausted
-// The auth-rate-limit path uses a deliberately LARGER backoff than the generic
-// retry helper because Actual Budget's auth rate-limiter operates on a multi-
-// second sliding window, not a per-request burst. The generic 200ms base
-// would exhaust within 1.4s — well inside the upstream's window.
-//
-// Empirically (2026-05-06, #127):
-//   - 200ms base = 1.4s total: too short, every retry hits the throttle.
-//   - 2000ms base = 14s total: insufficient under heavy auth pressure
-//     (e.g. 10 rapid logins before a tool call still throttle 14s+).
-//   - 5000ms base = 5s + 10s + 10s = 25s total (each step capped by
-//     MAX_RETRY_DELAY_MS): clears the rate-limit window in light-pressure
-//     scenarios (3 rapid logins) without holding the API mutex unreasonably
-//     long.
-//
-// Beyond 25s, blocking the API mutex starts to harm tail latency for
-// unrelated tool calls. The proper long-term fix for sustained-pressure
-// scenarios is session reuse (avoid init+shutdown per op) — out of scope for
-// this ticket; tracked as a follow-up.
-const AUTH_RETRY_BASE_BACKOFF_MS = 5000;
-export function isRetryableAuthError(err) {
-    if (!(err instanceof Error))
-        return false;
-    return (err.message.includes('Authentication failed: too-many-requests') ||
-        err.message.includes('Authentication failed: network-failure'));
-}
-/**
- * Wrap an operation with retry-on-rate-limit. Used to wrap api.init() so
- * transient too-many-requests errors are absorbed transparently. The retry
- * budget is capped at DEFAULT_RETRY_ATTEMPTS (3) attempts and total wallclock
- * is bounded by MAX_RETRY_DELAY_MS via exponential backoff.
- *
- * Test-friendly: opts.maxRetries / opts.baseBackoffMs override the defaults
- * so unit tests can run fast.
- *
- * Log hygiene: this function never logs the upstream URL, password, or any
- * config-derived value — only the error class and the Actual error code
- * (extracted from the message) plus the attempt counter.
- */
-export async function withAuthRetry(operation, opts) {
-    const maxRetries = opts?.maxRetries ?? DEFAULT_RETRY_ATTEMPTS;
-    const baseBackoffMs = opts?.baseBackoffMs ?? AUTH_RETRY_BASE_BACKOFF_MS;
-    let attempt = 0;
-    while (true) {
-        try {
-            return await operation();
-        }
-        catch (err) {
-            if (!isRetryableAuthError(err))
-                throw err;
-            attempt++;
-            if (attempt > maxRetries) {
-                // Budget exhausted: log + bump failure counter, but do NOT bump
-                // authRetryCount — that counter measures successful retry-and-sleep
-                // cycles, not failed final attempts.
-                authRetryFailureCount++;
-                const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
-                logger.error(`[ADAPTER] Auth retry exhausted after ${maxRetries} retries (last code: ${code})`);
-                throw err;
-            }
-            // We're going to retry — count it and sleep with exponential backoff.
-            authRetryCount++;
-            const delay = Math.min(baseBackoffMs * Math.pow(2, attempt - 1), MAX_RETRY_DELAY_MS);
-            const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
-            logger.debug(`[ADAPTER] Auth retry ${attempt}/${maxRetries} (code: ${code}) after ${delay}ms`);
-            await new Promise(r => setTimeout(r, delay));
-        }
-    }
-}
-/**
- * Test-only: reset the auth retry observability counters. NOT exported via
- * the package public surface — only used by unit tests.
- */
-export function _resetAuthRetryCountersForTests() {
-    authRetryCount = 0;
-    authRetryFailureCount = 0;
-}
+// Auth-rate-limit retry subsystem extracted to ./actual-adapter/auth-retry.ts
+// (#166). Imported for internal use (wrapping api.init, getConcurrencyState)
+// and re-exported so the public surface and importers are unchanged.
+import { isRetryableAuthError, withAuthRetry, _resetAuthRetryCountersForTests, getAuthRetryCounts, } from './actual-adapter/auth-retry.js';
+export { isRetryableAuthError, withAuthRetry, _resetAuthRetryCountersForTests };
 /**
  * Initialize Actual API - based on s-stefanov/actual-mcp pattern
  * This calls api.init() and api.downloadBudget() for each operation
@@ -550,15 +473,12 @@ async function shutdownActualApi() {
         setApiInitialized(false);
     }
 }
-import { BANK_SYNC_SETTLE_MS, DEFAULT_CONCURRENCY_LIMIT, DEFAULT_RETRY_ATTEMPTS, MAX_RETRY_DELAY_MS, 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 = [];
+import { BANK_SYNC_SETTLE_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
+// Concurrency limiter extracted to ./actual-adapter/concurrency.ts (#166).
+// Imported for internal use (every method wraps its raw call in withConcurrency)
+// and setMaxConcurrency is re-exported.
+import { withConcurrency, setMaxConcurrency, getConcurrencySnapshot } from './actual-adapter/concurrency.js';
+export { setMaxConcurrency };
 let writeQueue = [];
 let isProcessingWrites = false;
 let writeSessionTimeout = null;
@@ -728,59 +648,16 @@ function queueWriteOperation(operation) {
 export async function withWriteSession(fn) {
     return queueWriteOperation(fn);
 }
-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,
+        ...getConcurrencySnapshot(),
         // Auth-retry observability — issue #127. authRetries is monotonic over the
         // process lifetime; authRetryFailures only increments when retry budget
         // exhausted. A jump in authRetries without a matching jump in
         // authRetryFailures means the retry-with-backoff is absorbing rate-limit
         // pressure (healthy). Both jumping = upstream genuinely overloaded.
-        authRetries: authRetryCount,
-        authRetryFailures: authRetryFailureCount,
+        ...getAuthRetryCounts(),
         // Pool-cooperation observability — issue #134. connectionReuses increments
         // every time withActualApi reused an existing per-session pool connection
         // instead of running its own init+shutdown cycle. Pre-#134 this was
@@ -818,9 +695,6 @@ async function syncToServer() {
         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.
@@ -832,44 +706,10 @@ export function callWithRetry(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 : [],
-    };
-}
+// Extracted to ./actual-adapter/normalize.ts (#166). Imported for internal use
+// and re-exported so the public surface and external importers are unchanged.
+import { normalizeToTransactionArray, normalizeToId, normalizeImportResult } from './actual-adapter/normalize.js';
+export { normalizeToTransactionArray, normalizeToId, normalizeImportResult };
 // ---------------------------------------------------------------------------
 export async function getAccounts() {
     return withActualApi(async () => {
@@ -897,7 +737,7 @@ export async function addTransactions(txs, options = {}) {
             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, options), { retries: 2, backoffMs: 200 }));
+        const result = await withConcurrency(() => retry(() => rawAddTransactions(accountId, cleanedTxs, options), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         // Handle various return formats
         if (result === 'ok') {
             // Transaction created successfully but no IDs returned
@@ -924,7 +764,7 @@ export async function addTransactions(txs, options = {}) {
 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 }));
+        const raw = await withConcurrency(() => retry(() => rawImportTransactions(accountId, txs), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return raw || { added: [], updated: [], errors: [] };
     });
 }
@@ -957,7 +797,7 @@ export async function createTransfer(params) {
             payee: transferPayee.id,
             ...(params.notes !== undefined && { notes: params.notes }),
         };
-        await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
+        await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return { success: true };
     });
     if (!writeResult.success)
@@ -998,7 +838,7 @@ 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 }));
+            const raw = await withConcurrency(() => retry(() => rawCreateCategory(category), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
             return normalizeToId(raw);
         }
         catch (error) {
@@ -1022,7 +862,7 @@ export async function getPayees() {
 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 }));
+        const raw = await withConcurrency(() => retry(() => rawCreatePayee(payee), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return normalizeToId(raw);
     });
 }
@@ -1047,7 +887,7 @@ export async function setBudgetAmount(month, categoryId, amount) {
         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 }));
+        const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
     });
 }
@@ -1091,7 +931,7 @@ export async function transferBudgetAmount(month, fromCategoryId, toCategoryId,
 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 raw = await withConcurrency(() => retry(() => rawCreateAccount(account, initialBalance), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         // NO NEED for syncToServer() - shutdown() will handle persistence
         return id;
@@ -1100,7 +940,7 @@ export async function createAccount(account, initialBalance) {
 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 }));
+        await withConcurrency(() => retry(() => rawUpdateAccount(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return null;
     });
 }
@@ -1143,7 +983,7 @@ 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 }));
+        await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function updateTransactionBatch(updates) {
@@ -1156,7 +996,7 @@ export async function updateTransactionBatch(updates) {
         const failed = [];
         for (const { id, fields } of updates) {
             try {
-                await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200 }));
+                await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
                 succeeded.push({ id });
             }
             catch (err) {
@@ -1179,7 +1019,7 @@ export async function deleteTransaction(id) {
 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 }));
+        await withConcurrency(() => retry(() => rawUpdateCategory(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function deleteCategory(id) {
@@ -1210,7 +1050,7 @@ export async function updatePayee(id, fields) {
         }
         // 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 }));
+            await withConcurrency(() => retry(() => rawUpdatePayee(id, directFields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         }
         // Handle category via the rules mechanism (same approach Actual Budget uses internally)
         if (categoryValue !== undefined) {
@@ -1230,7 +1070,7 @@ export async function updatePayee(id, fields) {
                         ...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 }));
+                    await withConcurrency(() => retry(() => rawUpdateRule(updatedRule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
                     logger.debug(`[UPDATE PAYEE] Updated default category rule for payee ${id} to category ${categoryValue}`);
                 }
             }
@@ -1242,7 +1082,7 @@ export async function updatePayee(id, fields) {
                     conditions: [{ op: 'is', field: 'payee', value: id }],
                     actions: [{ op: 'set', field: 'category', value: categoryValue }],
                 };
-                await withConcurrency(() => retry(() => rawCreateRule(newRule), { retries: 0, backoffMs: 200 }));
+                await withConcurrency(() => retry(() => rawCreateRule(newRule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
                 logger.debug(`[UPDATE PAYEE] Created default category rule for payee ${id} with category ${categoryValue}`);
             }
             // category=null + no existing rule = no-op (already clear)
@@ -1271,7 +1111,7 @@ export async function getRules() {
 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 raw = await withConcurrency(() => retry(() => rawCreateRule(rule), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
     });
@@ -1295,7 +1135,7 @@ export async function updateRule(id, fields) {
             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 }));
+        await withConcurrency(() => retry(() => rawUpdateRule(rule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
         logger.debug(`[UPDATE RULE] Update completed for rule ${id}`);
     });
 }
@@ -1317,7 +1157,7 @@ export async function createSchedule(schedule) {
     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 raw = await withConcurrency(() => retry(() => rawCreateSchedule(schedule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
     });
@@ -1325,7 +1165,7 @@ export async function createSchedule(schedule) {
 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 }));
+        await withConcurrency(() => retry(() => rawUpdateSchedule(id, fields, resetNextDate), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function deleteSchedule(id) {
@@ -1337,7 +1177,7 @@ export async function deleteSchedule(id) {
 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 }));
+        await withConcurrency(() => retry(() => rawSetBudgetCarryover(month, categoryId, flag), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function closeAccount(id) {
@@ -1363,7 +1203,7 @@ export async function getCategoryGroups() {
 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 raw = await withConcurrency(() => retry(() => rawCreateCategoryGroup(group), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
     });
@@ -1371,7 +1211,7 @@ export async function createCategoryGroup(group) {
 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 }));
+        await withConcurrency(() => retry(() => rawUpdateCategoryGroup(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function deleteCategoryGroup(id) {
@@ -1587,110 +1427,10 @@ export async function runQuery(queryString) {
         throw new Error(`Query execution failed: ${errorMsg}`);
     }
 }
-// Helper function to parse WHERE clause conditions.
-// Exported so it can be unit-tested directly.
-// Strip a single pair of surrounding quotes from a SQL value literal.
-function _stripWhereQuotes(s) {
-    return s.trim().replace(/^['"]|['"]$/g, '');
-}
-// Coerce a SQL value literal to a number when it looks numeric, else keep the
-// (unquoted) string. Used for IN lists and comparison operands. Empty stays a
-// string so an empty literal is not silently turned into 0.
-function _coerceWhereValue(s) {
-    const v = _stripWhereQuotes(s);
-    if (v === '')
-        return v;
-    const n = Number(v);
-    return isNaN(n) ? v : n;
-}
-export function parseWhereClause(query, whereClause) {
-    // OR is not supported. Detect it up front and fail loudly. Without this guard
-    // a clause like `amount = 100 OR amount < 0` is left as a single fragment by
-    // the AND-splitter, and the comparison regex's greedy value capture swallows
-    // `100 OR amount < 0` into the operand, running a silently-wrong filter rather
-    // than erroring. That silent mishandling is exactly what #178 set out to stop.
-    // This shares the AND-splitter's quote-naive simplicity: an " OR " inside a
-    // quoted value is a known limitation, the same as " AND ".
-    if (/\sOR\s/i.test(whereClause)) {
-        throw new Error(`Unsupported WHERE condition: OR is not supported. ` +
-            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
-            `Combine conditions with AND only.`);
-    }
-    // Split by AND. This is a simple parser: it does not handle OR or nested /
-    // parenthesised conditions (see the unsupported-operator throw below).
-    const conditions = whereClause.split(/\s+AND\s+/i);
-    for (const condition of conditions) {
-        const trimmedCondition = condition.trim();
-        if (!trimmedCondition)
-            continue;
-        // IS NULL / IS NOT NULL: lets callers find unmerged rows (e.g. imported_payee
-        // IS NULL). ActualQL treats `field: null` as IS NULL and `$ne: null` as IS NOT NULL.
-        const nullMatch = trimmedCondition.match(/^([\w.]+)\s+IS\s+(NOT\s+)?NULL$/i);
-        if (nullMatch) {
-            const [, field, not] = nullMatch;
-            query = not
-                ? query.filter({ [field]: { $ne: null } })
-                : query.filter({ [field]: null });
-            continue;
-        }
-        // NOT LIKE (checked before LIKE so the longer keyword wins).
-        const notLikeMatch = trimmedCondition.match(/^([\w.]+)\s+NOT\s+LIKE\s+(.+)$/i);
-        if (notLikeMatch) {
-            const [, field, valueStr] = notLikeMatch;
-            query = query.filter({ [field]: { $notlike: _stripWhereQuotes(valueStr) } });
-            continue;
-        }
-        // LIKE: pattern match. ActualQL's $like runs through NORMALISE + UNICODE_LIKE,
-        // so it is case-insensitive and accent-insensitive. Use % as the wildcard,
-        // e.g. imported_payee LIKE '%amazon%'.
-        const likeMatch = trimmedCondition.match(/^([\w.]+)\s+LIKE\s+(.+)$/i);
-        if (likeMatch) {
-            const [, field, valueStr] = likeMatch;
-            query = query.filter({ [field]: { $like: _stripWhereQuotes(valueStr) } });
-            continue;
-        }
-        // 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(_coerceWhereValue);
-            query = query.filter({ [field]: { $oneof: values } });
-            continue;
-        }
-        // Comparison operators: 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 operatorMap = {
-                '>=': '$gte',
-                '<=': '$lte',
-                '>': '$gt',
-                '<': '$lt',
-                '=': '$eq',
-                '!=': '$ne',
-            };
-            const actualOp = operatorMap[operator];
-            const finalValue = _coerceWhereValue(valueStr);
-            if (actualOp === '$eq') {
-                // Simple equality can use the direct field: value shorthand.
-                query = query.filter({ [field]: finalValue });
-            }
-            else {
-                query = query.filter({ [field]: { [actualOp]: finalValue } });
-            }
-            continue;
-        }
-        // Nothing matched. Refuse to silently drop the condition: dropping it would
-        // run the query UNFILTERED and hand back misleading "matches everything"
-        // results. Fail loudly with an actionable error instead. See #178.
-        throw new Error(`Unsupported WHERE condition: "${trimmedCondition}". ` +
-            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
-            `OR, REGEXP, NOT IN, and parenthesised groups are not yet supported.`);
-    }
-    return query;
-}
+// WHERE-clause translation extracted to ./actual-adapter/query.ts (#166).
+// Imported for internal use by runQuery and re-exported (unit-tested directly).
+import { parseWhereClause } from './actual-adapter/query.js';
+export { parseWhereClause };
 export async function runBankSync(accountId) {
     try {
         return await withActualApi(async () => {

package/dist/src/lib/retry.js

@@ -1,9 +1,41 @@
 import { DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_BACKOFF_MS, MAX_RETRY_DELAY_MS } from './constants.js';
 import { ModuleLoggers } from './loggerFactory.js';
 const log = ModuleLoggers.RETRY;
+/**
+ * Error-message fragments that mark a TRANSIENT / infrastructure-level failure:
+ * the kind a retry can actually recover from, and the kind worth dropping a
+ * pooled connection over. Single source of truth for #177: the adapter's
+ * `_shouldDropPoolOnError` delegates to `isRetryableError`, so the retry
+ * decision and the pool-drop decision cannot drift apart.
+ *
+ * Anything NOT matching here (domain/validation errors such as "is required",
+ * "not found", "does not exist", Zod failures, and any unknown error) is
+ * terminal: it fails the same way on every attempt, so it must NOT be retried.
+ */
+export const TRANSIENT_ERROR_PATTERNS = [
+    'Authentication failed',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'socket hang up',
+    'ETIMEDOUT',
+    'out of memory',
+    'ENOMEM',
+];
+/**
+ * True only for known transient/infrastructure errors (#177). Non-Error and
+ * unknown rejections return false (fail fast), so a deterministic domain error
+ * is never retried.
+ */
+export function isRetryableError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message || '';
+    return TRANSIENT_ERROR_PATTERNS.some(p => msg.includes(p));
+}
 export async function retry(fn, opts) {
     const retries = opts?.retries ?? DEFAULT_RETRY_ATTEMPTS;
     const backoffMs = opts?.backoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+    const isRetryable = opts?.isRetryable;
     let attempt = 0;
     while (true) {
         try {
@@ -12,6 +44,14 @@ export async function retry(fn, opts) {
             return result;
         }
         catch (err) {
+            // Fail fast on a non-retryable (domain/validation) error when a classifier
+            // is supplied: retrying cannot help and only wastes work plus log noise
+            // (#177). With no classifier, behaviour is unchanged (retry until the
+            // attempt budget is exhausted), preserving every existing call site.
+            if (isRetryable && !isRetryable(err)) {
+                log.debug('Not retrying non-transient error', { error: err?.message });
+                throw err;
+            }
             attempt++;
             if (attempt > retries) {
                 log.error(`All retry attempts exhausted after ${retries} tries`, err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",