actual-mcp-server 0.6.14 → 0.6.15

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.14 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.15 | **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.14",
+    "version": "0.6.15",
     "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/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_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/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/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/pool_liveness.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/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/actualConnection.js

@@ -130,7 +130,12 @@ export async function shutdownActualForSession(sessionId) {
         return;
     }
     try {
-        await connectionPool.shutdownConnection(sessionId);
+        // evict: true so the pool tears down the matching httpServer transport too
+        // (#167). This wrapper is only used for session-ending events (explicit
+        // session_close, server shutdown); the adapter's switchBudget / infra-drop
+        // paths call connectionPool.shutdownConnection directly without evict so the
+        // transport survives a budget switch or transient error.
+        await connectionPool.shutdownConnection(sessionId, { evict: true });
         logger.info(`Actual API connection shutdown for session: ${sessionId}`);
     }
     catch (err) {

package/dist/src/lib/ActualConnectionPool.js

@@ -23,9 +23,16 @@ class ActualConnectionPool {
     cleanupInterval = null;
     IDLE_TIMEOUT; // Configurable via SESSION_IDLE_TIMEOUT_MINUTES env var (default: 5 minutes)
     CLEANUP_INTERVAL; // Check frequency (default: 2 minutes)
-    MAX_CONCURRENT_SESSIONS; // Configurable via MAX_CONCURRENT_SESSIONS env var (default: 1)
+    MAX_CONCURRENT_SESSIONS; // Configurable via MAX_CONCURRENT_SESSIONS env var (default: 15)
     sharedConnection = null;
     initializationPromise = null;
+    // Eviction listeners. The pool is the single source of truth for session
+    // liveness and idle timing (#167); when it removes a session it notifies the
+    // transport layer (httpServer) so the transport object is torn down in the
+    // same window. This is callback-based eager teardown, not lazy query-on-demand:
+    // a lazily-cleaned table would leak transport objects for sessions a client
+    // abandons without reconnecting.
+    evictionCallbacks = [];
     constructor() {
         // Read from environment variable or default to 15
         // @actual-app/api is a singleton, so concurrent sessions cause conflicts
@@ -76,6 +83,61 @@ class ActualConnectionPool {
         const conn = this.connections.get(sessionId);
         return conn?.initialized ?? false;
     }
+    /**
+     * Single source of truth for session liveness (#167). Returns true only if
+     * the session has an initialized connection that has not passed the idle
+     * timeout. Returns false for unknown or expired sessions, and never creates
+     * an entry as a side effect. httpServer uses this as a per-request defensive
+     * guard against the race where the idle sweep evicts a session while a
+     * request for it is already in flight.
+     */
+    isLive(sessionId) {
+        const conn = this.connections.get(sessionId);
+        if (!conn || !conn.initialized)
+            return false;
+        return !this.isExpired(conn);
+    }
+    /**
+     * Single definition of "past the idle window". Shared by isLive and the idle
+     * sweep so the two can never disagree about where the boundary is (#167).
+     */
+    isExpired(conn) {
+        return (Date.now() - conn.lastActivity) > this.IDLE_TIMEOUT;
+    }
+    /**
+     * Refresh a session's activity timestamp. Called by the transport layer on
+     * every request so the pool's idle clock reflects real usage (#167). Before
+     * this, the pool only stamped lastActivity at init/switch, so an actively
+     * used session's pool clock never advanced; httpServer kept a parallel
+     * activity map to compensate, which is the drift this consolidation removes.
+     * No-op for unknown sessions (does NOT create an entry).
+     */
+    touch(sessionId) {
+        const conn = this.connections.get(sessionId);
+        if (conn) {
+            conn.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Register a listener invoked when the pool removes a session (idle sweep or
+     * explicit close). httpServer registers one that closes the transport and
+     * drops its table entries, keeping both tables consistent (#167). Listeners
+     * must not throw; any error is logged and swallowed so one bad listener
+     * cannot abort the removal of others.
+     */
+    onSessionEvicted(cb) {
+        this.evictionCallbacks.push(cb);
+    }
+    fireEviction(sessionId) {
+        for (const cb of this.evictionCallbacks) {
+            try {
+                cb(sessionId);
+            }
+            catch (err) {
+                logger.error(`[ConnectionPool] Eviction listener threw for session ${sessionId} (ignoring):`, err);
+            }
+        }
+    }
     /**
      * Check if we can accept a new session (under the concurrent limit)
      * Returns true if limit not reached, false otherwise
@@ -243,9 +305,17 @@ class ActualConnectionPool {
         }
     }
     /**
-     * Shutdown connection for a specific session
+     * Shutdown connection for a specific session.
+     *
+     * `opts.evict` controls whether eviction listeners fire (#167). Pass `true`
+     * when the session itself is ending (idle sweep, explicit session close) so
+     * the transport layer tears down its transport. Leave it false (default) when
+     * the pool entry is being recycled but the MCP session continues, e.g.
+     * switchBudget's slow path which shuts the entry down and immediately
+     * recreates it, or an infra-error drop where the next request re-establishes
+     * the connection: in those cases the transport must survive.
      */
-    async shutdownConnection(sessionId) {
+    async shutdownConnection(sessionId, opts = {}) {
         const conn = this.connections.get(sessionId);
         if (!conn || !conn.initialized) {
             return;
@@ -256,17 +326,23 @@ class ActualConnectionPool {
             if (typeof maybeApi.shutdown === 'function') {
                 await maybeApi.shutdown();
             }
-            conn.initialized = false;
-            this.connections.delete(sessionId);
-            setApiInitialized(false);
-            // NOTE: We do NOT delete the data directory because it's shared across all sessions
-            // Deleting it would cause data loss for other active sessions
             logger.info(`[ConnectionPool] Connection shutdown complete for session: ${sessionId}`);
         }
         catch (err) {
             logger.error(`[ConnectionPool] Error shutting down connection for session ${sessionId}:`, err);
-            // Even on error, the singleton is in an unknown state — don't reuse.
+        }
+        finally {
+            // Remove the entry in all cases so liveness can never report a session
+            // alive after its shutdown was attempted. On error the singleton is in
+            // an unknown state, so we must not leave it reusable either.
+            conn.initialized = false;
+            this.connections.delete(sessionId);
             setApiInitialized(false);
+            // NOTE: We do NOT delete the data directory because it's shared across all sessions
+            // Deleting it would cause data loss for other active sessions
+            if (opts.evict) {
+                this.fireEviction(sessionId);
+            }
         }
     }
     /**
@@ -335,17 +411,20 @@ class ActualConnectionPool {
      * Clean up idle connections that haven't been used recently
      */
     async cleanupIdleConnections() {
-        const now = Date.now();
         const connectionsToRemove = [];
         for (const [sessionId, conn] of this.connections.entries()) {
-            if (now - conn.lastActivity > this.IDLE_TIMEOUT) {
+            if (this.isExpired(conn)) {
                 connectionsToRemove.push(sessionId);
             }
         }
         if (connectionsToRemove.length > 0) {
             logger.info(`[ConnectionPool] Cleaning up ${connectionsToRemove.length} idle connections`);
             for (const sessionId of connectionsToRemove) {
-                await this.shutdownConnection(sessionId);
+                // evict: true so the transport layer tears down the matching transport
+                // in the same window (#167). This is the path that previously drifted:
+                // the pool's autonomous timer removed an entry httpServer's separate
+                // timer knew nothing about.
+                await this.shutdownConnection(sessionId, { evict: true });
             }
         }
     }

package/dist/src/lib/node-polyfills.js

@@ -3,7 +3,14 @@
  *
  * @actual-app/api v26.3.0 introduced `navigator.platform` usage at the module
  * top level (inside the Electron/browser bundle) which crashes on Node.js with
- * `ReferenceError: navigator is not defined`.
+ * `ReferenceError: navigator is not defined`. v26.6.0 additionally reads
+ * `navigator.userAgent` at the top level (`navigator.userAgent.includes(...)`
+ * plus a UAParser call), so the polyfill must define `userAgent` too or the
+ * bundle throws `Cannot read properties of undefined (reading 'includes')`.
+ *
+ * Node 21+ ships a native `navigator` that already carries both fields, so this
+ * polyfill only fires on Node 20 (still inside the documented "Node.js 20+"
+ * support range, and the version several CI workflows run on).
  *
  * This file must be imported BEFORE any `@actual-app/api` import so that the
  * global is defined when the bundle is first evaluated.
@@ -12,6 +19,7 @@ if (typeof globalThis.navigator === 'undefined') {
     Object.defineProperty(globalThis, 'navigator', {
         value: {
             platform: process.platform === 'win32' ? 'Win32' : 'Linux',
+            userAgent: `Node.js/${process.version}`,
         },
         writable: true,
         configurable: true,

package/dist/src/server/httpServer.js

@@ -7,6 +7,7 @@ import logger from '../logger.js';
 import { getLocalIp } from '../utils.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, canAcceptNewSession } from '../actualConnection.js';
+import { connectionPool } from '../lib/ActualConnectionPool.js';
 import observability from '../observability.js';
 import config from '../config.js';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
@@ -75,31 +76,30 @@ bindHost = 'localhost', advertisedUrl) {
         }
     }
     const transports = new Map();
-    const sessionLastActivity = new Map();
     const sessionInitPromises = new Map(); // Track session init completion
-    // Use same timeout as ConnectionPool (SESSION_IDLE_TIMEOUT_MINUTES env var, default: 2 minutes)
-    const idleTimeoutMinutes = parseInt(process.env.SESSION_IDLE_TIMEOUT_MINUTES || '2', 10);
-    const SESSION_TIMEOUT_MS = idleTimeoutMinutes * 60 * 1000;
-    const SESSION_CLEANUP_INTERVAL_MS = 30 * 1000; // Check every 30 seconds
     // safe fallback if index didn't provide implementedTools
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
-    // Session cleanup: check for idle sessions periodically
-    const cleanupInterval = setInterval(async () => {
-        const now = Date.now();
-        const sessionsToCleanup = [];
-        for (const [sessionId, lastActivity] of sessionLastActivity.entries()) {
-            if (now - lastActivity > SESSION_TIMEOUT_MS) {
-                sessionsToCleanup.push(sessionId);
+    // Session liveness and idle timing are owned solely by the connection pool
+    // (#167). httpServer no longer runs its own idle timer or activity map; it
+    // owns only the transport objects. When the pool removes a session (idle
+    // sweep or explicit close) it fires this eviction listener, which tears down
+    // the matching transport in the same window. This is what keeps the two
+    // tables from drifting: no "alive in httpServer, dead in the pool" state, and
+    // no transport object left behind for a session the client abandoned.
+    connectionPool.onSessionEvicted((sessionId) => {
+        const transport = transports.get(sessionId);
+        if (transport) {
+            try {
+                transport.close?.();
+            }
+            catch (err) {
+                logger.debug(`[SESSION] Error closing transport for evicted session ${sessionId} (ignoring): ${err}`);
             }
         }
-        for (const sessionId of sessionsToCleanup) {
-            logger.info(`[SESSION] Cleaning up idle session: ${sessionId}`);
-            transports.delete(sessionId);
-            sessionLastActivity.delete(sessionId);
-            sessionInitPromises.delete(sessionId);
-            await shutdownActualForSession(sessionId);
-        }
-    }, SESSION_CLEANUP_INTERVAL_MS);
+        transports.delete(sessionId);
+        sessionInitPromises.delete(sessionId);
+        logger.info(`[SESSION] Transport torn down for evicted session: ${sessionId}`);
+    });
     // Authentication middleware
     const authenticateRequest = (req, res) => {
         // OIDC mode: mcp-auth middleware has already validated the JWT and populated req.auth.
@@ -333,9 +333,10 @@ bindHost = 'localhost', advertisedUrl) {
                         // Initialize connection pool for this session
                         try {
                             await connectToActualForSession(sid);
-                            // Only add to transports/activity map if connection successful
+                            // Only register the transport if the pool connection succeeded.
+                            // The pool stamped lastActivity when it created the entry, so it
+                            // is already the source of truth for this session's idle clock.
                             transports.set(sid, transport);
-                            sessionLastActivity.set(sid, Date.now());
                             logger.info(`[SESSION] Actual connection initialized for session: ${sid}`);
                             resolveInit?.();
                         }
@@ -370,7 +371,18 @@ bindHost = 'localhost', advertisedUrl) {
                 }
                 return;
             }
-            // sessionId present -> reuse
+            // sessionId present -> reuse. Transport presence is the liveness signal:
+            // the pool's eviction listener (#167) removes the transport the moment a
+            // session is genuinely evicted (idle sweep or explicit close), so a
+            // missing transport means "expired" and a present one means "serve it".
+            //
+            // We deliberately do NOT additionally gate on connectionPool.isLive() here.
+            // A pool entry can be absent while the MCP session is still perfectly
+            // usable: after a transient infra error the adapter drops the pool entry
+            // (without evicting the transport) so the next call re-establishes it via
+            // the legacy fallback. Rejecting those requests as "expired" would force a
+            // needless client re-initialize on every transient blip, re-introducing
+            // the session churn this server works to avoid.
             let transport = transports.get(sessionId);
             if (!transport) {
                 // Check if session is currently being initialized
@@ -431,8 +443,8 @@ bindHost = 'localhost', advertisedUrl) {
                     return;
                 }
             }
-            // Update activity timestamp for valid session
-            sessionLastActivity.set(sessionId, Date.now());
+            // Refresh the pool's idle clock for this session (single source of truth, #167).
+            connectionPool.touch(sessionId);
             // Run in AsyncLocalStorage context so tools and the adapter can access
             // sessionId (pool branch, #134) and allowedBudgets (ACL enforcement, #156).
             const allowedBudgets = req.allowedBudgets;
@@ -457,7 +469,7 @@ bindHost = 'localhost', advertisedUrl) {
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'No session id' }, id: null });
             return;
         }
-        sessionLastActivity.set(sessionId, Date.now()); // Track activity
+        connectionPool.touch(sessionId); // Refresh the pool's idle clock (#167)
         const transport = transports.get(sessionId);
         if (!transport) {
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Transport not ready' }, id: null });
@@ -538,12 +550,13 @@ bindHost = 'localhost', advertisedUrl) {
     // Cleanup on server shutdown
     const cleanup = async () => {
         logger.info('[SERVER] Shutting down, cleaning up sessions...');
-        clearInterval(cleanupInterval);
-        for (const sessionId of transports.keys()) {
+        // Snapshot the keys: shutdownActualForSession evicts, and the eviction
+        // listener deletes from `transports`, so iterating the live map would
+        // mutate it mid-iteration.
+        for (const sessionId of [...transports.keys()]) {
             await shutdownActualForSession(sessionId);
         }
         transports.clear();
-        sessionLastActivity.clear();
         sessionInitPromises.clear();
         // Also shut down the shared/pooled connections
         await shutdownActual();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "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/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_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/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/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/pool_liveness.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/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",