actual-mcp-server 0.25.2 → 0.26.1

package/README.md

@@ -15,7 +15,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets an
 
 **What you can ask it:** "How much did I spend on groceries last month, by payee?", "Add a $47.50 grocery transaction at Whole Foods to my checking account.", "Move $200 from Dining Out to Emergency Fund for this month."
 
-**84 tools** across accounts, transactions, budgets, rules, schedules and more, over stdio or HTTP, with Bearer token or OIDC auth, per-user budget access, up to 15 concurrent sessions, and automatic retry of transient Actual errors (3 attempts, exponential backoff; deletes and merges are never retried).
+**85 tools** across accounts, transactions, budgets, rules, schedules and more, over stdio or HTTP, with Bearer token or OIDC auth, per-user budget access, up to 15 concurrent sessions, and automatic retry of transient Actual errors (3 attempts, exponential backoff; deletes and merges are never retried).
 
 ## Pick your path
 
@@ -98,7 +98,7 @@ Every tool, with its description and caveats, is in the [tools reference](docs/r
 
 ### Reducing the tool surface
 
-All 84 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer. A tool that is not published is also refused if a client calls it by name.
+All 85 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer. A tool that is not published is also refused if a client calls it by name.
 
 <!-- BEGIN GENERATED: tools-summary -->
 <!-- Generated from dist/src/lib/toolsets.js by `npm run docs:gen`. Do not edit. -->
@@ -109,14 +109,14 @@ All 84 tools are published by default. Chat clients with a small tool budget (Ge
 | `analysis` | 7 | Summaries, aggregates and balances |
 | `budget` | 10 | Budget months, amounts, carryover, holds, transfers, batch updates and notes |
 | `rules` | 7 | Rules and payee rules, including `actual_rules_create_batch` |
-| `schedules` | 4 | Scheduled transactions |
+| `schedules` | 5 | Scheduled transactions |
 | `structure` | 21 | Accounts, account groups, categories, category groups, payees and tags |
 | `query` | 1 | `actual_query_run` (SELECT only) |
 | `admin` | 6 | Budget switching, import, export, bank sync and session management |
 
 The `chat` preset publishes 12 tools: `actual_get_context`, `actual_query_run`, `actual_transactions_update_batch`, `actual_budget_updates_batch`, `actual_rules_create_batch`, `actual_transactions_create`, `actual_transactions_update`, `actual_transactions_delete`, `actual_rules_create`, `actual_budgets_transfer`, `actual_budgets_setAmount` and `actual_budgets_getMonth`.
 
-`MCP_READ_ONLY=true` hides and refuses 48 write-capable tools and leaves 36 published.
+`MCP_READ_ONLY=true` hides and refuses 48 write-capable tools and leaves 37 published.
 <!-- END GENERATED: tools-summary -->
 
 Example: a chat assistant with two extra tools.
@@ -169,4 +169,4 @@ MIT, see [LICENSE](LICENSE). Built on [Actual Budget](https://actualbudget.org/)
 
 ---
 
-**Version:** 0.25.2 | **Tool Count:** 84 (verified LibreChat-compatible)
+**Version:** 0.26.1 | **Tool Count:** 85 (verified LibreChat-compatible)

package/dist/src/actualToolsManager.js

@@ -57,6 +57,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_rules_get',
     'actual_rules_update',
     'actual_schedules_create',
+    'actual_schedules_dates',
     'actual_schedules_delete',
     'actual_schedules_get',
     'actual_schedules_update',

package/dist/src/config.js

@@ -89,6 +89,10 @@ export const configSchema = z.object({
     // 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.
     ALLOW_INSECURE_UPSTREAM: z.string().optional().transform(val => val === 'true'),
+    // #620: upstream @actual-app/api logs at its own info/debug level (sync chatter, and on every
+    // import or bank sync a dump of each reconciled transaction) unless init is told otherwise.
+    // Off by default; `=== 'true'` fails safe, since turning it on is what carries the risk.
+    ACTUAL_API_VERBOSE: z.string().optional().transform(val => val === 'true'),
     MCP_BRIDGE_DATA_DIR: z.string().default('./actual-data'),
     // #332: where actual_budgets_export writes budget zips. A budget export is
     // megabytes of binary, so the tool returns a PATH plus metadata rather than

package/dist/src/index.js

@@ -5,12 +5,16 @@
 // guard cannot live in bin/ alone. It is a side-effect import: the module's top-level
 // `enforceNodeVersion()` fires here, exactly once.
 import './lib/node-version-guard.js';
+// #622: MUST be the second import. Registers the unhandledRejection and uncaughtException
+// handlers before any other module evaluates. They write gated records only (no reason,
+// message or stack) and get the logger later through attachProcessLogger below.
+import { attachProcessLogger } from './lib/processHandlersInstall.js';
 import { getMcpServerVersion } from './lib/mcp-version.js';
 import path from 'node:path';
 import { z } from 'zod';
-import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
 import { buildServerInstructions } from './lib/serverInstructions.js';
 import { format } from 'node:util';
+import { writeSync } from 'node:fs';
 /*
  * #277 / #541: this module's version comes from `getMcpServerVersion()` (src/lib/mcp-version.ts),
  * which `--version`, `--help`, the startup banner, the MCP initialize `serverInfo.version` and
@@ -22,54 +26,6 @@ import { format } from 'node:util';
  * ignored `VERSION`, so a Docker image built as `X-dev-abc` printed plain `X` from
  * `--version` while clients saw `X-dev-abc`. One reader means one string.
  */
-// Add global error handlers
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('=== UNHANDLED REJECTION ===');
-    console.error('Promise:', promise);
-    console.error('Reason:', reason);
-    if (reason instanceof Error) {
-        console.error('Stack:', reason.stack);
-    }
-    console.error('===========================');
-    // #275 backstop. The guard above catches both entry points, but a consumer that
-    // imports this package as a library reaches neither. Import attributes are the one
-    // construct here that fails on an under-floor Node, and it fails asynchronously,
-    // so name the real cause rather than letting the reader chase a packaging bug.
-    if (reason?.code === 'ERR_IMPORT_ASSERTION_TYPE_MISSING') {
-        console.error(`⚠️  This almost certainly means Node ${process.version} is too old.`);
-        console.error('⚠️  actual-mcp-server requires the Node version in package.json "engines".');
-        console.error('⚠️  Import attributes (`with { type: "json" }`) need Node 22 or newer.');
-    }
-    if (isKnownBenignRejection(reason)) {
-        console.error('⚠️  Known Actual API domain error escaped to unhandledRejection:');
-        console.error('⚠️  ' + String(reason));
-        console.error('⚠️  Server will continue running. The caller received an error response.');
-        return;
-    }
-    process.exit(1);
-});
-process.on('uncaughtException', (error) => {
-    const errMsg = String(error?.message || error);
-    const errType = error?.type;
-    // Bank sync errors from GoCardless/SimpleFIN can surface as uncaughtException
-    // from within the @actual-app/api SDK when the provider API returns an error
-    // asynchronously (e.g. RATE_LIMIT_EXCEEDED from GoCardless/Nordigen).
-    // These are non-fatal — the server should survive and continue serving requests.
-    if (errType === 'BankSyncError' ||
-        errMsg.includes('BankSyncError') ||
-        errMsg.includes('NORDIGEN_ERROR') ||
-        errMsg.includes('RATE_LIMIT_EXCEEDED') ||
-        errMsg.includes('Rate limit exceeded') ||
-        errMsg.includes('Failed syncing account') ||
-        errMsg.includes('GoCardless') ||
-        errMsg.includes('SimpleFIN')) {
-        console.error('⚠️  [BANK SYNC] Non-fatal bank sync error surfaced as uncaughtException (server continues):');
-        console.error('⚠️  ' + errMsg);
-        return;
-    }
-    console.error('Uncaught Exception:', error);
-    process.exit(1);
-});
 // Minimal early help handling before any side-effectful modules (prevents dotenv from running on --help)
 const argsEarly = process.argv.slice(2);
 // Set MCP_STDIO_MODE before the async IIFE so it is in place when src/logger.ts is first
@@ -191,7 +147,7 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         import('./actualConnection.js'),
         import('./lib/ActualMCPConnection.js'),
     ]);
-    const [{ startHttpServer }, { startStdioServer }, { enforceHttpAuthPosture, findWeakTokenVars }, loggerModule, utilsModule, actualToolsManagerModule,] = await Promise.all([
+    const [{ startHttpServer }, { startStdioServer }, { enforceHttpAuthPosture, findWeakTokenVars, describeAuthMode }, loggerModule, utilsModule, actualToolsManagerModule,] = await Promise.all([
         import('./server/httpServer.js'),
         import('./server/stdioServer.js'),
         import('./lib/authPosture.js'),
@@ -200,6 +156,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         import('./actualToolsManager.js'),
     ]);
     const logger = loggerModule.default;
+    // #622: the process handlers log survivable events through the logger from here on.
+    const { createModuleLogger } = await import('./lib/loggerFactory.js');
+    attachProcessLogger(createModuleLogger('PROCESS'));
     const { getLocalIp } = utilsModule;
     const actualToolsManager = actualToolsManagerModule.default;
     // #541: the build-time VERSION, or the root package version plus a dev suffix on a
@@ -213,7 +172,7 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
     const useStdio = args.includes('--stdio');
     const useTestActualConnection = args.includes('--test-actual-connection');
     const useTestMcpClient = args.includes('--test-mcp-client');
-    const SERVER_DESCRIPTION = 'Bridge MCP server exposing Actual finance API to LibreChat.';
+    const SERVER_DESCRIPTION = 'Actual Budget over the Model Context Protocol';
     async function main() {
         // Mutual exclusion — stdio and http are incompatible transports
         if (useHttp && useStdio) {
@@ -359,7 +318,16 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
             logger.info('---------');
             logger.info('🟡 MCP SERVER INFO');
             logger.info(`• Server Description:   ${SERVER_DESCRIPTION}`);
-            logger.info(`• OAuth Required:       false`);
+            // #626: the real mode, computed with the same blank-means-off rules as the
+            // posture check. MCP_SSE_AUTHORIZATION stays untrimmed: a whitespace-only
+            // value is still a live credential there.
+            const { staticTokensConfigured } = await import('./auth/static-tokens.js');
+            const authMode = describeAuthMode({
+                oidcEnabled: process.env.AUTH_PROVIDER === 'oidc',
+                hasStaticTokens: staticTokensConfigured(process.env.MCP_STATIC_TOKENS),
+                hasSseAuthorization: !!process.env.MCP_SSE_AUTHORIZATION,
+            });
+            logger.info(`• Auth mode:            ${authMode}`);
             logger.info(`• Capabilities:         ${Object.keys(capabilities).join(', ')}`);
             logger.info(`• Tools:                ${implementedTools.join(', ') || 'none'}`);
             logger.info(`• Server Instructions:  ${serverInstructionsText}`);
@@ -390,4 +358,12 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         logger.error(`Failed to start Actual MCP bridge: ${err?.message || String(err)}`);
         process.exit(1);
     });
-})();
+})().catch((err) => {
+    // #622: the prelude above (dotenv, the dynamic imports, the logger) runs before main(), so
+    // its failures never reach main().catch. Without this catch they escape as an
+    // unhandledRejection, whose gated record drops the message: a missing package or a broken
+    // build would name no module. Same residual as main().catch: startup text only. The logger
+    // may not exist yet, so this writes synchronously to stderr, never stdout.
+    writeSync(2, `Failed to start Actual MCP bridge: ${err?.message || String(err)}\n`);
+    process.exit(1);
+});

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

