actual-mcp-server 0.16.6 → 0.16.7

package/README.md

@@ -476,6 +476,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `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 |
+| `ACTUAL_IMPORT_TIMEOUT_MS` | `600000` | No | Separate, larger timeout (ms) for a budget import, which is legitimately long rather than stalled. An import is a tracked load, so every other session waits on it; bounding it at the general operation timeout turned one tenant's large import into a process-wide stall (#407). 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) |
@@ -774,7 +775,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.6 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.7 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/config.js

@@ -30,6 +30,34 @@ export const configSchema = z.object({
             return 0;
         return Math.min(Math.max(n, 250), 2147483647);
     }),
+    /**
+     * #407: a separate, larger bound for a budget IMPORT.
+     *
+     * An import is not a stalled operation, it is a legitimately long one: a large YNAB or zip
+     * import runs for minutes. #394 made it a TRACKED load, so while it is in flight every other
+     * session's lock acquisition waits for it and then fails at ACTUAL_OP_TIMEOUT_MS. Bounding a
+     * five-minute import at the 30 second operation default therefore turned one tenant's import
+     * into a process-wide stall, with every other session failing repeatedly for the duration.
+     *
+     * Same parse-and-clamp shape as ACTUAL_OP_TIMEOUT_MS, and the same escape hatch: 0 disables the
+     * bound, which for an import means it can hold the process-global api mutex indefinitely (the
+     * #393 P0 shape), so it is for diagnosis rather than production.
+     *
+     * The clamp floor is 250ms, the same as the operation timeout. It is deliberately NOT raised to
+     * the operation timeout's configured VALUE: an earlier comment here claimed an import bound below
+     * the general one was prevented, and it was not, so the claim is removed rather than left to
+     * mislead. A smaller import bound is unusual but coherent (abandon imports sooner than ordinary
+     * reads), and enforcing an ordering between two independently configured knobs at parse time
+     * would need one to be parsed before the other.
+     */
+    ACTUAL_IMPORT_TIMEOUT_MS: z.string().default('600000').transform(val => {
+        const n = parseInt(val, 10);
+        if (!Number.isFinite(n) || n < 0)
+            return 600000;
+        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/actual-adapter.js

@@ -21,7 +21,7 @@ import { parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
 import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
-import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, setLoadedBudgetSyncId } from './apiState.js';
+import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, awaitAbandonedBudgetLoad } from './apiState.js';
 import { withApiLock } from './apiLock.js';
 import { loadBudgetTracked, importBudgetTracked } from './budgetLoader.js';
 /**
@@ -830,7 +830,7 @@ async function processWriteQueue() {
                     //
                     // Each op keeps its own withOpTimeout (#270) and still settles individually, so one
                     // stalled or rejected operation cannot hold the api mutex or fail its siblings.
-                    for (const { operation, resolve, reject, preservesListings, requestStore } of batch) {
+                    for (const { operation, resolve, reject, preservesListings, requestStore, timeoutMs } of batch) {
                         try {
                             // #390 round 2: run each op in the context it was ENQUEUED in.
                             //
@@ -847,8 +847,40 @@ async function processWriteQueue() {
                             // been correct wrong. Re-entering the captured store makes each op resolve its own
                             // budget, which is what #158 captured a per-entry sessionId for in the first place.
                             const result = await requestContext.run(requestStore ?? {}, async () => {
+                                // #406: settle any abandoned budget load PER OPERATION, not per lock acquisition.
+                                //
+                                // #393 made the wait part of acquiring the api lock, which makes the set of call
+                                // sites stop mattering: nothing reaches the api without the lock, so nothing reaches
+                                // it without the wait. That holds for every path where one acquisition serves one
+                                // operation. It does NOT hold here. This drain acquires the lock ONCE and then runs
+                                // N operations inside it, so once any op abandons a load, every LATER op in the same
+                                // batch runs against a singleton that abandoned load will re-point, having never
+                                // waited for it. Reproduced with a slow import and a following write in one debounce
+                                // window; it is the #390 class with a new author.
+                                //
+                                // Deliberately NOT inside ensureLoadedBudgetMatchesSession: that returns early when
+                                // the loaded budget already matches, and an op whose budget happens to match still
+                                // needs the wait, because the abandoned load is about to move the singleton AWAY
+                                // from it. The wait has to be unconditional, so it sits before the precondition.
+                                //
+                                // A rejection here is caught by this loop's own per-op catch, so a stuck load fails
+                                // ONE operation rather than the whole batch, which is the behaviour #393 round 4
+                                // established for the drain.
+                                await awaitAbandonedBudgetLoad(withOpTimeout);
                                 await ensureLoadedBudgetMatchesSession();
-                                return await withOpTimeout(operation);
+                                // #407: an operation may carry its OWN bound. Only a budget import does today, and
+                                // it needs one: the import is legitimately long, and bounding it at the general
+                                // operation timeout abandons it while every other session is already waiting on it
+                                // as a tracked load. Without this the raised bound inside the loader is dead letter,
+                                // because THIS wrapper would abandon the op first.
+                                //
+                                // A long op does NOT need a keep-alive heartbeat, and one was written and removed in
+                                // review. The session cannot be swept out from under it: `cleanupIdleConnections`
+                                // passes `onlyIfExpired`, so `shutdownConnectionLocked` re-checks expiry AFTER
+                                // acquiring the mutex (#392), and the `finally` below touches every session in the
+                                // batch before the lock is released. A sweep that queued behind this drain therefore
+                                // finds the entry fresh and returns without evicting.
+                                return await withOpTimeout(operation, 'operation', timeoutMs);
                             });
                             resolve(result);
                         }
@@ -1021,6 +1053,7 @@ function queueWriteOperation(operation, options) {
             sessionId,
             requestStore: requestContext.getStore(),
             preservesListings: options?.preservesListings,
+            timeoutMs: options?.timeoutMs,
         };
         // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
         // operation that is RUNNING; it cannot bound one that never starts. Reuse the same
@@ -2898,17 +2931,32 @@ export async function importBudget(input, opts = {}) {
         // #390 still holds at this call site: `importBudgetTracked` records the `imported:` sentinel
         // when the promise settles, whichever way, and the clear below states the same fact at the
         // call site where the guard in tests/unit/budget_selection_precondition.test.js can see it.
+        // #408: invalidate BEFORE the import starts, not after it resolves.
+        //
+        // The invalidation below used to run only after `queueWriteOperation` resolved, so on the
+        // TIMEOUT path it never ran at all, and a large import exceeding ACTUAL_OP_TIMEOUT_MS is the
+        // expected case rather than a rare one. Every pool entry then kept naming the pre-import
+        // syncId while the singleton moved to the imported file, and switchBudget's #172 fast path
+        // no-opped on a switch back: the reported-success-with-no-effect class #349 exists to prevent.
+        //
+        // Moving it here follows the same clear-before-you-start discipline #394 established for the
+        // record itself: a mutation that may be abandoned must leave state INDETERMINATE, never
+        // confidently wrong. It is idempotent and costs nothing on the success path, where the call
+        // after the write simply re-applies the same sentinel.
+        const preInvalidated = connectionPool.invalidateAllLoadedSyncIds('imported:pending');
+        if (preInvalidated > 0) {
+            logger.debug(`[ADAPTER] importBudget: invalidated the pooled syncId on ${preInvalidated} session(s) before starting`);
+        }
         const imported = await importBudgetTracked(() => {
             const started = withConcurrency(() => retry(() => rawImportBudget(input, opts), {
                 retries: 0,
                 backoffMs: 200,
                 isRetryable: isRetryableError,
             }));
-            setLoadedBudgetSyncId(null);
             return started;
         });
         return imported;
-    });
+    }, { timeoutMs: config.ACTUAL_IMPORT_TIMEOUT_MS });
     // #349: an import CHANGES WHICH BUDGET IS LOADED, so the pool's record of it
     // must stop naming the old one.
     //

package/dist/src/lib/apiState.js

@@ -131,3 +131,17 @@ export async function awaitAbandonedBudgetLoad(bound) {
 export function _hasPendingBudgetLoadForTests() {
     return _pendingBudgetLoads.size > 0;
 }
+/**
+ * Test hook: drop every registration.
+ *
+ * There is deliberately no production unregister: an entry leaves this set only when its promise
+ * settles, which is what makes "is a load outstanding" mean anything (#393). But a test that
+ * registers a NEVER-settling load has no way back, and leaving one pending poisons every later
+ * lock acquisition in that file, so a later case silently exercises a poisoned lock while claiming
+ * to test something else. Both of this repo's abandoned-load test files hit exactly that.
+ *
+ * Test-only, and not exported through the package surface.
+ */
+export function _clearPendingBudgetLoadsForTests() {
+    _pendingBudgetLoads.clear();
+}

package/dist/src/lib/budgetLoader.js

@@ -1,5 +1,6 @@
 import api from '@actual-app/api';
 import { withOpTimeout } from './opTimeout.js';
+import config from '../config.js';
 import { setApiInitialized, setLoadedBudgetSyncId, registerBudgetLoad } from './apiState.js';
 import { createModuleLogger } from './loggerFactory.js';
 const log = createModuleLogger('BUDGET-LOADER');
@@ -181,6 +182,9 @@ export function _clearReasonCacheForTests() {
     reasonCache.clear();
 }
 async function diagnose(syncId) {
+    // #409: what the cache held before a re-diagnosis, so a failed re-diagnosis can fall back to it
+    // rather than reporting nothing.
+    let staleReason;
     // #396 review: memoise the reason STRING, never the fail-closed decision. Without this, every
     // tool call while the condition persists pays two bounded network calls WHILE HOLDING the
     // process-global api mutex, so a single unloadable budget stalls unrelated sessions for up to
@@ -199,9 +203,16 @@ async function diagnose(syncId) {
             log.debug('reusing the cached load-failure reason', { syncId, uses: cached.uses });
             return cached.reason || undefined;
         }
-        // #404: the entry has served its budget of calls. Drop it and fall through to a fresh
-        // diagnosis, so a failure mode that changed without an intervening success is picked up.
-        reasonCache.delete(syncId);
+        // #404: the entry has served its budget of calls, so fall through to a fresh diagnosis and
+        // pick up a failure mode that changed without an intervening success.
+        //
+        // #409: do NOT delete it here. Deleting first meant a re-diagnosis that then failed
+        // transiently (a `getBudgets` blip) left the caller with "upstream discarded the reason"
+        // despite a perfectly good cached one having existed a moment earlier, and the next call paid
+        // two more bounded network calls inside the api mutex to rediscover it. The stale entry is
+        // kept as a fallback and is only overwritten when a new answer is actually produced.
+        staleReason = cached.reason;
+        cached.uses = 0;
         log.debug('re-diagnosing the load failure after the cached reason served its budget', {
             syncId,
             afterUses: REDIAGNOSE_AFTER_USES,
@@ -235,6 +246,13 @@ async function diagnose(syncId) {
             // stay in THIS brace-balanced block: the guard's window ends at the first `}` that takes
             // depth below zero, so a setter in a sibling `catch` or `finally` arm would be outside it.
             setLoadedBudgetSyncId(null);
+            // #407 review (I3): DROP any cached reason here. #409 stopped deleting the entry before a
+            // re-diagnosis, which is right for the failed-diagnosis path, but on THIS path the old
+            // reason has just been proven wrong: the load worked. Leaving it cached with uses reset
+            // meant the next 20 calls reported a permanent-sounding migration code for a condition the
+            // diagnosis had just shown to be transient, which is exactly the reading the comment below
+            // says to avoid.
+            reasonCache.delete(syncId);
             // #396 review: the retry SUCCEEDED, so this was not a deterministic unloadable budget. Say
             // so rather than reporting "upstream discarded the reason", which reads as permanent. The
             // operation still fails (the record is indeterminate by design, which forces a re-select),
@@ -262,6 +280,13 @@ async function diagnose(syncId) {
     catch (diagErr) {
         // A failing diagnostic is LOGGED, never substituted for the post-condition error.
         log.warn('could not diagnose why the budget did not load', { syncId, error: messageOf(diagErr) });
+        // #409: fall back to the previous answer rather than reporting nothing. It described this same
+        // budget's failure moments ago and is far more useful than silence; the use counter was reset,
+        // so the next call re-attempts the diagnosis anyway.
+        if (staleReason !== undefined) {
+            reasonCache.set(syncId, { reason: staleReason, uses: 0 });
+            return staleReason || undefined;
+        }
         return undefined;
     }
 }
@@ -294,10 +319,15 @@ function postConditionError(syncId, reason) {
  * `verify` is #396's post-condition, and it runs BEFORE the record is written, so the record can
  * only ever describe a mutation that actually took effect.
  */
-async function trackBudgetMutation(start, describeLoaded, label, verify, onRecorded) {
-    const raw = start();
-    // Indeterminate from here until it settles. Cleared first, deliberately.
+async function trackBudgetMutation(start, describeLoaded, label, verify, onRecorded, timeoutMs) {
+    // Indeterminate from here until it settles. Cleared BEFORE the load is even started, so the
+    // record can never name the outgoing budget while the singleton is moving away from it: that is
+    // the one direction that makes #390's precondition silently pass. It used to be cleared on the
+    // statement AFTER `start()`, which was safe in practice (both run in one synchronous turn, so
+    // nothing could observe the gap) but made the invariant untestable and the comment's own word
+    // "first" untrue.
     setLoadedBudgetSyncId(null);
+    const raw = start();
     const tracked = raw
         .then(async (result) => {
         if (verify)
@@ -329,7 +359,7 @@ async function trackBudgetMutation(start, describeLoaded, label, verify, onRecor
     registerBudgetLoad(tracked);
     // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
     // waits for it inside the lock rather than racing it.
-    return await withOpTimeout(() => tracked, label);
+    return await withOpTimeout(() => tracked, label, timeoutMs);
 }
 /**
  * #394: the same discipline for an IMPORT.
@@ -362,24 +392,23 @@ export async function importBudgetTracked(start, label = 'importBudget') {
     // outside the ACL, so no session can ever legitimately match it and every session's next
     // operation re-selects its own budget. Configured sync ids are UUIDs, so an `imported:` prefix
     // can never compare equal to one.
-    return trackBudgetMutation(start, (result) => `imported:${result.id}`, label);
+    // #407: the import's OWN bound. See ACTUAL_IMPORT_TIMEOUT_MS in config.ts for why a long
+    // import must not be abandoned at the ordinary operation timeout: it is tracked, so every other
+    // session waits on it, and abandoning it early turns one tenant's import into a process-wide
+    // stall without making the import itself any faster.
+    return trackBudgetMutation(start, (result) => `imported:${result.id}`, label, undefined, undefined, config.ACTUAL_IMPORT_TIMEOUT_MS);
 }
 export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
     try {
-        await trackBudgetMutation(() => {
-            const started = encryptionPassword
-                ? api
-                    .downloadBudget(syncId, { password: encryptionPassword })
-                : api.downloadBudget(syncId);
-            // Indeterminate from the moment the download starts. `trackBudgetMutation` clears the
-            // record too; this repeats it at the CALL SITE on purpose, AFTER the call, because block
-            // (4) of tests/unit/budget_selection_precondition.test.js scans FORWARD from the matched
-            // line to the end of its brace-balanced block and requires a record there. Satisfying
-            // that structurally, rather than exempting this file from the guard, is what keeps the
-            // #390 protection worth having.
-            setLoadedBudgetSyncId(null);
-            return started;
-        }, () => syncId, label, 
+        await trackBudgetMutation(
+        // #410: no redundant clear here any more. `trackBudgetMutation` owns the clear-before, and
+        // the guard in tests/unit/budget_selection_precondition.test.js now asserts the invariant
+        // that actually holds (a raw load must be inside the tracked helper) rather than looking for
+        // a setter in the same block, which had stopped discriminating.
+        () => encryptionPassword
+            ? api
+                .downloadBudget(syncId, { password: encryptionPassword })
+            : api.downloadBudget(syncId), () => syncId, label, 
         // #396: the post-condition runs INSIDE the tracked chain, before the record is written, so
         // an ABANDONED load is verified when it lands rather than recording a success nobody
         // checked. The network enrichment below deliberately does NOT run there.

package/dist/src/lib/opTimeout.js

@@ -28,15 +28,25 @@ import config from '../config.js';
  * 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;
+export function withOpTimeout(fn, label = 'operation', overrideMs, overrideKnob = 'ACTUAL_IMPORT_TIMEOUT_MS') {
+    // #407: an explicit override, for an operation that is legitimately long rather than stalled.
+    // A budget import is the only one today. Everything else keeps the general bound, because the
+    // whole point of #270 is that one stalled call must not hold the process-global mutex.
+    const timeoutMs = overrideMs === undefined ? config.ACTUAL_OP_TIMEOUT_MS : overrideMs;
+    // #407 review (I4): name the knob that ACTUALLY applies. Hardcoding ACTUAL_OP_TIMEOUT_MS sent an
+    // operator whose import died at the import bound to raise a variable with no effect on imports.
+    //
+    // The name is a PARAMETER rather than inferred from "an override exists" (round 2): inferring it
+    // is correct only while exactly one call site passes an override, and the second one would
+    // silently report the import knob for a different bound, which is the same misdirection.
+    const knob = overrideMs === undefined ? 'ACTUAL_OP_TIMEOUT_MS' : overrideKnob;
     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). ` +
+            reject(new Error(`Actual API ${label} timed out after ${timeoutMs}ms (${knob}). ` +
                 'The upstream Actual server may be unreachable or stalled; the operation was ' +
                 'aborted so the session can recover. Please retry the request.'));
         }, timeoutMs);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.6",
+  "version": "0.16.7",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"