actual-mcp-server 0.8.1 → 0.8.3

package/README.md

@@ -449,6 +449,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `ACTUAL_BUDGET_SYNC_ID` | _(none)_ | Yes | Budget Sync ID from Actual (Settings then Sync ID) |
 | `ACTUAL_BUDGET_PASSWORD` | _(none)_ | No | Optional encryption password for encrypted budgets |
 | `ALLOW_INSECURE_UPSTREAM` | `false` | No | Allow an `http://` upstream even when `ACTUAL_BUDGET_PASSWORD` is set (#161). Off by default so a plaintext upstream plus an encryption password is refused |
+| `ACTUAL_OP_TIMEOUT_MS` | `30000` | No | Per-operation timeout (ms) for every upstream Actual API call (init, budget download, sync, and each tool operation). A stalled call rejects after this bound so it cannot hold the global API mutex forever and hang subsequent tool calls (#270). Set to `0` to disable |
 | **MCP Server Settings** ||||
 | `MCP_BRIDGE_PORT` | `3600` | No | Port for MCP server to listen on |
 | `MCP_BRIDGE_BIND_HOST` | `0.0.0.0` | No | Host address to bind server to (`0.0.0.0` = all interfaces) |
@@ -719,4 +720,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.8.1 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.8.3 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.8.1",
+    "version": "0.8.3",
     "engines": {
         "node": ">=22.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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/httpServer_session_not_found.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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/httpServer_session_not_found.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.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/config.js

@@ -5,6 +5,30 @@ export const configSchema = z.object({
     ACTUAL_BUDGET_SYNC_ID: z.string().min(1),
     // Optional per-budget encryption password (leave unset for unencrypted budgets)
     ACTUAL_BUDGET_PASSWORD: z.string().optional(),
+    // #270: bound every upstream Actual API operation (api.init, downloadBudget,
+    // sync, and each tool operation body) so a stalled call cannot hold the
+    // process-global api mutex forever and hang all subsequent tool calls. On
+    // timeout the operation rejects with a clear error, the mutex releases, and
+    // later calls proceed. Default 30000ms (30s): generous for a healthy
+    // init+download on a large budget, short enough that a stalled upstream
+    // recovers in seconds instead of wedging the session. Set to 0 to disable the
+    // bound (not recommended). A non-numeric or negative value falls back to the
+    // default. `0` disables the bound. Any other positive value is clamped to the
+    // range [250ms, 2147483647ms]:
+    //   - Floor 250ms: a smaller positive value would time out real operations
+    //     almost immediately (a self-inflicted DoS footgun, e.g. a typo'd `25`).
+    //     Use `0` to disable deliberately rather than a tiny value.
+    //   - Ceiling 2147483647ms (~24.8 days, the 32-bit setTimeout max): a larger
+    //     value overflows setTimeout and silently clamps to 1ms, timing out
+    //     everything.
+    ACTUAL_OP_TIMEOUT_MS: z.string().default('30000').transform(val => {
+        const n = parseInt(val, 10);
+        if (!Number.isFinite(n) || n < 0)
+            return 30000;
+        if (n === 0)
+            return 0;
+        return Math.min(Math.max(n, 250), 2147483647);
+    }),
     // Escape hatch for #161: allow an http:// upstream even when an E2E encryption
     // password is set (e.g. an isolated Docker network where the hop is trusted).
     // Off by default so a plaintext upstream + encryption password is refused.

package/dist/src/lib/ActualConnectionPool.js

@@ -17,6 +17,7 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
+import { withOpTimeout } from './opTimeout.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
     connections = new Map();
@@ -214,22 +215,27 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            await api.init({
+            // Bound the session-open init/download (#270): this is the HTTP exposure.
+            // A stalled upstream here would otherwise hang session open unbounded and,
+            // because the api singleton is process-global, wedge other sessions too.
+            await withOpTimeout(() => api.init({
                 dataDir: DATA_DIR,
                 serverURL: SERVER_URL,
                 password: PASSWORD,
-            });
-            // Mark the singleton as live so the adapter's pool-cooperation branch
-            // (withActualApi in actual-adapter.ts) can safely skip its per-op init.
-            setApiInitialized(true);
+            }), 'pool init');
             logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
-                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
             }
             else {
-                await api.downloadBudget(BUDGET_SYNC_ID);
+                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
             }
+            // Mark the singleton as live only AFTER the budget is downloaded (#270):
+            // setting it before downloadBudget left a poisoning window where the
+            // adapter's pool-cooperation branch could reuse a connection whose budget
+            // never loaded (a stalled/failed download would leak isApiInitialized=true).
+            setApiInitialized(true);
             conn = {
                 sessionId,
                 initialized: true,
@@ -284,19 +290,22 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            await api.init({
+            // Bound the session-open init/download (#270), same as getConnection.
+            await withOpTimeout(() => api.init({
                 dataDir: DATA_DIR,
                 serverURL: SERVER_URL,
                 password: PASSWORD,
-            });
-            setApiInitialized(true);
+            }), 'pool init');
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
-                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
             }
             else {
-                await api.downloadBudget(BUDGET_SYNC_ID);
+                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
             }
+            // Mark live only after a successful download (#270): avoids the poisoning
+            // window where a stalled/failed download would leak isApiInitialized=true.
+            setApiInitialized(true);
             this.sharedConnection = {
                 sessionId: 'shared',
                 initialized: true,

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

@@ -9,6 +9,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import { retry, isRetryableError } from './retry.js';
+import { withOpTimeout } from './opTimeout.js';
 import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
 import config from '../config.js';
@@ -88,6 +89,9 @@ function withApiLock(fn) {
     _apiSessionLock = new Promise(resolve => { release = resolve; });
     return prevLock.then(() => fn()).finally(() => release());
 }
+// Per-op timeout (#270) lives in ./opTimeout.ts so ActualConnectionPool can bound
+// its own session-open init/download without a circular import back into this
+// module (which imports the pool singleton).
 // ----------------------------------------------------------------------------
 // Per-session pool cooperation — issue #134
 // ----------------------------------------------------------------------------
@@ -237,7 +241,7 @@ export async function withActualApi(operation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for session ${sessionId} (reuses=${connectionReuseCount})`);
-                return await operation();
+                return await withOpTimeout(operation);
             }
             catch (err) {
                 // Only drop the pool connection on errors that suggest the api
@@ -262,7 +266,7 @@ export async function withActualApi(operation) {
     return withApiLock(async () => {
         try {
             await initActualApiForOperation();
-            return await operation();
+            return await withOpTimeout(operation);
         }
         finally {
             await shutdownActualApi();
@@ -290,13 +294,13 @@ export async function withActualApiWrite(operation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for write session ${sessionId} (reuses=${connectionReuseCount})`);
-                const result = await operation();
+                const result = await withOpTimeout(operation);
                 // Propagate the write to the server so other clients (and our next
                 // read) see it. Pre-#134 this happened implicitly via api.shutdown().
                 try {
                     const apiAny = api;
                     if (typeof apiAny.sync === 'function') {
-                        await apiAny.sync();
+                        await withOpTimeout(() => apiAny.sync(), 'sync');
                     }
                 }
                 catch (syncErr) {
@@ -332,7 +336,7 @@ export async function withActualApiWrite(operation) {
     return withApiLock(async () => {
         try {
             await initActualApiForOperation();
-            return await operation();
+            return await withOpTimeout(operation);
         }
         finally {
             await shutdownActualApi();
@@ -420,18 +424,27 @@ async function initActualApiForOperation() {
         logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${budget.serverUrl})`);
         // Wrap api.init in auth-rate-limit retry so a transient too-many-requests
         // doesn't surface to the caller (and doesn't trigger #132's crash path).
-        await withAuthRetry(() => api.init({
+        // Bound EACH init attempt with the op timeout (#270), inside withAuthRetry:
+        // a stalled login rejects per attempt, and a timeout is not an auth error so
+        // withAuthRetry does not retry it. Wrapping per-attempt (not the whole retry
+        // loop) means legitimate #127 auth-rate-limit backoff (up to ~25s) is not
+        // counted against ACTUAL_OP_TIMEOUT_MS.
+        await withAuthRetry(() => withOpTimeout(() => api.init({
             dataDir: DATA_DIR,
             serverURL: budget.serverUrl,
             password: budget.password || '',
-        }));
+        }), 'init'));
         logger.debug('[ADAPTER] Downloading budget');
+        // Bound downloadBudget (#270): the legacy stdio path re-downloads on every
+        // op, and a stall here was the production hang. On timeout it rejects and
+        // the mutex releases.
         if (budget.encryptionPassword) {
+            const encryptionPassword = budget.encryptionPassword;
             const apiWithOptions = api;
-            await apiWithOptions.downloadBudget(budget.syncId, { password: budget.encryptionPassword });
+            await withOpTimeout(() => apiWithOptions.downloadBudget(budget.syncId, { password: encryptionPassword }), 'downloadBudget');
         }
         else {
-            await api.downloadBudget(budget.syncId);
+            await withOpTimeout(() => api.downloadBudget(budget.syncId), 'downloadBudget');
         }
         setApiInitialized(true);
         logger.debug('[ADAPTER] Actual API initialized for operation');
@@ -459,7 +472,7 @@ async function shutdownActualApi() {
             try {
                 const apiAny = api;
                 if (typeof apiAny.sync === 'function') {
-                    await apiAny.sync();
+                    await withOpTimeout(() => apiAny.sync(), 'sync');
                     logger.debug('[ADAPTER] api.sync() instead of shutdown (pool has active sessions)');
                 }
             }
@@ -477,7 +490,10 @@ async function shutdownActualApi() {
     try {
         const maybeApi = api;
         if (typeof maybeApi.shutdown === 'function') {
-            await maybeApi.shutdown();
+            // Bound shutdown too (#270): it runs inside withApiLock, so a stalled
+            // shutdown would hold the mutex just like a stalled op. Errors here are
+            // already best-effort (swallowed below), and a timeout is one of them.
+            await withOpTimeout(() => maybeApi.shutdown(), 'shutdown');
             logger.debug('[ADAPTER] Actual API shutdown complete');
         }
     }
@@ -546,7 +562,10 @@ async function processWriteQueue() {
                 // Each operation handles its own success/failure
                 await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
                     try {
-                        const result = await operation();
+                        // Bound each queued write (#270): a stalled op must reject its own
+                        // promise (so withWriteSession callers don't hang) and let the
+                        // batch settle so the api mutex releases.
+                        const result = await withOpTimeout(operation);
                         resolve(result);
                     }
                     catch (error) {
@@ -558,7 +577,7 @@ async function processWriteQueue() {
                 // before returning (pool). Persistence guarantee in both branches.
                 logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
                 try {
-                    await api.sync();
+                    await withOpTimeout(() => api.sync(), 'sync');
                     logger.debug(`[WRITE QUEUE] Sync completed`);
                 }
                 catch (syncError) {
@@ -1680,12 +1699,14 @@ export async function switchBudget(name) {
         }
         else {
             await withApiLock(async () => {
+                // Bound the in-place budget reload too (#270).
                 if (found.encryptionPassword) {
+                    const encryptionPassword = found.encryptionPassword;
                     const apiWithOptions = api;
-                    await apiWithOptions.downloadBudget(found.syncId, { password: found.encryptionPassword });
+                    await withOpTimeout(() => apiWithOptions.downloadBudget(found.syncId, { password: encryptionPassword }), 'downloadBudget');
                 }
                 else {
-                    await api.downloadBudget(found.syncId);
+                    await withOpTimeout(() => api.downloadBudget(found.syncId), 'downloadBudget');
                 }
             });
         }

package/dist/src/lib/opTimeout.js

@@ -0,0 +1,48 @@
+import config from '../config.js';
+/**
+ * Bound a single upstream Actual API call so a stall cannot hold the process-global
+ * API mutex (or a session-open path) forever (#270). `@actual-app/api` is a
+ * single-connection singleton: every op is serialised through `withApiLock`, and
+ * session open runs `api.init()` + `downloadBudget()` in `ActualConnectionPool`.
+ * The mutex releases in a `.finally()`, but the upstream calls it guards
+ * (`api.init`, `downloadBudget`, `api.sync`, and each tool operation body) had no
+ * timeout. If one stalled (a half-open socket, the server restarting mid-request,
+ * a VPN idle-drop) the `release()` never ran and every subsequent tool call
+ * blocked forever.
+ *
+ * This races the call against `ACTUAL_OP_TIMEOUT_MS`. On timeout it REJECTS with a
+ * clear, actionable error; because the rejection propagates through the enclosing
+ * `withApiLock(...).finally(release)` (reads), the write-queue catch (writes), or
+ * the pool's own try/catch (session open), the resource is freed and later calls
+ * proceed. A configured timeout of 0 disables the bound.
+ *
+ * Recovery: in the adapter legacy path the enclosing `finally` runs
+ * `shutdownActualApi()`, so the next call re-inits a fresh singleton. In pooled
+ * mode the timeout error message ("timed out") matches the transient pattern list
+ * (retry.ts), so `_shouldDropPoolOnError` drops the pooled connection and the next
+ * call re-inits cleanly. Because the timeout is thrown OUTSIDE any `retry()`,
+ * classing it transient drops the pool without causing a retry storm.
+ *
+ * `fn()` is invoked via `Promise.resolve().then(fn)` so a SYNCHRONOUS throw from
+ * `fn` becomes a rejected promise the race can settle on, rather than escaping
+ * before `Promise.race` is built (which would orphan the armed timer and later
+ * fire an unhandledRejection).
+ */
+export function withOpTimeout(fn, label = 'operation') {
+    const timeoutMs = config.ACTUAL_OP_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return fn();
+    }
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`Actual API ${label} timed out after ${timeoutMs}ms (ACTUAL_OP_TIMEOUT_MS). ` +
+                'The upstream Actual server may be unreachable or stalled; the operation was ' +
+                'aborted so the session can recover. Please retry the request.'));
+        }, timeoutMs);
+    });
+    return Promise.race([Promise.resolve().then(fn), timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}

package/dist/src/lib/retry.js

@@ -20,6 +20,12 @@ export const TRANSIENT_ERROR_PATTERNS = [
     'ETIMEDOUT',
     'out of memory',
     'ENOMEM',
+    // #270: the adapter's per-op timeout (withOpTimeout) rejects a stalled upstream
+    // call with a message containing "timed out". Classing it transient means the
+    // pooled connection is dropped so the session re-inits cleanly on the next
+    // call. The timeout error is thrown OUTSIDE any retry(), so this does not cause
+    // a retry storm; it only feeds the pool-drop decision.
+    'timed out',
 ];
 /**
  * True only for known transient/infrastructure errors (#177). Non-Error and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "engines": {
     "node": ">=22.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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/httpServer_session_not_found.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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/httpServer_session_not_found.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.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",