@@ -5,7 +5,7 @@ import api from '@actual-app/api';
 // cannot expose its named exports via static import syntax. At runtime the default import
 // IS module.exports, so all methods are accessible as properties.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, mergeTransactions: rawMergeTransactions, getPayeeRules: rawGetPayeeRules, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, mergeTransactions: rawMergeTransactions, getPayeeRules: rawGetPayeeRules, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, getScheduleDates: rawGetScheduleDates, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
@@ -13,13 +13,13 @@ import observability from '../observability.js';
 import { retry, isRetryableError, isRateLimitError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
 import { markInitFailure } from './init-failure.js';
-import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg, errorLogFields } from './errors.js';
+import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg, errorLogFields, isPreflightRefusal } from './errors.js';
 import { amountOpMismatch } from './schemas/schedule-amount.js';
 import { findMatchingRule } from './rule-matching.js';
 import logger from '../logger.js';
 import { checkServerVersionOnce } from './server-version-guard.js';
 import config from '../config.js';
-import { parseBudgetRegistry } from './budget-registry.js';
+import { formatBudgetRegistrySummary, logSafeOrigin, parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
 import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
@@ -38,8 +38,8 @@ const budgetRegistry = parseBudgetRegistry(process.env, {
     encryptionPassword: config.ACTUAL_BUDGET_PASSWORD,
 });
 setLoginsSpanServers(new Set([...budgetRegistry.values()].map((b) => JSON.stringify([b.serverUrl, b.password || '']))).size > 1);
-logger.info(`[ADAPTER] Budget registry: ${budgetRegistry.size} budget(s) — ` +
-    [...budgetRegistry.values()].map(b => `"${b.name}" (${b.serverUrl})`).join(', '));
+// #621: counts and schemes only; budget names and server hosts stay out of the startup log.
+logger.info(`[ADAPTER] ${formatBudgetRegistrySummary(budgetRegistry)}`);
 /**
  * Per-session active budget. Map from sessionId to lowercased budget key
  * (matches the keys in budgetRegistry).
@@ -276,7 +276,7 @@ function loginOf(budget) {
 async function loadBudgetOnItsServer(budget) {
     const login = loginOf(budget);
     if (!isApiLoggedInTo(login)) {
-        logger.info(`[ADAPTER] logging the api in to ${budget.serverUrl} before loading "${budget.name}"`);
+        logger.info(`[ADAPTER] logging the api in to ${logSafeOrigin(budget.serverUrl)} before loading "${budget.name}"`);
         await withAuthRetry(() => initApiLoggedIn(config.MCP_BRIDGE_DATA_DIR, login, 'init'));
     }
     await loadBudgetTracked(budget.syncId, budget.encryptionPassword);
@@ -828,7 +828,7 @@ async function initActualApiForOperation() {
     try {
         const budget = getActiveBudgetConfig();
         const DATA_DIR = config.MCP_BRIDGE_DATA_DIR;
-        logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${budget.serverUrl})`);
+        logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${logSafeOrigin(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).
         // Bound EACH init attempt with the op timeout (#270), inside withAuthRetry:
@@ -925,7 +925,7 @@ async function shutdownActualApi(opts) {
         setApiInitialized(false);
     }
 }
-import { BANK_SYNC_SETTLE_MS, SPLIT_VERIFY_INTERVAL_MS, SPLIT_VERIFY_TIMEOUT_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
+import { SCHEDULE_DATES_CAP, SPLIT_VERIFY_INTERVAL_MS, SPLIT_VERIFY_TIMEOUT_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.
@@ -2958,6 +2958,56 @@ export async function getSchedules() {
         return Array.isArray(raw) ? raw : [];
     });
 }
+/**
+ * #479: the dates a schedule falls on, expanded by Actual itself (`api.getScheduleDates`, new in
+ * 26.11.0), so month ends, patterns, intervals and the weekend move match the Actual UI.
+ *
+ * One session: the schedule listing and the expansion run inside the same withActualApi, never
+ * through adapter.getSchedules (the api lock is not reentrant). Upstream takes the schedule row's
+ * `date` field (`scheduleModel.toExternal` maps it from `_date`), a single date or a RecurConfig.
+ * A count is ALWAYS sent, one above what is returned, so an open-ended recurrence returns its next
+ * dates instead of upstream's "needs an end or a count" error, and the extra date is how
+ * `truncated` knows that more dates exist after the last one returned. With both `end` and
+ * `count`, upstream stops at whichever comes first.
+ *
+ * The two refusals a caller can fix are typed and checked BEFORE the upstream call, never chosen
+ * by matching upstream message text: an `end` before `start` (only when both are given; with
+ * `start` omitted upstream uses its own today and its error passes through), and a stored
+ * `skipWeekend` without `weekendSolveMode`. Any other upstream error passes through unchanged.
+ */
+export async function getScheduleDates(scheduleId, opts = {}) {
+    if (opts.start !== undefined && opts.end !== undefined && opts.end < opts.start) {
+        throw new OutOfRangeRefusal(`end (${opts.end}) is before start (${opts.start}); end must be on or after start.`, opts.end);
+    }
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.schedules.dates').catch(() => { });
+        const schedules = await withConcurrency(() => retry(() => rawGetSchedules(), { retries: 2, backoffMs: 200 }));
+        const schedule = Array.isArray(schedules) ? schedules.find((s) => s?.id === scheduleId) : undefined;
+        if (!schedule) {
+            throw new NotFoundRefusal('Schedule', scheduleId, 'actual_schedules_get');
+        }
+        const recur = schedule.date;
+        if (recur && typeof recur === 'object' && recur.skipWeekend && !recur.weekendSolveMode) {
+            throw new OutOfRangeRefusal(`Schedule ${scheduleId} has skipWeekend set without weekendSolveMode, so its dates cannot be ` +
+                "computed. Set weekendSolveMode to 'before' or 'after' with actual_schedules_update.", 'weekendSolveMode');
+        }
+        const limit = Math.min(opts.count ?? SCHEDULE_DATES_CAP, SCHEDULE_DATES_CAP);
+        const raw = await withConcurrency(() => rawGetScheduleDates(schedule.date, {
+            ...(opts.start !== undefined ? { start: opts.start } : {}),
+            ...(opts.end !== undefined ? { end: opts.end } : {}),
+            count: limit + 1,
+        }));
+        const all = Array.isArray(raw) ? raw : [];
+        const dates = all.slice(0, limit);
+        return {
+            schedule_id: scheduleId,
+            name: typeof schedule.name === 'string' ? schedule.name : null,
+            dates,
+            count: dates.length,
+            truncated: all.length > limit,
+        };
+    });
+}
 /**
  * #547: upstream builds a schedule's rule with one `is` condition per field and STRINGIFIES the
  * value on create (`scheduleModel.fromExternal` in loot-core/src/server/api-models.ts), so an
@@ -3863,75 +3913,73 @@ export async function getFinancialAnalysisSnapshot(params) {
 // Imported for internal use by runQuery and re-exported (unit-tested directly).
 import { parseWhereClause, nameConditionLookups, nameConditionHintLines } from './actual-adapter/query.js';
 export { parseWhereClause };
+function normaliseBankSyncReport(raw) {
+    const r = (raw && typeof raw === 'object' ? raw : {});
+    const list = (v) => (Array.isArray(v) ? v.map(String) : []);
+    return {
+        newTransactions: list(r.newTransactions),
+        matchedTransactions: list(r.matchedTransactions),
+        updatedAccounts: list(r.updatedAccounts),
+    };
+}
+const BANK_SYNC_SETUP_HINT = 'To use bank sync, link your account(s) with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ' +
+    'See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.';
 export async function runBankSync(accountId) {
     try {
-        return await withActualApi(async () => {
+        // #548: a write, so the import and the bank_sync_status row reach the server. In pooled
+        // mode withActualApiWrite pushes once after a RESOLVED sync and never in a rejection path;
+        // on the fallback (init/op/shutdown) path, shutdown still syncs whatever a partial
+        // all-accounts run imported before it failed. Not queueWriteOperation: bank sync is one
+        // upstream call, and the queue's per-call bound has no env knob, which #619 owns.
+        return await withActualApiWrite(async () => {
             observability.incrementToolCall('actual.bank.sync').catch(() => { });
-            // Bank sync must NOT be retried — retrying could import duplicate transactions.
+            // Bank sync must NOT be retried: retrying could import duplicate transactions.
             // Pass { accountId } for a specific account, or {} to sync all linked accounts.
             const args = accountId != null ? { accountId } : {};
-            // Pre-check: verify bank-linked accounts exist before calling rawRunBankSync.
-            // The SDK silently resolves void for local accounts (account_sync_source: null),
-            // which would otherwise be misreported as success and cause an unnecessary 30s wait.
+            // Pre-check: upstream resolves silently for a local account and skips a closed one,
+            // which would read as an empty but successful sync. Refusals are typed (#377).
             if (accountId != null) {
-                // Per-account check: verify the specified account is bank-linked.
                 const { data: acctRows } = await rawRunQuery(api.q('accounts')
-                    .select(['account_sync_source', 'name'])
+                    .select(['account_sync_source', 'account_id', 'name', 'closed'])
                     .filter({ id: accountId, tombstone: false }));
                 const acct = acctRows?.[0];
                 if (!acct) {
-                    throw new Error(`Bank sync failed: Account not found (id: ${accountId})`);
+                    // Only reachable on a race: the tool resolves the id with verifyExists first (#388).
+                    throw new NotFoundRefusal('Account', accountId, 'actual_accounts_list');
                 }
                 if (!acct.account_sync_source) {
-                    throw new Error(`Bank sync failed: Account "${acct.name}" is a local account — not configured for bank sync. ` +
-                        `To use bank sync, link your account with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
-                        `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
+                    throw new OutOfRangeRefusal(`Bank sync failed: Account "${acct.name}" is a local account, not configured for bank sync. ${BANK_SYNC_SETUP_HINT}`, accountId);
+                }
+                if (acct.closed) {
+                    throw new OutOfRangeRefusal(`Bank sync failed: Account "${acct.name}" is closed; Actual skips closed accounts in bank sync. Reopen it in Actual to sync it.`, accountId);
+                }
+                // Upstream also skips an account without a provider account id (and one without a bank
+                // row, which AQL does not expose, so that rarer half-link still reads as an empty sync).
+                if (!acct.account_id) {
+                    throw new OutOfRangeRefusal(`Bank sync failed: Account "${acct.name}" has a ${acct.account_sync_source} link with no provider account; Actual skips it in bank sync. Re-link it in the Actual Budget UI.`, accountId);
                 }
             }
             else {
-                // Global check: verify at least one bank-linked account exists across the budget.
                 const { data: allAccounts } = await rawRunQuery(api.q('accounts')
-                    .select(['account_sync_source'])
+                    .select(['account_sync_source', 'account_id', 'closed'])
                     .filter({ tombstone: false }));
-                const linkedCount = allAccounts?.filter(a => a.account_sync_source).length ?? 0;
-                if (linkedCount === 0) {
-                    throw new Error(`Bank sync failed: No accounts are configured for bank sync. ` +
-                        `To use bank sync, link your account(s) with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
-                        `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
-                }
-            }
-            // rawRunBankSync returns void immediately; the actual provider call runs on
-            // a background promise inside the SDK and surfaces errors as unhandledRejection.
-            // We install a temporary listener to capture any BankSyncError and re-throw.
-            let capturedRejection = null;
-            const rejectionHandler = (reason) => {
-                const msg = reason?.message || String(reason);
-                if (reason?.type === 'BankSyncError' ||
-                    msg.includes('BankSyncError') ||
-                    msg.includes('NORDIGEN_ERROR') ||
-                    msg.includes('Rate limit exceeded') ||
-                    msg.includes('Failed syncing account') ||
-                    msg.includes('GoCardless') ||
-                    msg.includes('SimpleFIN')) {
-                    capturedRejection = reason;
+                const linked = (allAccounts ?? []).filter(a => a.account_sync_source && a.account_id);
+                if (!linked.some(a => !a.closed)) {
+                    throw new OutOfRangeRefusal(linked.length > 0
+                        ? 'Bank sync failed: Every bank-linked account is closed; Actual skips closed accounts in bank sync. Reopen one in Actual to sync it.'
+                        : `Bank sync failed: No accounts are configured for bank sync. ${BANK_SYNC_SETUP_HINT}`, 'all');
                 }
-            };
-            process.on('unhandledRejection', rejectionHandler);
-            try {
-                await rawRunBankSync(args);
-                // Wait for the SDK's background promise to resolve/reject.
-                // Provider errors (rate limits, auth failures) arrive in < 3s in practice;
-                // BANK_SYNC_SETTLE_MS gives a comfortable margin to catch them.
-                await new Promise(resolve => setTimeout(resolve, BANK_SYNC_SETTLE_MS));
-                if (capturedRejection !== null)
-                    throw capturedRejection;
-            }
-            finally {
-                process.off('unhandledRejection', rejectionHandler);
             }
+            // Since 26.11 upstream awaits the provider and rejects this call itself, so the old
+            // settle sleep and the process-wide unhandledRejection listener are gone (#548).
+            return normaliseBankSyncReport(await rawRunBankSync(args));
         });
     }
     catch (error) {
+        // A typed refusal is already the caller-facing answer; the text mapping below would
+        // rewrite "not configured" into a generic message and lose the brand.
+        if (isPreflightRefusal(error))
+            throw error;
         const errorMsg = error?.message || String(error);
         // Network / connectivity errors (includes "fetch failed" from Node.js native fetch)
         if (errorMsg.includes('fetch failed') ||
@@ -3952,22 +4000,16 @@ export async function runBankSync(accountId) {
                 `To use bank sync, you must first link your account(s) with a supported provider (GoCardless or SimpleFIN) in the Actual Budget UI. ` +
                 `See https://actualbudget.org/docs/advanced/bank-sync for setup instructions.`);
         }
-        // GoCardless / SimpleFIN provider-level errors
-        // BankSyncError objects (from @actual-app/api) may have { type, category, code, message }
-        const bankSyncCategory = error?.category || '';
-        if (errorMsg.includes('Rate limit exceeded') ||
-            errorMsg.includes('RATE_LIMIT_EXCEEDED') ||
-            bankSyncCategory === 'RATE_LIMIT_EXCEEDED') {
-            const reset = error?.details?.rateLimitHeaders?.http_x_ratelimit_account_success_reset;
-            const retryIn = reset ? ` Retry in ~${Math.ceil(Number(reset) / 60)} minute(s).` : '';
-            throw new Error(`Bank sync failed: GoCardless rate limit exceeded for this account.${retryIn} ` +
+        // Provider errors. Since 26.11 the rejection is a plain Error with `.code` only (no
+        // category, type or details), so the upstream message is the one rate-limit signal.
+        if (errorMsg.includes('Rate limit exceeded')) {
+            throw new Error(`Bank sync failed: GoCardless rate limit exceeded for this account. ` +
                 `(NORDIGEN RATE_LIMIT_EXCEEDED: account success quota exhausted)`);
         }
-        if (error?.type === 'BankSyncError' ||
-            errorMsg.includes('BankSyncError') ||
-            errorMsg.includes('NORDIGEN_ERROR') ||
-            errorMsg.includes('Failed syncing account')) {
-            throw new Error(`Bank sync failed: Provider error: ${errorMsg}`, { cause: error });
+        if (errorMsg.includes('Failed syncing account')) {
+            // The message names only the account; `.code` is the one hint at why (re-link or retry).
+            const code = typeof error?.code === 'string' && error.code ? ` (code ${error.code})` : '';
+            throw new Error(`Bank sync failed: Provider error: ${errorMsg}${code}`, { cause: error });
         }
         throw new Error(`Bank sync failed: ${errorMsg}`, { cause: error }); // #452: keep the brand
     }
@@ -4036,6 +4078,9 @@ export async function switchBudget(name) {
     };
     if (!found)
         throw notFound();
+    // #628: tool results show the server origin only, never a userinfo credential, path or query.
+    // `found` keeps the raw URL, which the login below still needs.
+    const shownServerUrl = logSafeOrigin(found.serverUrl);
     // ACL enforcement: the target budget must be in this session's allowedBudgets.
     // OIDC mode: explicit ACL required. #572: any mode whose request carries a
     // restricting list (MCP_STATIC_TOKENS) is checked against it too; with no list
@@ -4087,7 +4132,7 @@ export async function switchBudget(name) {
         setSessionBudget(sessionId, key);
         setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
         logger.info(`[ADAPTER] switchBudget no-op for session ${sessionId}: already on "${found.name}" (${found.syncId})`);
-        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+        return { name: found.name, syncId: found.syncId, serverUrl: shownServerUrl };
     }
     if (sameAuth) {
         // Same server + creds, different syncId. Reload budget file in place.
@@ -4108,8 +4153,8 @@ export async function switchBudget(name) {
         connectionPool.updateLoadedSyncId(sessionId, found.syncId);
         setSessionBudget(sessionId, key);
         setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
-        logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
-        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+        logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${logSafeOrigin(found.serverUrl)}`);
+        return { name: found.name, syncId: found.syncId, serverUrl: shownServerUrl };
     }
     // #581: hold this session's slot across the window between releasing the old entry and
     // creating the new one, so a concurrent initialize cannot take it and leave this session over
@@ -4178,8 +4223,8 @@ export async function switchBudget(name) {
         if (holdsSlot)
             connectionPool.releaseReservation(sessionId);
     }
-    logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
-    return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+    logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${logSafeOrigin(found.serverUrl)}`);
+    return { name: found.name, syncId: found.syncId, serverUrl: shownServerUrl };
 }
 /**
  * Clear the per-session budget state for a session, so the map does not
@@ -4200,7 +4245,8 @@ export function getBudgetRegistry() {
     return [...budgetRegistry.values()].filter(b => !allowed || allowed.includes(b.syncId)).map(b => ({
         name: b.name,
         syncId: b.syncId,
-        serverUrl: b.serverUrl,
+        // #628: origin only; the registry entry itself keeps the raw URL for the login.
+        serverUrl: logSafeOrigin(b.serverUrl),
         hasEncryption: !!b.encryptionPassword,
     }));
 }
@@ -4573,6 +4619,7 @@ export default {
     getIDByName,
     getServerVersion,
     getSchedules,
+    getScheduleDates,
     createSchedule,
     updateSchedule,
     deleteSchedule,

package/dist/src/lib/apiLogin.js

@@ -1,4 +1,5 @@
 import api from '@actual-app/api';
+import config from '../config.js';
 import { withOpTimeout } from './opTimeout.js';
 import { setApiLogin, setLoadedBudgetSyncId, registerBudgetLoad, loginsSpanServers } from './apiState.js';
 import { createModuleLogger } from './loggerFactory.js';
@@ -38,6 +39,10 @@ let upstreamLib = null;
  *     entries are still valid.
  *  3. log in, then record the login.
  *
+ * Every init passes `verbose` explicitly (#620): upstream only sets its process-global verbose
+ * mode when the key is present, and its default is on, which writes reconciled transactions into
+ * our log through `wireConsoleAndDebug`.
+ *
  * Bounded by the op timeout (#270). Callers that retry on the auth rate limit wrap this whole
  * call in `withAuthRetry`, so each attempt is bounded on its own.
  *
@@ -72,6 +77,7 @@ export async function initApiLoggedIn(dataDir, login, label) {
         dataDir,
         serverURL: login.serverUrl,
         password: login.password,
+        verbose: config.ACTUAL_API_VERBOSE,
     });
     const lib = await withOpTimeout(() => loggingIn, label);
     if (lib && typeof lib.send === 'function')
@@ -109,7 +115,7 @@ async function initOverFetchedLogin(dataDir, login, label) {
         }
     }
     // `password: ''` is upstream's no-credential init (it signs in only on a truthy password).
-    const pointing = api.init({ dataDir, serverURL: login.serverUrl, password: '' });
+    const pointing = api.init({ dataDir, serverURL: login.serverUrl, password: '', verbose: config.ACTUAL_API_VERBOSE });
     registerBudgetLoad(pointing);
     const lib = await withOpTimeout(() => pointing, label);
     if (!lib || typeof lib.send !== 'function')

package/dist/src/lib/authPosture.js

@@ -218,3 +218,20 @@ export function enforceHttpAuthPosture(input, log = logger, exit = process.exit)
     }
     return decision;
 }
+/**
+ * One word naming the HTTP auth mode for the startup banner (#626). Precedence
+ * mirrors the listen callback's posture lines in httpServer.ts: OIDC, then the
+ * static token map, then the single shared bearer token, then none. With both
+ * token variables set this reports `static`, as the ticket specifies; the
+ * listen callback still names the extra unrestricted token, and #623 replaces
+ * the banner. Never prints an issuer, token or principal.
+ */
+export function describeAuthMode(input) {
+    if (input.oidcEnabled)
+        return 'oidc';
+    if (input.hasStaticTokens)
+        return 'static';
+    if (input.hasSseAuthorization)
+        return 'bearer';
+    return 'none';
+}