Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛎️ fix: Preflight MCP Readiness for Scheduled Chats (#15782)
Danny Avila442d477acff9
diff --git a/CONTEXT.md b/CONTEXT.mdindex 78f0f13a6a..1fa1202774 100644--- a/CONTEXT.md+++ b/CONTEXT.md@@ -1,5 +1,7 @@# Domain language+- **Scheduled run admission**: The claimed-occurrence phase that rehydrates the owner, validates current schedule policy and agent reachability, resolves files and MCP readiness, and only then competes for durable generation capacity. It owns cancellation and lease revalidation until a generation slot is reserved; a slow or failed readiness check never occupies generation capacity.+- **Attached code environment**: A principal- or deployment-authorized stateful workspace owned by an outbound `librechat-code` worker on a user-chosen machine or VM. LibreChat selects it and enforces approval policy, Code API authenticates and dispatches to it, and the worker's local sandbox and capability flags remain the final execution ceiling. The environment interface is runtime-neutral: native SRT, WSL2, Docker/NsJail, and future adapters expose the same workspace operations without leaking host paths or runtime configuration into agent tools.- **Agent run envelope**: the versioned, JSON-safe request contract created after ingress authentication and protocol validation but before agent, provider, tool, or MCP initialization. It carries only the validated protocol payload and the minimum trusted principal identifiers. The execution host rehydrates all runtime state from those identifiers.- **Agent execution context**: runtime-only, transport-free state rehydrated beside an Agent run envelope. It contains the authenticated user, application configuration, normalized request metadata, and resolved conversation facts needed by initialization, but never Express request/response objects or serialized credentials.diff --git a/api/server/routes/schedules.js b/api/server/routes/schedules.jsindex 161629583c..d5cc2b1ba5 100644--- a/api/server/routes/schedules.js+++ b/api/server/routes/schedules.js@@ -34,6 +34,7 @@ const checkSchedulesCreate = generateCheckAccess({});const handlers = createSchedulesHandlers({+ preflightMCP: require('~/server/services/Schedules/mcp'),methods,getLimits,// Full fire-equivalent access check (not mere existence): the body-based agentdiff --git a/api/server/services/Schedules/index.js b/api/server/services/Schedules/index.jsindex 1671c7ce2d..4e9c10101c 100644--- a/api/server/services/Schedules/index.js+++ b/api/server/services/Schedules/index.js@@ -22,6 +22,7 @@ function getService() {const isUserDeleting = async (userId) => !(await methods.isAgentTriggerPrincipalActive(userId));service = createSchedulesService({+ preflightMCP: require('./mcp'),methods,getAppConfig,findUserById: (userId) =>diff --git a/api/server/services/Schedules/index.spec.js b/api/server/services/Schedules/index.spec.jsindex 194af1ea68..58216d96cb 100644--- a/api/server/services/Schedules/index.spec.js+++ b/api/server/services/Schedules/index.spec.js@@ -9,6 +9,7 @@ jest.mock('@librechat/api', () => ({jest.mock('mongoose', () => ({ models: {} }));jest.mock('~/server/services/Config/app', () => ({ getAppConfig: jest.fn() }));jest.mock('~/server/services/Agents/triggers', () => ({ enqueueAgentTrigger: jest.fn() }));+jest.mock('./mcp', () => jest.fn());jest.mock('./access', () => ({ resolveAgentFireAccess: jest.fn() }));jest.mock('~/models', () => ({ isAgentTriggerPrincipalActive: jest.fn() }));diff --git a/api/server/services/Schedules/mcp.js b/api/server/services/Schedules/mcp.jsnew file mode 100644index 0000000000..c699936159--- /dev/null+++ b/api/server/services/Schedules/mcp.js@@ -0,0 +1,38 @@+const { createScheduleMCPPreflight } = require('@librechat/api');+const { CacheKeys } = require('librechat-data-provider');+const { getMCPManager, getMCPServersRegistry, getFlowStateManager } = require('~/config');+const { getAppConfig } = require('~/server/services/Config/app');+const { getModelsConfig } = require('~/server/controllers/ModelController');+const { getGraphApiToken } = require('~/server/services/GraphTokenService');+const { exchangeOboToken } = require('~/server/services/OboTokenService');+const { createOboTrustChecker } = require('~/server/services/OboPolicyService');+const { getLogStores } = require('~/cache');+const methods = require('~/models');++module.exports = createScheduleMCPPreflight({+ getRoleByName: methods.getRoleByName,+ resolveAgentGraphAccess: methods.resolveAgentGraphAccess,+ getAgentGraphNodes: methods.getAgentGraphNodes,+ getModelsConfig: (user) => getModelsConfig({ user }),+ getUser: (id) => methods.findUser({ _id: id }),+ getAppConfig,+ ensureConfigServers: (config, limit) =>+ getMCPServersRegistry().ensureConfigServers(config, limit),+ getServerConfigs: (userId, config, role) =>+ getMCPServersRegistry().getAllServerConfigs(userId, config, role),+ findPluginAuthsByKeys: methods.findPluginAuthsByKeys,+ connect: (options) =>+ getMCPManager().getConnection({+ ...options,+ flowManager: getFlowStateManager(getLogStores(CacheKeys.FLOWS)),+ tokenMethods: {+ findToken: methods.findToken,+ updateToken: methods.updateToken,+ createToken: methods.createToken,+ deleteTokens: methods.deleteTokens,+ },+ graphTokenResolver: getGraphApiToken,+ oboTokenResolver: exchangeOboToken,+ oboTrustChecker: createOboTrustChecker(),+ }),+});diff --git a/client/src/components/SidePanel/Schedules/ScheduleCard.tsx b/client/src/components/SidePanel/Schedules/ScheduleCard.tsxindex a0dfe0b56f..31ecb3cefc 100644--- a/client/src/components/SidePanel/Schedules/ScheduleCard.tsx+++ b/client/src/components/SidePanel/Schedules/ScheduleCard.tsx@@ -15,6 +15,7 @@ import {useToastContext,} from '@librechat/client';import type { TSchedule, ScheduleRunStatus, ScheduleDisabledReason } from 'librechat-data-provider';+import type { ImmediateScheduleMCPFailure } from './errors';import type { TranslationKeys } from '~/hooks';import {useGetAgentByIdQuery,@@ -22,7 +23,14 @@ import {useUpdateScheduleMutation,useRunScheduleNowMutation,} from '~/data-provider';+import {+ scheduleMCPErrorMessage,+ scheduleMCPErrorOutcomes,+ scheduleLastRunKey,+ scheduleMCPCardOutcomes,+} from './errors';import { useLocalize, useHasAccess, useClockFormat, useWeekStart } from '~/hooks';+import ScheduleMCPRecovery from './ScheduleMCPRecovery';import { useAgentsMapContext } from '~/Providers';import { getMessageTimestamp } from '~/utils';import ScheduleDialog from './ScheduleDialog';@@ -48,6 +56,9 @@ const STATUS_CHIPS: Record<ScheduleRunStatus, { label: TranslationKeys; tone: St};const DISABLED_REASON_LABELS: Record<ScheduleDisabledReason, TranslationKeys> = {+ mcp_reauth_required: 'com_ui_schedule_disabled_mcp_reauth',+ mcp_configuration_missing: 'com_ui_schedule_disabled_mcp_configuration',+ mcp_permission_denied: 'com_ui_schedule_disabled_mcp_permission',too_many_failures: 'com_ui_schedule_disabled_too_many_failures',agent_deleted: 'com_ui_schedule_disabled_agent_deleted',invalid_schedule: 'com_ui_schedule_disabled_invalid',@@ -60,9 +71,20 @@ const DISABLED_REASON_LABELS: Record<ScheduleDisabledReason, TranslationKeys> =export default function ScheduleCard({ schedule, projectName }: ScheduleCardProps) {const localize = useLocalize();const navigate = useNavigate();+ const lastRunKey = scheduleLastRunKey(schedule);+ const [immediateMCPFailure, setImmediateMCPFailure] =+ useState<ImmediateScheduleMCPFailure | null>(null);+ const mcpOutcomes = scheduleMCPCardOutcomes(schedule, immediateMCPFailure);const { i18n } = useTranslation();const { showToast } = useToastContext();const agentsMap = useAgentsMapContext();+ const agentNames = useMemo(+ () =>+ Object.fromEntries(+ Object.entries(agentsMap ?? {}).map(([id, agent]) => [id, agent?.name || id]),+ ),+ [agentsMap],+ );// Enable/disable, run-now, edit and delete all hit CREATE-gated routes, so a// USE-only viewer sees a read-only card instead of controls that 403.const canWrite = useHasAccess({@@ -90,10 +112,14 @@ export default function ScheduleCard({ schedule, projectName }: ScheduleCardProp* leave the owner flipping a switch that keeps flipping back; point them at the* dialog, which is where the fixable settings are. */onError: (error, variables) => {+ const outcomes = scheduleMCPErrorOutcomes(error);+ setImmediateMCPFailure(outcomes.length > 0 ? { outcomes, lastRunKey } : null);const status = (error as { response?: { status?: number } } | undefined)?.response?.status;const blockedEnable = status === 400 && variables.payload.enabled === true;showToast({- message: localize(blockedEnable ? 'com_ui_schedule_enable_blocked' : 'com_ui_error'),+ message:+ scheduleMCPErrorMessage(error, localize) ??+ localize(blockedEnable ? 'com_ui_schedule_enable_blocked' : 'com_ui_error'),status: 'error',});},@@ -103,22 +129,29 @@ export default function ScheduleCard({ schedule, projectName }: ScheduleCardPropconst handleToggle = useCallback((checked: boolean) => {+ setImmediateMCPFailure(null);updateSchedule.mutate({ id: schedule.id, payload: { enabled: checked } });},[schedule.id, updateSchedule],);const handleRunNow = useCallback(() => {+ setImmediateMCPFailure(null);runSchedule.mutate(schedule.id, {onSuccess: () => {showToast({ message: localize('com_ui_schedule_run_now_started'), status: 'success' });setMenuOpen(false);},- onError: () => {- showToast({ message: localize('com_ui_error'), status: 'error' });+ onError: (error) => {+ const outcomes = scheduleMCPErrorOutcomes(error);+ setImmediateMCPFailure(outcomes.length > 0 ? { outcomes, lastRunKey } : null);+ showToast({+ message: scheduleMCPErrorMessage(error, localize) ?? localize('com_ui_error'),+ status: 'error',+ });},});- }, [schedule.id, runSchedule, showToast, localize]);+ }, [schedule.id, runSchedule, showToast, localize, lastRunKey]);const confirmDelete = useCallback(() => {deleteSchedule.mutate(schedule.id, {@@ -264,6 +297,14 @@ export default function ScheduleCard({ schedule, projectName }: ScheduleCardProp)}</div>)}+ <div className="mt-1">+ <ScheduleMCPRecovery+ outcomes={mcpOutcomes}+ fallbackAgentId={schedule.agent_id}+ agentNames={agentNames}+ onOpenAgent={(ownerId) => navigate(`/c/new?agent_id=${encodeURIComponent(ownerId)}`)}+ />+ </div>{editOpen && (<ScheduleDialogopen={editOpen}diff --git a/client/src/components/SidePanel/Schedules/ScheduleDialog.tsx b/client/src/components/SidePanel/Schedules/ScheduleDialog.tsxindex e85fedc6c0..bbeeb6b2f0 100644--- a/client/src/components/SidePanel/Schedules/ScheduleDialog.tsx+++ b/client/src/components/SidePanel/Schedules/ScheduleDialog.tsx@@ -1,6 +1,7 @@-import { useMemo, useRef } from 'react';+import { useMemo, useRef, useState } from 'react';import { v4 } from 'uuid';import { Folder } from 'lucide-react';+import { useNavigate } from 'react-router-dom';import { useTranslation } from 'react-i18next';import { useForm, Controller } from 'react-hook-form';import {@@ -49,9 +50,11 @@ import {useCreateScheduleMutation,useUpdateScheduleMutation,} from '~/data-provider';+import { scheduleMCPErrorMessage, scheduleMCPErrorOutcomes } from './errors';import { useLocalize, useClockFormat, useWeekStart } from '~/hooks';import { useChatProjectPicker } from './useScheduleProjects';import { VariableEditor } from '~/components/Variables';+import ScheduleMCPRecovery from './ScheduleMCPRecovery';import { rotateWeekFrom } from '~/utils/clock';import { cn } from '~/utils';@@ -183,10 +186,14 @@ export default function ScheduleDialog({schedule,triggerRef,}: ScheduleDialogProps) {+ const navigate = useNavigate();const localize = useLocalize();const { i18n } = useTranslation();const { showToast } = useToastContext();const locale = i18n.language;+ const [mcpRecoveryOutcomes, setMCPRecoveryOutcomes] = useState<+ ReturnType<typeof scheduleMCPErrorOutcomes>+ >([]);const {control,@@ -211,6 +218,7 @@ export default function ScheduleDialog({const daysOfWeek = watch('daysOfWeek');const expression = watch('expression');const timezone = watch('timezone');+ const selectedAgentId = watch('agent_id');/** Not named `hour12`: that is already the form's own 12-hour clock VALUE (1-12).* This is the preference deciding whether a time is written with a meridiem. */const prefersMeridiem = useClockFormat();@@ -228,6 +236,10 @@ export default function ScheduleDialog({() => (agents ?? []).map((agent) => ({ label: agent.name || agent.id, value: agent.id })),[agents],);+ const agentNames = useMemo(+ () => Object.fromEntries((agents ?? []).map((agent) => [agent.id, agent.name || agent.id])),+ [agents],+ );/** Reads the SAME cached list query the panel already holds, so the dialog needs no* request of its own — and so the form mirrors exactly the policy the write handler@@ -317,25 +329,34 @@ export default function ScheduleDialog({const createSchedule = useCreateScheduleMutation({onSuccess: () => {+ setMCPRecoveryOutcomes([]);createRequestId.current = v4();lastAttemptedPayload.current = null;showToast({ message: localize('com_ui_schedule_created'), status: 'success' });onOpenChange(false);},- onError: () => {- showToast({ message: localize('com_ui_error'), status: 'error' });+ onError: (error) => {+ setMCPRecoveryOutcomes(scheduleMCPErrorOutcomes(error));+ showToast({+ message: scheduleMCPErrorMessage(error, localize) ?? localize('com_ui_error'),+ status: 'error',+ });},});const updateSchedule = useUpdateScheduleMutation({onSuccess: () => {+ setMCPRecoveryOutcomes([]);showToast({ message: localize('com_ui_schedule_updated'), status: 'success' });onOpenChange(false);},onError: (error) => {+ setMCPRecoveryOutcomes(scheduleMCPErrorOutcomes(error));const status = (error as { response?: { status?: number } } | undefined)?.response?.status;showToast({- message: localize(status === 409 ? 'com_ui_schedule_conflict' : 'com_ui_error'),+ message:+ scheduleMCPErrorMessage(error, localize) ??+ localize(status === 409 ? 'com_ui_schedule_conflict' : 'com_ui_error'),status: 'error',});},@@ -568,6 +589,15 @@ export default function ScheduleDialog({className="w-11/12 md:max-w-3xl"main={<form id={FORM_ID} onSubmit={handleSubmit(onSubmit)} className="space-y-4">+ <ScheduleMCPRecovery+ outcomes={mcpRecoveryOutcomes}+ fallbackAgentId={schedule?.agent_id ?? selectedAgentId}+ agentNames={agentNames}+ onOpenAgent={(ownerId) => {+ onOpenChange(false);+ navigate(`/c/new?agent_id=${encodeURIComponent(ownerId)}`);+ }}+ />{/* Identity row: what the schedule is, who runs it, where its chats land.Its caption is grouped with it rather than left to the form's own 4-unitrhythm, which would spend more vertical budget on the gap than thediff --git a/client/src/components/SidePanel/Schedules/ScheduleMCPRecovery.tsx b/client/src/components/SidePanel/Schedules/ScheduleMCPRecovery.tsxnew file mode 100644index 0000000000..91ae6b8c44--- /dev/null+++ b/client/src/components/SidePanel/Schedules/ScheduleMCPRecovery.tsx@@ -0,0 +1,48 @@+import type { ScheduleMCPOutcome } from 'librechat-data-provider';+import { MCP_STATUS_LABELS, scheduleMCPNeedsAgentRecovery } from './errors';+import { useLocalize } from '~/hooks';++export default function ScheduleMCPRecovery({+ outcomes,+ fallbackAgentId,+ agentNames,+ onOpenAgent,+}: {+ outcomes: ScheduleMCPOutcome[];+ fallbackAgentId: string;+ agentNames?: Record<string, string>;+ onOpenAgent: (agentId: string) => void;+}) {+ const localize = useLocalize();+ const failures = outcomes.filter((item) => item.status !== 'ready');+ if (failures.length === 0) return null;++ return (+ <div className="space-y-1" role="alert">+ {failures.map((item, index) => {+ const ownerId = item.agentId ?? fallbackAgentId;+ const ownerLabel = agentNames?.[ownerId] ?? ownerId;+ return (+ <div+ key={`${item.server}:${ownerId}:${item.status}:${index}`}+ className="flex flex-wrap items-baseline gap-x-2 text-xs text-text-secondary"+ >+ <p>+ {item.server} ({ownerLabel}): {localize(MCP_STATUS_LABELS[item.status])}+ </p>+ {scheduleMCPNeedsAgentRecovery([item]) && (+ <button+ type="button"+ className="text-text-primary underline"+ aria-label={`${item.server}, ${ownerLabel}: ${localize('com_ui_schedule_mcp_open_agent')}`}+ onClick={() => onOpenAgent(ownerId)}+ >+ {localize('com_ui_schedule_mcp_open_agent')}+ </button>+ )}+ </div>+ );+ })}+ </div>+ );+}diff --git a/client/src/components/SidePanel/Schedules/__tests__/ScheduleDialog.spec.tsx b/client/src/components/SidePanel/Schedules/__tests__/ScheduleDialog.spec.tsxindex b2408daaf8..712343f7a2 100644--- a/client/src/components/SidePanel/Schedules/__tests__/ScheduleDialog.spec.tsx+++ b/client/src/components/SidePanel/Schedules/__tests__/ScheduleDialog.spec.tsx@@ -1,8 +1,9 @@import { createElement } from 'react';+import { MemoryRouter } from 'react-router-dom';import { ToastProvider } from '@librechat/client';import userEvent from '@testing-library/user-event';-import { render, screen, waitFor, within } from '@testing-library/react';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import { act, render, screen, waitFor, within } from '@testing-library/react';import type { TSchedule } from 'librechat-data-provider';import type { ReactNode } from 'react';import ScheduleDialog from '../ScheduleDialog';@@ -23,6 +24,7 @@ jest.mock('react-i18next', () => ({}));const mockMutate = jest.fn();+let createMutationOptions: { onError: (error: Error) => void } | undefined;/** Server-resolved schedule policy for the render under test. The dialog reads it from* the schedules list query, the same cache entry the panel populates. */@@ -67,11 +69,14 @@ jest.mock('~/data-provider', () => ({isFetchingNextPage: false,isLoading: false,}),- useCreateScheduleMutation: () => ({ mutate: mockMutate, isLoading: false }),+ useCreateScheduleMutation: (options: { onError: (error: Error) => void }) => {+ createMutationOptions = options;+ return { mutate: mockMutate, isLoading: false };+ },useUpdateScheduleMutation: () => ({ mutate: mockMutate, isLoading: false }),}));-const renderDialog = (schedule?: Partial<TSchedule>) => {+const renderDialog = (schedule?: Partial<TSchedule>, onOpenChange = jest.fn()) => {const queryClient = new QueryClient({defaultOptions: { queries: { retry: false }, mutations: { retry: false } },});@@ -79,13 +84,13 @@ const renderDialog = (schedule?: Partial<TSchedule>) => {return createElement(QueryClientProvider,{ client: queryClient },- createElement(ToastProvider, null, children),+ createElement(MemoryRouter, null, createElement(ToastProvider, null, children)),);}return render(<ScheduleDialogopen={true}- onOpenChange={jest.fn()}+ onOpenChange={onOpenChange}schedule={schedule as TSchedule | undefined}/>,{ wrapper: Wrapper },@@ -124,6 +129,7 @@ describe('ScheduleDialog', () => {mockUseClockFormat.mockReturnValue(true);mockUseWeekStart.mockReturnValue(0);mockFetchedProject = undefined;+ createMutationOptions = undefined;});/**@@ -141,6 +147,34 @@ describe('ScheduleDialog', () => {expect(within(dialog).getByPlaceholderText('com_agents_search_name')).toBeInTheDocument();});+ it('closes before opening the agent that owns an admission failure', async () => {+ const user = userEvent.setup();+ const onOpenChange = jest.fn();+ renderDialog(undefined, onOpenChange);+ const error = Object.assign(new Error('missing tool'), {+ response: {+ data: {+ mcp: [+ {+ server: 'Notion',+ agentId: 'child-agent',+ status: 'mcp_configuration_missing',+ },+ ],+ },+ },+ });++ act(() => createMutationOptions?.onError(error));+ await user.click(+ screen.getByRole('button', {+ name: 'Notion, child-agent: com_ui_schedule_mcp_open_agent',+ }),+ );++ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+it('exposes frequency as a radiogroup with the default selected', () => {renderDialog();diff --git a/client/src/components/SidePanel/Schedules/__tests__/ScheduleMCPRecovery.spec.tsx b/client/src/components/SidePanel/Schedules/__tests__/ScheduleMCPRecovery.spec.tsxnew file mode 100644index 0000000000..ced818d972--- /dev/null+++ b/client/src/components/SidePanel/Schedules/__tests__/ScheduleMCPRecovery.spec.tsx@@ -0,0 +1,30 @@+import userEvent from '@testing-library/user-event';+import { render, screen } from '@testing-library/react';+import ScheduleMCPRecovery from '../ScheduleMCPRecovery';++jest.mock('~/hooks', () => ({ useLocalize: () => (key: string) => key }));++it('opens the exact descendant that owns an immediate MCP failure', async () => {+ const onOpenAgent = jest.fn();+ render(+ <ScheduleMCPRecovery+ outcomes={[+ {+ server: 'Notion',+ agentId: 'research-agent',+ status: 'mcp_configuration_missing',+ },+ ]}+ fallbackAgentId="root-agent"+ agentNames={{ 'research-agent': 'Research Agent' }}+ onOpenAgent={onOpenAgent}+ />,+ );++ await userEvent.click(+ screen.getByRole('button', {+ name: 'Notion, Research Agent: com_ui_schedule_mcp_open_agent',+ }),+ );+ expect(onOpenAgent).toHaveBeenCalledWith('research-agent');+});diff --git a/client/src/components/SidePanel/Schedules/__tests__/errors.spec.ts b/client/src/components/SidePanel/Schedules/__tests__/errors.spec.tsnew file mode 100644index 0000000000..09292e53c3--- /dev/null+++ b/client/src/components/SidePanel/Schedules/__tests__/errors.spec.ts@@ -0,0 +1,137 @@+import { readScheduleMCPOutcomes } from 'librechat-data-provider';+import {+ scheduleMCPErrorMessage,+ scheduleMCPErrorOutcomes,+ scheduleMCPCardOutcomes,+ scheduleMCPRecoveryOutcomes,+ scheduleMCPNeedsAgentRecovery,+} from '../errors';++it('shows localized recovery reasons and exact server names', () => {+ const error = Object.assign(new Error('private transport details'), {+ response: {+ data: {+ mcp: [+ { server: 'Notion', status: 'mcp_reauth_required' },+ { server: 'ClickHouse', status: 'ready' },+ ],+ },+ },+ });+ expect(scheduleMCPErrorMessage(error, (key) => key)).toBe('Notion: com_ui_schedule_mcp_reauth');+ expect(scheduleMCPErrorOutcomes(error)).toEqual([+ { server: 'Notion', status: 'mcp_reauth_required' },+ { server: 'ClickHouse', status: 'ready' },+ ]);+});++it('drops an immediate MCP failure after polling reports a newer run', () => {+ const immediate = {+ lastRunKey: '2026-09-09T12:00:00.000Z:error',+ outcomes: [{ server: 'Notion', status: 'mcp_unavailable' as const }],+ };+ const prior = {+ enabled: true,+ lastRun: { firedAt: '2026-09-09T12:00:00.000Z', status: 'error' as const },+ };+ const recovered = {+ enabled: true,+ lastRun: { firedAt: '2026-09-09T13:00:00.000Z', status: 'success' as const },+ };++ expect(scheduleMCPCardOutcomes(prior, immediate)).toEqual(immediate.outcomes);+ expect(scheduleMCPCardOutcomes(recovered, immediate)).toEqual([]);+});++it('preserves descendant owners from immediate admission errors', () => {+ const error = Object.assign(new Error('missing tool'), {+ response: {+ data: {+ mcp: [+ {+ server: 'Notion',+ agentId: 'research-agent',+ status: 'mcp_configuration_missing',+ },+ ],+ },+ },+ });++ expect(scheduleMCPErrorOutcomes(error)).toEqual([+ {+ server: 'Notion',+ agentId: 'research-agent',+ status: 'mcp_configuration_missing',+ },+ ]);+});++it('ignores unrelated and malformed server errors', () => {+ expect(+ scheduleMCPErrorMessage(new Error('private transport details'), (key) => key),+ ).toBeUndefined();+ expect(readScheduleMCPOutcomes('mcp_reauth_required: [malformed')).toEqual([]);+});++it('explains transient MCP infrastructure failures without server outcomes', () => {+ const error = Object.assign(new Error('private infrastructure details'), {+ response: { status: 503, data: { code: 'mcp_unavailable' } },+ });+ expect(scheduleMCPErrorMessage(error, (key) => key)).toBe('com_ui_schedule_mcp_unavailable');+});++it('explains administrator-revoked MCP permission', () => {+ const error = Object.assign(new Error('permission denied'), {+ response: {+ status: 400,+ data: { mcp: [{ server: 'Notion', status: 'mcp_permission_denied' }] },+ },+ });+ expect(scheduleMCPErrorMessage(error, (key) => key)).toBe(+ 'Notion: com_ui_schedule_mcp_permission',+ );+});++it('restores saved per-server failure outcomes on the schedule card', () => {+ const outcomes = [+ { server: 'Notion', agentId: 'research-agent', status: 'mcp_reauth_required' as const },+ ];+ const lastRun = {+ status: 'error' as const,+ firedAt: new Date().toISOString(),+ error: 'mcp_reauth_required: [legacy malformed payload',+ mcp: outcomes,+ };+ expect(+ scheduleMCPRecoveryOutcomes({+ enabled: false,+ disabledReason: 'mcp_reauth_required',+ lastRun,+ }),+ ).toEqual(outcomes);+ expect(+ scheduleMCPRecoveryOutcomes({+ enabled: false,+ disabledReason: 'permission_revoked',+ lastRun,+ }),+ ).toEqual([]);+ expect(scheduleMCPRecoveryOutcomes({ enabled: true, lastRun })).toEqual([]);+});++it('does not label unrelated schedule 503 responses as MCP failures', () => {+ const error = Object.assign(new Error('scheduler unavailable'), {+ response: { status: 503, data: { code: 'SCHEDULES_UNAVAILABLE' } },+ });+ expect(scheduleMCPErrorMessage(error, (key) => key)).toBeUndefined();+});++it('does not offer agent reconnection for permission-only recovery', () => {+ expect(+ scheduleMCPNeedsAgentRecovery([{ server: 'Notion', status: 'mcp_permission_denied' }]),+ ).toBe(false);+ expect(scheduleMCPNeedsAgentRecovery([{ server: 'Notion', status: 'mcp_reauth_required' }])).toBe(+ true,+ );+});diff --git a/client/src/components/SidePanel/Schedules/errors.ts b/client/src/components/SidePanel/Schedules/errors.tsnew file mode 100644index 0000000000..66abd5ef8e--- /dev/null+++ b/client/src/components/SidePanel/Schedules/errors.ts@@ -0,0 +1,77 @@+import { readScheduleMCPOutcomes, scheduleMCPOutcomeSchema } from 'librechat-data-provider';+import type { TSchedule, ScheduleMCPStatus, ScheduleMCPOutcome } from 'librechat-data-provider';+import type { TranslationKeys, useLocalize } from '~/hooks';++export const MCP_STATUS_LABELS: Record<ScheduleMCPStatus, TranslationKeys> = {+ ready: 'com_ui_schedule_mcp_ready',+ mcp_reauth_required: 'com_ui_schedule_mcp_reauth',+ mcp_configuration_missing: 'com_ui_schedule_mcp_configuration',+ mcp_permission_denied: 'com_ui_schedule_mcp_permission',+ mcp_unavailable: 'com_ui_schedule_mcp_unavailable',+};++export function scheduleMCPRecoveryOutcomes(+ schedule: Pick<TSchedule, 'enabled' | 'disabledReason' | 'lastRun'>,+) {+ const reason = schedule.disabledReason;+ const preservesMCPRecovery =+ reason === 'mcp_reauth_required' ||+ reason === 'mcp_configuration_missing' ||+ reason === 'mcp_permission_denied' ||+ reason === 'too_many_failures';+ if (schedule.enabled || !preservesMCPRecovery) return [];+ const persisted = scheduleMCPOutcomeSchema.array().safeParse(schedule.lastRun?.mcp);+ return persisted.success ? persisted.data : readScheduleMCPOutcomes(schedule.lastRun?.error);+}++export type ImmediateScheduleMCPFailure = {+ outcomes: ScheduleMCPOutcome[];+ lastRunKey: string;+};++export function scheduleLastRunKey(schedule: Pick<TSchedule, 'lastRun'>): string {+ return `${schedule.lastRun?.firedAt ?? ''}:${schedule.lastRun?.status ?? ''}`;+}++/** Keeps a request-local error visible until polling reports a different run. */+export function scheduleMCPCardOutcomes(+ schedule: Pick<TSchedule, 'enabled' | 'disabledReason' | 'lastRun'>,+ immediate: ImmediateScheduleMCPFailure | null,+): ScheduleMCPOutcome[] {+ return immediate?.lastRunKey === scheduleLastRunKey(schedule)+ ? immediate.outcomes+ : scheduleMCPRecoveryOutcomes(schedule);+}++export function scheduleMCPNeedsAgentRecovery(outcomes: ScheduleMCPOutcome[]): boolean {+ return outcomes.some(+ (outcome) => outcome.status !== 'ready' && outcome.status !== 'mcp_permission_denied',+ );+}++export function scheduleMCPErrorMessage(+ error: Error,+ localize: ReturnType<typeof useLocalize>,+): string | undefined {+ const failures = scheduleMCPErrorOutcomes(error).filter((item) => item.status !== 'ready');+ if (failures.length > 0) {+ return failures+ .map((item) => `${item.server}: ${localize(MCP_STATUS_LABELS[item.status])}`)+ .join('; ');+ }+ const response = (+ error as Error & { response?: { status?: number; data?: { code?: string; mcp?: object } } }+ ).response;+ return response?.data?.code === 'mcp_unavailable'+ ? localize(MCP_STATUS_LABELS.mcp_unavailable)+ : undefined;+}++/** Preserves the structured recovery projection for immediate create, update, and+ * Run Now failures. The message formatter and every recovery surface consume the+ * same parsed outcome rather than independently interpreting the response. */+export function scheduleMCPErrorOutcomes(error: Error): ScheduleMCPOutcome[] {+ const payload = (error as Error & { response?: { data?: { mcp?: object } } }).response?.data?.mcp;+ const parsed = scheduleMCPOutcomeSchema.array().safeParse(payload);+ return parsed.success ? parsed.data : [];+}diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex 2a8f7a7c8b..9f703294a1 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -1,4 +1,13 @@{+ "com_ui_schedule_mcp_ready": "Ready for scheduled chats",+ "com_ui_schedule_mcp_reauth": "Reconnect this MCP server before enabling the schedule.",+ "com_ui_schedule_mcp_configuration": "Configure or remove this MCP server before enabling the schedule.",+ "com_ui_schedule_mcp_permission": "An administrator must restore your MCP server permission.",+ "com_ui_schedule_mcp_unavailable": "MCP server unavailable. Try again later.",+ "com_ui_schedule_mcp_open_agent": "Open agent to reconnect MCPs",+ "com_ui_schedule_disabled_mcp_reauth": "Disabled: MCP reauthentication required",+ "com_ui_schedule_disabled_mcp_configuration": "Disabled: MCP configuration required",+ "com_ui_schedule_disabled_mcp_permission": "Disabled: MCP permission revoked","com_ui_code_approval_mode": "Code approval mode","com_ui_code_workspace": "Code workspace","com_ui_code_workspace_choose": "Choose workspace",diff --git a/e2e/specs/mock/schedules-execution.spec.ts b/e2e/specs/mock/schedules-execution.spec.tsindex c1612998b5..c5a9bd161b 100644--- a/e2e/specs/mock/schedules-execution.spec.ts+++ b/e2e/specs/mock/schedules-execution.spec.ts@@ -5,7 +5,6 @@ import { getAccessToken, requestJson, replyPrompt, replyText } from './helpers';const uniqueName = (prefix: string) => `${prefix} ${Date.now()}-${Math.floor(Math.random() * 1e4)}`;type AgentSummary = { id: string; name?: string };-type AgentList = { data?: AgentSummary[] };type Schedule = {id: string;name: string;@@ -19,18 +18,16 @@ type ScheduleList = { schedules: Schedule[] };type RunNowResult = { scheduleId: string; conversationId?: string; status?: string };async function ensureAgent(page: Page, token: string): Promise<AgentSummary> {- const list = await requestJson<AgentList>(page, { path: '/api/agents?limit=1', token }).catch(- () => ({}) as AgentList,- );- const existing = list.data?.[0];- if (existing?.id) {- return existing;- }const agent = await requestJson<AgentSummary>(page, {path: '/api/agents',token,method: 'POST',- body: { name: uniqueName('E2E Agent'), provider: 'Mock Provider A', model: 'mock-model-a' },+ body: {+ name: uniqueName('Schedule E2E Agent'),+ provider: 'Mock Provider A',+ model: 'mock-model-a',+ tools: [],+ },});expect(agent.id).toBeTruthy();return agent;diff --git a/librechat.example.yaml b/librechat.example.yamlindex 61bc012676..ac285d70c1 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -223,7 +223,13 @@ interface:# maxPerUser: 10# minIntervalMinutes: 60# autoDisableAfterFailures: 5+ # # Maximum occurrences concurrently passing readiness admission per replica (1-100).+ # admissionConcurrency: 20# fireConcurrency: 5+ # # Maximum MCP readiness connections opened at once by one schedule admission (1-10).+ # mcpPreflightConcurrency: 3+ # # Maximum wall-clock time for one MCP readiness admission (1000-600000 ms).+ # mcpPreflightTimeoutMs: 300000# # Require every schedule to be filed under a chat project. Enforced on# # create/update AND at each fire, so turning it on stops (auto-disables)# # schedules that predate it rather than letting their runs land loose.diff --git a/packages/api/src/agents/discovery.ts b/packages/api/src/agents/discovery.tsindex 45766568a5..c34957c8c9 100644--- a/packages/api/src/agents/discovery.ts+++ b/packages/api/src/agents/discovery.ts@@ -22,7 +22,7 @@ import type { ValidateAgentModelParams } from './validation';import type { ServerRequest } from '~/types';import { validateAgentModel as defaultValidateAgentModel } from './validation';import { initializeAgent as defaultInitializeAgent } from './initialize';-import { createEdgeCollector, filterOrphanedEdges } from './edges';+import { createEdgeCollector, resolveReachableGraph } from './edges';import { isFatalAgentInitializationError } from './errors';import { createConcurrencyLimiter } from '~/utils/promise';import { createSequentialChainEdges } from './chain';@@ -488,147 +488,12 @@ export async function discoverConnectedAgents(}const preFilterEdges = Array.from(edgeMap.values());- const filteredEdges = filterOrphanedEdges(preFilterEdges, skippedAgentIds);-- /**- * Discovery computes structural reachability before compiling the SDK- * graph. A multi-source direct edge is an all-source runtime barrier, but- * discovery deliberately advances when any surviving source is reachable:- * inaccessible/orphaned sources are removed below, reducing the barrier to- * the branches the caller can actually run.- *- * Two semantics to reconcile when pruning after orphan-filter:- *- * 1. Accidental orphans — agents loaded via BFS from the primary's- * edges that lost their only path when an intermediate agent was- * skipped (e.g. `A -> B -> C` with B skipped leaves C stranded).- * These should be pruned; leaving them flips `createRun` into- * multi-agent mode with a disconnected C and the SDK runs C as an- * unintended parallel root.- *- * 2. Intentional multi-start branches — agents referenced by edges the- * user explicitly defined without wiring them to the primary- * (e.g. `A -> B` plus `X -> Y` as two independent starting- * branches). The SDK's `MultiAgentGraph.analyzeGraph` treats- * `no-incoming-edge` agents as start nodes, so these run in- * parallel with the primary by design. These must be preserved.- *- * Distinguish the two by asking: did the agent have any incoming edge- * in the user's original (pre-filter) graph? If yes, it was wired as- * a downstream step, and losing that wiring post-filter makes it an- * accidental orphan — prune. If no, the user declared it a start- * node; seed it so the SDK's `analyzeGraph` behavior of running- * incoming-less agents in parallel is preserved.- *- * "No incoming edge pre-filter" is stricter than "not reachable from- * primary pre-filter": a downstream agent like Y in `X -> Y` where X- * is skipped was never reachable from the primary pre-filter either,- * but it's still an orphan (its upstream X would have routed to it).- * The incoming-edge test catches that case correctly.- *- * - Post-filter reachability is seeded with the primary AND every- * agent in `agentConfigs` that had no pre-filter incoming edge- * (legitimate parallel start).- * - Agents whose pre-filter incoming edges got filtered out lose- * reachability and get pruned.- * - Surviving edges are filtered to the post-filter reachable set- * so no stale edge references a pruned agent.- * - Agents referenced as an endpoint in a surviving edge are always- * kept (a multi-source edge co-source like B in- * `{ from: ['A','B'], to: 'C' }` where nothing reaches B still- * needs B present for the SDK waiting barrier to compile).- */- const anyReachable = (value: string | string[], reachableSet: Set<string>): boolean => {- const ids = Array.isArray(value) ? value : [value];- return ids.some((id) => typeof id === 'string' && reachableSet.has(id));- };- const allReachable = (value: string | string[], reachableSet: Set<string>): boolean => {- const ids = Array.isArray(value) ? value : [value];- return ids.every((id) => typeof id !== 'string' || reachableSet.has(id));- };- const expandReachable = (seeds: Set<string>, edgeList: GraphEdge[]): Set<string> => {- const result = new Set<string>(seeds);- let changed = true;- while (changed) {- changed = false;- for (const edge of edgeList) {- if (!anyReachable(edge.from, result)) {- continue;- }- const dests = Array.isArray(edge.to) ? edge.to : [edge.to];- for (const dest of dests) {- if (typeof dest === 'string' && !result.has(dest)) {- result.add(dest);- changed = true;- }- }- }- }- return result;- };-- // A legitimate parallel-start agent is one that has NO incoming edge- // in the pre-filter graph — the user declared it as a starting node.- // "Not reachable from primary pre-filter" is too permissive: a- // downstream agent whose only upstream got skipped (`X -> Y` with X- // skipped but Y loaded) would qualify under that weaker rule and be- // promoted to a parallel root even though it's actually a stranded- // orphan. Using "no incoming edge in pre-filter" tightens the criterion- // to match the SDK's `analyzeGraph` definition of a start node applied- // to the user's ORIGINAL graph topology, before any orphan filtering.- const hadIncomingEdgePreFilter = new Set<string>();- for (const edge of preFilterEdges) {- const dests = Array.isArray(edge.to) ? edge.to : [edge.to];- for (const dest of dests) {- if (typeof dest === 'string') {- hadIncomingEdgePreFilter.add(dest);- }- }- }-- const postFilterSeeds = new Set<string>([primaryConfig.id]);- for (const agentId of agentConfigs.keys()) {- if (!hadIncomingEdgePreFilter.has(agentId)) {- postFilterSeeds.add(agentId);- }- }-- const reachable = expandReachable(postFilterSeeds, filteredEdges);-- /**- * Filter + sanitize edges:- * - Keep an edge if at least one `from` source is reachable AND every- * `to` destination is reachable (a missing destination would still- * crash `StateGraph.compile` with `Found edge ending at unknown- * node`).- * - For kept edges with an array `from`, strip out unreachable- * co-sources. The SDK represents a multi-source direct edge as a- * synchronization barrier, so retaining a source that was pruned- * would leave the destination waiting forever. Removing dead sources- * preserves the barrier across the remaining reachable branches and- * prevents pruned agents from reappearing as unintended parallel roots- * during `MultiAgentGraph.analyzeGraph`.- *- * After sanitization every endpoint in every surviving edge is- * guaranteed to be in `reachable`, which lets the agent prune below- * collapse to a strict reachability check.- */- const edges: GraphEdge[] = [];- for (const edge of filteredEdges) {- if (!anyReachable(edge.from, reachable) || !allReachable(edge.to, reachable)) {- continue;- }- if (!Array.isArray(edge.from)) {- edges.push(edge);- continue;- }- const reachableSources = edge.from.filter((s) => typeof s !== 'string' || reachable.has(s));- if (reachableSources.length === edge.from.length) {- edges.push(edge);- } else {- edges.push({ ...edge, from: reachableSources });- }- }+ const { reachable, edges } = resolveReachableGraph(+ [primaryConfig.id],+ agentConfigs.keys(),+ preFilterEdges,+ skippedAgentIds,+ );for (const agentId of [...agentConfigs.keys()]) {if (!reachable.has(agentId)) {diff --git a/packages/api/src/agents/edges.ts b/packages/api/src/agents/edges.tsindex 98482d214d..2656938baf 100644--- a/packages/api/src/agents/edges.ts+++ b/packages/api/src/agents/edges.ts@@ -139,6 +139,67 @@ export function filterOrphanedEdges(edges: GraphEdge[], skippedAgentIds: Set<strreturn result;}+/** Applies the runtime graph's post-filter reachability rules to loaded agents and edges. */+export function resolveReachableGraph(+ explicitSeeds: Iterable<string>,+ agentIds: Iterable<string>,+ preFilterEdges: GraphEdge[],+ skippedAgentIds: Set<string>,+): { reachable: Set<string>; edges: GraphEdge[] } {+ const filteredEdges = filterOrphanedEdges(preFilterEdges, skippedAgentIds);+ const anyReachable = (value: string | string[], reachableSet: Set<string>): boolean =>+ (Array.isArray(value) ? value : [value]).some(+ (id) => typeof id === 'string' && reachableSet.has(id),+ );+ const allReachable = (value: string | string[], reachableSet: Set<string>): boolean =>+ (Array.isArray(value) ? value : [value]).every(+ (id) => typeof id !== 'string' || reachableSet.has(id),+ );++ const hadIncomingEdgePreFilter = new Set<string>();+ for (const edge of preFilterEdges) {+ for (const dest of Array.isArray(edge.to) ? edge.to : [edge.to]) {+ if (typeof dest === 'string') hadIncomingEdgePreFilter.add(dest);+ }+ }++ const seeds = new Set(explicitSeeds);+ for (const agentId of agentIds) {+ if (!hadIncomingEdgePreFilter.has(agentId)) seeds.add(agentId);+ }++ const reachable = new Set(seeds);+ let changed = true;+ while (changed) {+ changed = false;+ for (const edge of filteredEdges) {+ if (!anyReachable(edge.from, reachable)) continue;+ for (const dest of Array.isArray(edge.to) ? edge.to : [edge.to]) {+ if (typeof dest === 'string' && !reachable.has(dest)) {+ reachable.add(dest);+ changed = true;+ }+ }+ }+ }++ const edges: GraphEdge[] = [];+ for (const edge of filteredEdges) {+ if (!anyReachable(edge.from, reachable) || !allReachable(edge.to, reachable)) continue;+ if (!Array.isArray(edge.from)) {+ edges.push(edge);+ continue;+ }+ const reachableSources = edge.from.filter(+ (source) => typeof source !== 'string' || reachable.has(source),+ );+ edges.push(+ reachableSources.length === edge.from.length ? edge : { ...edge, from: reachableSources },+ );+ }+ return { reachable, edges };+}+/** Collects all unique agent IDs referenced across an array of edges. */export function collectEdgeAgentIds(edges: GraphEdge[] | undefined): Set<string> {const ids = new Set<string>();diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.tsindex fb02ede64f..5a126fe7b1 100644--- a/packages/api/src/mcp/MCPManager.ts+++ b/packages/api/src/mcp/MCPManager.ts@@ -119,7 +119,7 @@ export class MCPManager extends UserConnectionManager {opts: t.UserMCPConnectionOptions,): Promise<MCPConnection> {const userId = opts.user?.id;- if (opts.forceNew || !userId) {+ if (opts.forceNew || opts.ephemeralConnection || !userId) {return super.getUserConnection(opts);}@@ -288,6 +288,7 @@ export class MCPManager extends UserConnectionManager {serverName: string;user?: IUser;forceNew?: boolean;+ ephemeralConnection?: boolean;flowManager?: FlowStateManager<MCPOAuthTokens | null>;/** Pre-resolved config for config-source servers not in YAML/DB */serverConfig?: t.ParsedServerConfig;diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsindex d1ff7e7561..a38c27bce4 100644--- a/packages/api/src/mcp/UserConnectionManager.ts+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -352,7 +352,9 @@ export abstract class UserConnectionManager {`[MCP][User: ${userId}][${serverName}] Request body field(s) required to resolve runtime MCP placeholders: ${missingBodyFields.join(', ')}.`,);}- const ephemeralConnection = config ? requiresEphemeralUserConnection(config) : false;+ const ephemeralConnection =+ opts.ephemeralConnection === true ||+ (config ? requiresEphemeralUserConnection(config) : false);const requestScopedConnections = ephemeralConnection? opts.requestScopedConnections: undefined;diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.tsindex 5712fcd83a..116ae00e4f 100644--- a/packages/api/src/mcp/__tests__/MCPManager.test.ts+++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts@@ -5693,6 +5693,48 @@ describe('MCPManager', () => {expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);});+ it('isolates an unattended probe from a live user connection', async () => {+ const config: t.ParsedServerConfig = {+ type: 'streamable-http',+ url: 'https://api.example.com/mcp',+ source: 'user',+ requiresOAuth: false,+ };+ const live = {+ isConnected: jest.fn().mockResolvedValue(true),+ refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),+ on: jest.fn(),+ disconnect: jest.fn(),+ dispose: jest.fn().mockResolvedValue(undefined),+ } as unknown as MCPConnection;+ const probe = {+ isConnected: jest.fn().mockResolvedValue(true),+ on: jest.fn(),+ } as unknown as MCPConnection;+ mockAppConnections({ has: jest.fn().mockResolvedValue(false) });+ (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(config);+ (MCPConnectionFactory.create as jest.Mock)+ .mockResolvedValueOnce(live)+ .mockResolvedValueOnce(probe);+ const manager = await MCPManager.createInstance(newMCPServersConfig());+ expect(await manager.getUserConnection({ serverName, user: mockUser })).toBe(live);+ const requestScopedConnections: t.RequestScopedMCPConnectionStore = {+ connections: new Map(),+ pending: new Map(),+ };+ expect(+ await manager.getUserConnection({+ serverName,+ user: mockUser,+ ephemeralConnection: true,+ requestScopedConnections,+ }),+ ).toBe(probe);+ expect(await manager.getUserConnection({ serverName, user: mockUser })).toBe(live);+ expect(live.disconnect).not.toHaveBeenCalled();+ expect(requestScopedConnections.connections.get(`${mockUser.id}:${serverName}`)).toBe(probe);+ });+it('should reuse BODY-scoped connections within a request-scoped connection store', async () => {const bodyUrlConfig: t.ParsedServerConfig = {type: 'streamable-http',diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.tsindex bd07a3fa01..1e6700d484 100644--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts@@ -22,6 +22,10 @@ import { withTimeout } from '~/utils';/** How long a failure stub is considered fresh before re-attempting inspection (5 minutes). */const CONFIG_STUB_RETRY_MS = 5 * 60 * 1000;+/** A request stopped while its config initialization was still queued. Healthy+ * joiners retry ownership instead of inheriting that request-local cancellation. */+export class MCPConfigInitializationCanceledError extends Error {}+/** Cached configs carry decrypted oauth/apiKey credentials, so the shared* stores only ever see ciphertext; plaintext stays in process memory,* exactly where it lived before these caches became shared. */@@ -460,7 +464,9 @@ export class MCPServersRegistry {/** Tenant-scoped (also covering the single-flight map): the DB read behind* a miss is filtered by the active tenant, so entries and in-flight* builds must partition the same way. */- const cacheKey = scopedCacheKey(userId ?? '__no_user__');+ // DB visibility depends on both user and role. Keep the role in the cache and+ // single-flight identity so a role change cannot reuse the previous ACL result.+ const cacheKey = scopedCacheKey(`${userId ?? '__no_user__'}::role:${role ?? '__no_role__'}`);const cached = await this.readThroughCacheAll.get(cacheKey);if (cached.hit) {@@ -777,6 +783,7 @@ export class MCPServersRegistry {*/public async ensureConfigServers(resolvedMcpConfig: Record<string, t.MCPOptions>,+ limit: <T>(task: () => Promise<T>) => Promise<T> = (task) => task(),): Promise<Record<string, t.ParsedServerConfig>> {if (!resolvedMcpConfig || Object.keys(resolvedMcpConfig).length === 0) {return {};@@ -798,7 +805,12 @@ export class MCPServersRegistry {if (this.isUnmodifiedYamlServer(yamlSnapshot, serverName, rawConfig)) {return;}- const parsed = await this.ensureSingleConfigServer(serverName, rawConfig, allowlists);+ const parsed = await this.ensureSingleConfigServer(+ serverName,+ rawConfig,+ allowlists,+ limit,+ );if (parsed) {result[serverName] = parsed;}@@ -848,6 +860,7 @@ export class MCPServersRegistry {serverName: string,rawConfig: t.MCPOptions,allowlists: ResolvedMCPAllowlists,+ limit: <T>(task: () => Promise<T>) => Promise<T>,): Promise<t.ParsedServerConfig | undefined> {const cacheKey = this.configCacheKey(serverName, rawConfig, allowlists);@@ -863,10 +876,22 @@ export class MCPServersRegistry {const pending = this.pendingConfigInits.get(cacheKey);if (pending) {- return pending;+ try {+ return await pending;+ } catch (error) {+ if (error instanceof MCPConfigInitializationCanceledError) {+ return this.ensureSingleConfigServer(serverName, rawConfig, allowlists, limit);+ }+ throw error;+ }}- const initPromise = this.lazyInitConfigServer(cacheKey, serverName, rawConfig, allowlists);+ // Only the caller that owns the cold initialization consumes shared capacity.+ // Joiners await the single-flight promise directly instead of filling every+ // slot while the same inspection runs once.+ const initPromise = limit(() =>+ this.lazyInitConfigServer(cacheKey, serverName, rawConfig, allowlists),+ );this.pendingConfigInits.set(cacheKey, initPromise);try {diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.tsindex 29d0db03ec..37d03e1869 100644--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts@@ -1,7 +1,10 @@import './helpers/setupCredsEnv';import { logger } from '@librechat/data-schemas';import type * as t from '~/mcp/types';-import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';+import {+ MCPServersRegistry,+ MCPConfigInitializationCanceledError,+} from '~/mcp/registry/MCPServersRegistry';import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';import { processMCPEnv } from '~/utils/env';@@ -136,6 +139,26 @@ describe('MCPServersRegistry', () => {expect(dbGetAll).toHaveBeenCalledTimes(2);});+ it('partitions role-filtered server maps when a user role changes', async () => {+ const dbGetAll = jest.spyOn(registry['dbConfigsRepo'], 'getAll');+ dbGetAll.mockResolvedValueOnce({ admin_server: testParsedConfig });+ dbGetAll.mockResolvedValueOnce({ user_server: testParsedConfig });++ await expect(registry.getAllServerConfigs('user-1', {}, 'ADMIN')).resolves.toEqual({+ admin_server: testParsedConfig,+ });+ await expect(registry.getAllServerConfigs('user-1', {}, 'USER')).resolves.toEqual({+ user_server: testParsedConfig,+ });+ await expect(registry.getAllServerConfigs('user-1', {}, 'USER')).resolves.toEqual({+ user_server: testParsedConfig,+ });++ expect(dbGetAll).toHaveBeenNthCalledWith(1, 'user-1', 'ADMIN');+ expect(dbGetAll).toHaveBeenNthCalledWith(2, 'user-1', 'USER');+ expect(dbGetAll).toHaveBeenCalledTimes(2);+ });+it('does not join or erase a single-flight fetch from another generation', async () => {let resolveOld!: (value: Record<string, t.ParsedServerConfig>) => void;let resolveFresh!: (value: Record<string, t.ParsedServerConfig>) => void;@@ -927,6 +950,73 @@ describe('MCPServersRegistry', () => {expect(result['config-only-server'].source).toBe('config');});+ it('lets duplicate cold initializations share one pending owner slot', async () => {+ let releaseInspection!: () => void;+ const inspectionGate = new Promise<void>((resolve) => {+ releaseInspection = resolve;+ });+ const inspectSpy = jest.spyOn(MCPServerInspector, 'inspect');+ inspectSpy.mockClear();+ inspectSpy.mockImplementationOnce(async (_serverName, rawConfig) => {+ await inspectionGate;+ return { ...testParsedConfig, ...rawConfig } as t.ParsedServerConfig;+ });+ const limitCalls = jest.fn();+ const limit = <T>(task: () => Promise<T>): Promise<T> => {+ limitCalls();+ return task();+ };+ const config = {+ shared: {+ type: 'streamable-http' as const,+ url: 'https://shared.example.com/mcp',+ },+ };++ const first = registry.ensureConfigServers(config, limit);+ const second = registry.ensureConfigServers(config, limit);+ await Promise.resolve();+ await Promise.resolve();+ releaseInspection();++ await expect(Promise.all([first, second])).resolves.toHaveLength(2);+ expect(inspectSpy).toHaveBeenCalledTimes(1);+ expect(limitCalls).toHaveBeenCalledTimes(1);+ });++ it('lets a healthy joiner replace a canceled pending initialization', async () => {+ let rejectOwner!: (error: Error) => void;+ const ownerGate = new Promise<never>((_resolve, reject) => {+ rejectOwner = reject;+ });+ const config = {+ shared: {+ type: 'streamable-http' as const,+ url: 'https://shared.example.com/mcp',+ },+ };+ const canceledLimitCalls = jest.fn();+ const canceledLimit = <T>(_task: () => Promise<T>): Promise<T> => {+ canceledLimitCalls();+ return ownerGate;+ };+ const healthyLimitCalls = jest.fn();+ const healthyLimit = <T>(task: () => Promise<T>): Promise<T> => {+ healthyLimitCalls();+ return task();+ };++ const canceled = registry.ensureConfigServers(config, canceledLimit);+ const healthy = registry.ensureConfigServers(config, healthyLimit);+ await Promise.resolve();+ rejectOwner(new MCPConfigInitializationCanceledError());++ await expect(canceled).resolves.toEqual({});+ await expect(healthy).resolves.toHaveProperty('shared');+ expect(canceledLimitCalls).toHaveBeenCalledTimes(1);+ expect(healthyLimitCalls).toHaveBeenCalledTimes(1);+ });+it('preserves YAML base entry when config-tier override reports inspectionFailed', async () => {const yamlSeed: t.ParsedServerConfig = {type: 'streamable-http',diff --git a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.tsindex bbee631e60..31a384d7a2 100644--- a/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts+++ b/packages/api/src/mcp/registry/__tests__/ensureConfigServers.test.ts@@ -88,6 +88,24 @@ describe('MCPServersRegistry — ensureConfigServers', () => {).toEqual({});});+ it('routes each config-source initialization through the supplied limiter', async () => {+ let limitCalls = 0;+ const limit = async <T>(task: () => Promise<T>): Promise<T> => {+ limitCalls += 1;+ return task();+ };++ const result = await registry.ensureConfigServers(+ { first: sseConfig, second: altSseConfig },+ limit,+ );++ expect(result).toEqual(+ expect.objectContaining({ first: expect.any(Object), second: expect.any(Object) }),+ );+ expect(limitCalls).toBe(2);+ });+it('should skip unchanged YAML-named servers but still process config-only servers', async () => {await registry.addServer('yaml_server', yamlConfig, 'CACHE');inspectSpy.mockClear();diff --git a/packages/api/src/schedules/README.md b/packages/api/src/schedules/README.mdnew file mode 100644index 0000000000..408641fa6d--- /dev/null+++ b/packages/api/src/schedules/README.md@@ -0,0 +1,40 @@+# Unattended MCP support++Scheduled chats validate the selected agent and its accessible graph agents before creation,+when enabling or changing the agent, and before each automatic or manual dispatch.+The check uses the persisted user document and plugin credentials, with temporary+user connections that are disposed afterwards. It does not borrow a browser session+or replace a live interactive connection. Graph agents are loaded in breadth-first+batches, and private children are skipped with the same VIEW rule as a live run.+Enabled spawn-agent members are included when the endpoint grants that capability.+The effective endpoint must grant the tools capability. Tool discovery uses the configured+per-admission concurrency (one to ten, default three), must complete, and must contain all+explicitly selected tools; wildcard selections require a nonempty catalog. Request disconnects+and scheduler shutdown cancel connection setup and discovery without advancing the occurrence.+Readiness admissions use a separate bounded pool and complete before a durable generation+slot is reserved, so slow MCP servers cannot consume generation capacity or block later+healthy occurrences from being considered.++Supported authentication is determined by a successful unattended connection:++- Static server credentials and anonymous servers.+- Persisted custom user variables, including API keys.+- Stored MCP OAuth credentials that can connect or refresh without user interaction.++Browser-only credentials, interactive OpenID bearer/OBO sources, missing user+variables, and OAuth grants needing renewed consent cannot be assumed available.+Reconnect or configure the server in an interactive agent chat, or remove it from the+agent, then enable the schedule. A browser connection alone does not prove readiness;+enabling always reruns the unattended check.++`mcp_reauth_required`, `mcp_configuration_missing`, and `mcp_permission_denied` stop a+scheduled occurrence and disable the schedule immediately. The permission status tells+the owner that an administrator must restore MCP use access. `mcp_unavailable` counts+toward the existing configured consecutive-failure threshold. Credential-store and+configuration-store outages are transient; they must never be treated as proof of missing credentials.+Failure records contain only server names and resolution statuses, never exception+messages or OAuth URLs. Successful dispatch records also retain the server outcomes.++The schedule card shows failed servers and links to the selected agent for recovery.+A pure pause remains available even when MCP validation fails. This change does not+re-enable existing schedules automatically or repair credentials on the user's behalf.diff --git a/packages/api/src/schedules/engine.spec.ts b/packages/api/src/schedules/engine.spec.tsindex be7b2e943b..5698bc3a72 100644--- a/packages/api/src/schedules/engine.spec.ts+++ b/packages/api/src/schedules/engine.spec.ts@@ -9,7 +9,10 @@ const LIMITS: ScheduleLimits = {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,};@@ -78,6 +81,7 @@ function makeDeps(getLimits: async () => LIMITS,getUserContext: async () => OWNER,isOutOfBalance: async () => false,+ preflightMCP: jest.fn().mockResolvedValue([]),agentAccess: async () => 'ok',hasScheduleAccess: async () => true,resolveFiles: async () => [],@@ -175,6 +179,71 @@ describe('runTick misfire skip-forward', () => {});describe('runTick error handling', () => {+ it('uses readiness admission capacity independently of generation capacity', async () => {+ const schedules = Array.from({ length: 6 }, (_, index) =>+ makeClaimedSchedule({+ id: `sched-${index}`,+ user: `user-${index}` as never,+ claimToken: `ct-${index}`,+ leaseBy: `inst-${index}`,+ }),+ );+ const methods = makeMethods(schedules[0]);+ const claims: Array<FireableSchedule | null> = [...schedules, null];+ methods.claimDueSchedule.mockImplementation(async () => claims.shift() ?? null);+ methods.countActiveRuns.mockResolvedValue(5);+ const getUserContext = jest.fn(async () => null);++ await tickOnce(+ makeDeps(methods, {+ getLimits: async () => ({ ...LIMITS, admissionConcurrency: 6, fireConcurrency: 1 }),+ getUserContext,+ }),+ );++ expect(getUserContext).toHaveBeenCalledTimes(6);+ expect(methods.countActiveRuns).not.toHaveBeenCalled();+ });++ it('starts later admissions while an earlier schedule is still in preflight', async () => {+ const first = makeClaimedSchedule();+ const second = makeClaimedSchedule({+ id: 'sched-2',+ user: 'user-2' as never,+ claimToken: 'ct-2',+ leaseBy: 'inst-2',+ });+ const methods = makeMethods(first);+ const claims = [first, second, null];+ methods.claimDueSchedule.mockImplementation(async () => claims.shift() ?? null);+ let releaseFirst!: () => void;+ const firstPreflight = new Promise<void>((resolve) => {+ releaseFirst = resolve;+ });+ let markSecondStarted!: () => void;+ const secondStarted = new Promise<void>((resolve) => {+ markSecondStarted = resolve;+ });+ const getUserContext = jest.fn(+ async (userId: Parameters<ScheduleEngineDeps['getUserContext']>[0]) => {+ if (String(userId) === 'user-1') {+ await firstPreflight;+ } else {+ markSecondStarted();+ }+ return null;+ },+ );+ const engine = startScheduleEngine(makeDeps(methods, { getUserContext }));++ const tick = engine.runTick();+ await secondStarted;+ expect(getUserContext).toHaveBeenCalledWith('user-2');+ releaseFirst();+ await expect(tick).resolves.toBe(0);+ engine.stop();+ });+it('retains the due occurrence when a preflight query throws', async () => {const schedule = makeClaimedSchedule();const methods = makeMethods(schedule);@@ -271,6 +340,46 @@ describe('reconciliation consults the durable trigger delivery', () => {);});+ it('replays admission-only MCP evidence without consulting a generation job', async () => {+ const methods = makeMethods(makeClaimedSchedule());+ (methods.getRunsForReconciliation as jest.Mock).mockResolvedValue([+ {+ ...joblessRun(YOUNG()),+ admissionOnly: true,+ error: 'mcp_configuration_missing',+ mcp: [+ {+ server: 'Notion',+ agentId: 'research-agent',+ status: 'mcp_configuration_missing',+ },+ ],+ },+ ]);+ const getJobStatus = jest.fn(async () => {+ throw new Error('admission-only rows have no job');+ });++ await tickOnce(makeDeps(methods, { getJobStatus }));++ expect(getJobStatus).not.toHaveBeenCalled();+ expect(methods.recordRunOutcome).toHaveBeenCalledWith(+ expect.objectContaining({+ scheduleId: 's1',+ status: 'error',+ error: 'mcp_configuration_missing',+ clearConversationId: true,+ mcp: [+ {+ server: 'Notion',+ agentId: 'research-agent',+ status: 'mcp_configuration_missing',+ },+ ],+ }),+ );+ });+it('does NOT orphan a PENDING delivery past the cutoff (Retry-After may still fire it)', async () => {const methods = await runReconcile(joblessRun(OLD()), async () => ({ status: 'pending' }));expect(methods.recordRunOutcome).not.toHaveBeenCalled();@@ -424,6 +533,7 @@ describe('bookkeeping replay rotation', () => {user: 'u1',status: 'success',conversationId: 'convo-crashed',+ mcp: [{ server: 'Notion', agentId: 'research-agent', status: 'ready' }],};(methods.getUnbookkeptRuns as jest.Mock).mockResolvedValue([unbookkept]);const clearReconciledJob = jest.fn(async () => undefined);@@ -431,7 +541,10 @@ describe('bookkeeping replay rotation', () => {await reconcileOnce(makeDeps(methods, { clearReconciledJob }));expect(methods.finalizeBookkeeping).toHaveBeenCalledWith(- expect.objectContaining({ scheduleId: 'sched-crashed' }),+ expect.objectContaining({+ scheduleId: 'sched-crashed',+ mcp: [{ server: 'Notion', agentId: 'research-agent', status: 'ready' }],+ }),);expect(clearReconciledJob).toHaveBeenCalledWith('convo-crashed', {scheduleId: 'sched-crashed',diff --git a/packages/api/src/schedules/engine.ts b/packages/api/src/schedules/engine.tsindex af2325d307..e32aed21e4 100644--- a/packages/api/src/schedules/engine.ts+++ b/packages/api/src/schedules/engine.ts@@ -42,6 +42,7 @@ export type ScheduleEngine = {export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {let stopped = false;+ const stopController = new AbortController();let timer: NodeJS.Timeout | undefined;let ticks = 0;const instanceId = `${process.pid}-${Math.random().toString(36).slice(2, 8)}`;@@ -68,16 +69,12 @@ export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {// settles, so it has to make progress on the rest; the examined-at stamp// below then rotates failures behind rows this pass did not inspect.try {+ let jobState: Awaited<ReturnType<typeof deps.getJobStatus>> | null = null;// Identity-fence the job lookup: a replacement user turn reuses this// conversationId but sheds the scheduleId/scheduledFor metadata. Only// trust the job's status when it still carries THIS occurrence's identity;// otherwise treat the job as gone (null) so a replacement generation's// status can never finalize — or its hash be deleted for — this run.- const jobState = run.conversationId- ? await deps.getJobStatus(run.conversationId)- : null;- const jobStatus = jobIdentityMatches(jobState, run) ? jobState!.status : null;- const ageMs = Date.now() - (run.firedAt?.getTime() ?? 0);// Resolve the run owner's limits so crash-reconciled auto-disable uses// the same per-principal threshold as an inline completion. Must run in// the OWNER's tenant context: getLimits resolves config via the ALS@@ -105,8 +102,21 @@ export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {conversationId: opts?.omitConversationId ? undefined : run.conversationId,clearConversationId: opts?.omitConversationId,error,+ ...(run.mcp ? { mcp: run.mcp } : {}),autoDisableAfterFailures: runLimits.autoDisableAfterFailures,});+ // Admission-only rows never reached the delivery or generation layers.+ // Their deterministic failure was stored with the reservation, so replay it+ // directly instead of waiting for the generic orphan timeout.+ if (run.status === 'started' && run.admissionOnly) {+ await finalize('error', run.error ?? 'MCP preflight unavailable', {+ omitConversationId: true,+ });+ continue;+ }+ jobState = run.conversationId ? await deps.getJobStatus(run.conversationId) : null;+ const jobStatus = jobIdentityMatches(jobState, run) ? jobState!.status : null;+ const ageMs = Date.now() - (run.firedAt?.getTime() ?? 0);// The clear runs AFTER finalize (the retained job is the only evidence if// the finalize write fails), which means a clear that keeps failing has no// natural retry: the now-terminal run never rescans, so nothing else would@@ -300,6 +310,7 @@ export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {| 'skipped_overlap',conversationId: run.conversationId,error: run.error,+ mcp: run.mcp,autoDisableAfterFailures: runLimits.autoDisableAfterFailures,balanceSkipDisableThreshold: BALANCE_SKIP_DISABLE_THRESHOLD,});@@ -421,140 +432,156 @@ export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {// still honored. The base config only supplies the per-tick claim budget.const limits = await deps.getLimits();let fired = 0;- // Cap on ACTIVE scheduled runs, not just per-tick starts: the loopback chat- // endpoint returns as soon as the generation starts and scheduled fires- // bypass the interactive limiter, so without this the in-flight count would- // grow by fireConcurrency every tick. Only claim up to the free headroom.- const active = await runAsSystem(() => deps.methods.countActiveRuns());- const budget = Math.max(0, limits.fireConcurrency - active);+ // Admission has its own bounded pool. MCP readiness runs before a generation+ // slot is reserved, so slow external servers cannot make generation occupancy+ // suppress later healthy claims. The durable capacity allocator in fireSchedule+ // remains the cross-replica authority for actual generations.+ const budget = limits.admissionConcurrency;+ const fires: Promise<unknown>[] = [];for (let i = 0; i < budget; i++) {// Claim + the fire's pre-owner-context bookkeeping (disable/advance,// cross-tenant reads) run as system; fireSchedule re-enters owner context// internally for the run-specific work.- const done = await runAsSystem(async () => {- const schedule = await deps.methods.claimDueSchedule({ instanceId, leaseMs: LEASE_MS });- if (schedule == null) {- return true;- }- const scheduledFor = schedule.nextRunAt ?? new Date();- /**- * Advances this claimed occurrence without preserving a superseded holder.- * Owner edits rotate the token/next occurrence but intentionally leave the old- * lease in place; a fenced miss therefore releases only this worker's unique- * holder. Infrastructure errors keep the lease as retry backoff, as before.- */- const advanceClaim = async (nextRunAt: Date | null): Promise<void> => {+ const schedule = await runAsSystem(() =>+ deps.methods.claimDueSchedule({ instanceId, leaseMs: LEASE_MS }),+ );+ if (schedule == null) {+ break;+ }+ // Start each admission as soon as its claim lands. MCP preflight is bounded but+ // can legitimately wait for its full deadline; awaiting it here used to hold the+ // claim loop and could push healthy schedules beyond the misfire grace window.+ // The claim budget still caps this batch, and the durable capacity allocator in+ // fireSchedule arbitrates against work started by concurrent engine replicas.+ fires.push(+ runAsSystem(async () => {+ const scheduledFor = schedule.nextRunAt ?? new Date();+ /**+ * Advances this claimed occurrence without preserving a superseded holder.+ * Owner edits rotate the token/next occurrence but intentionally leave the old+ * lease in place; a fenced miss therefore releases only this worker's unique+ * holder. Infrastructure errors keep the lease as retry backoff, as before.+ */+ const advanceClaim = async (nextRunAt: Date | null): Promise<void> => {+ try {+ const advanced = await deps.methods.advanceSchedule(+ schedule.id,+ nextRunAt,+ scheduledFor,+ schedule.claimToken,+ );+ if (!advanced && schedule.leaseBy != null) {+ await deps.methods.releaseLeaseByHolder(schedule.id, schedule.leaseBy);+ }+ } catch {+ // Leave the claim lease as bounded backoff for transient storage failures.+ }+ };+ // Use the CLAIM's clock for the misfire cutoff: the claim wrote+ // leaseUntil = now + LEASE_MS from the claiming worker's clock, so+ // leaseUntil - LEASE_MS is that worker's "now" at claim — usually this very+ // process, making cutoff and claim self-consistent. (DocumentDB rules out the+ // server-clock `$$NOW` CAS; skew between REPLICAS shifts fire timing by at+ // most the skew and can never double-fire — the lease CAS and the unique+ // occurrence index arbitrate that regardless of clocks.)+ const dbNow = schedule.leaseUntil ? schedule.leaseUntil.getTime() - LEASE_MS : Date.now();+ // Misfire skip-forward: an occurrence overdue past the grace window (the+ // engine was down/paused) is advanced to the next FUTURE occurrence+ // without firing, so a restart doesn't launch stale or bursty chats.+ if (dbNow - scheduledFor.getTime() > MISFIRE_GRACE_MS) {+ const next = computeNextRunAt({+ cadence: schedule.cadence,+ timezone: schedule.timezone,+ scheduleId: schedule.id,+ // The claim's own clock (see dbNow above): a clock-behind worker would+ // otherwise compute another already-due occurrence and reclaim the row.+ after: new Date(dbNow),+ });+ if (next == null) {+ // Uncomputable cadence is NOT transient, so this occurrence can never run.+ // The advance below would clear nextRunAt AND the lease; doing that after a+ // transiently failed disable would leave `enabled: true` with no nextRunAt+ // and no disabledReason, permanently unclaimable and invisible. Bail+ // instead: the lease expires and the occurrence is retried.+ const disabled = await deps.methods+ .disableSchedule(schedule.id, 'invalid_schedule', schedule.claimToken)+ .then(() => true)+ .catch(() => false);+ if (!disabled) {+ return false;+ }+ }+ // The SKIP-FORWARD itself, and the whole point of this branch: move to the+ // next FUTURE occurrence. Without it nextRunAt keeps pointing at the stale+ // one, so every later tick reclaims and skips the same occurrence forever and+ // a schedule overdue past an outage never fires again.+ await advanceClaim(next);+ logger.info(`[schedules] skipped stale occurrence for ${schedule.id} (misfire grace)`);+ return false;+ }try {- const advanced = await deps.methods.advanceSchedule(- schedule.id,- nextRunAt,+ const result = await fireSchedule(+ // The dispatch boundary observes shutdown from BOTH signals: the+ // coordinator flag flips before the listener starts closing (ahead of+ // any pre-drain task ordering), and the engine's own stop covers direct+ // runTick callers outside a coordinated shutdown.+ { ...deps, isShuttingDown: () => stopped || isShutdownInProgress() },+ schedule,+ limits,scheduledFor,- schedule.claimToken,+ {+ dbNow: new Date(dbNow),+ signal: stopController.signal,+ },);- if (!advanced && schedule.leaseBy != null) {- await deps.methods.releaseLeaseByHolder(schedule.id, schedule.leaseBy);- }- } catch {- // Leave the claim lease as bounded backoff for transient storage failures.- }- };- // Use the CLAIM's clock for the misfire cutoff: the claim wrote- // leaseUntil = now + LEASE_MS from the claiming worker's clock, so- // leaseUntil - LEASE_MS is that worker's "now" at claim — usually this very- // process, making cutoff and claim self-consistent. (DocumentDB rules out the- // server-clock `$$NOW` CAS; skew between REPLICAS shifts fire timing by at- // most the skew and can never double-fire — the lease CAS and the unique- // occurrence index arbitrate that regardless of clocks.)- const dbNow = schedule.leaseUntil ? schedule.leaseUntil.getTime() - LEASE_MS : Date.now();- // Misfire skip-forward: an occurrence overdue past the grace window (the- // engine was down/paused) is advanced to the next FUTURE occurrence- // without firing, so a restart doesn't launch stale or bursty chats.- if (dbNow - scheduledFor.getTime() > MISFIRE_GRACE_MS) {- const next = computeNextRunAt({- cadence: schedule.cadence,- timezone: schedule.timezone,- scheduleId: schedule.id,- // The claim's own clock (see dbNow above): a clock-behind worker would- // otherwise compute another already-due occurrence and reclaim the row.- after: new Date(dbNow),- });- if (next == null) {- // Uncomputable cadence is NOT transient, so this occurrence can never run.- // The advance below would clear nextRunAt AND the lease; doing that after a- // transiently failed disable would leave `enabled: true` with no nextRunAt- // and no disabledReason, permanently unclaimable and invisible. Bail- // instead: the lease expires and the occurrence is retried.- const disabled = await deps.methods- .disableSchedule(schedule.id, 'invalid_schedule', schedule.claimToken)- .then(() => true)- .catch(() => false);- if (!disabled) {- return false;+ if (result.fired) {+ fired += 1;}- }- // The SKIP-FORWARD itself, and the whole point of this branch: move to the- // next FUTURE occurrence. Without it nextRunAt keeps pointing at the stale- // one, so every later tick reclaims and skips the same occurrence forever and- // a schedule overdue past an outage never fires again.- await advanceClaim(next);- logger.info(`[schedules] skipped stale occurrence for ${schedule.id} (misfire grace)`);- return false;- }- try {- const result = await fireSchedule(- // The dispatch boundary observes shutdown from BOTH signals: the- // coordinator flag flips before the listener starts closing (ahead of- // any pre-drain task ordering), and the engine's own stop covers direct- // runTick callers outside a coordinated shutdown.- { ...deps, isShuttingDown: () => stopped || isShutdownInProgress() },- schedule,- limits,- scheduledFor,- {- dbNow: new Date(dbNow),- },- );- if (result.fired) {- fired += 1;- }- } catch (error) {- // A transient preflight throw (user/config/permission/balance/capacity query)- // must NOT advance past this occurrence: advancing schedules the NEXT- // recurrence, so the due one is discarded permanently with no ScheduleRun row- // and no evidence it was ever attempted. Leave nextRunAt alone and keep the- // claim lease as backoff — the lease expires and the SAME occurrence is- // re-claimed and retried, matching how the fire path already treats a- // transient file-resolution failure.- logger.error(`[schedules] unexpected fire error for ${schedule.id} (will retry):`, error);- // An UNCOMPUTABLE cadence is the one non-transient case: retrying can never- // make progress, and leaving the lease would re-claim the same occurrence- // forever. Disable so it stops being due, and only then clear nextRunAt —- // advancing on a failed disable would leave `enabled: true` with no nextRunAt- // and no disabledReason (permanently unclaimable and invisible). Everything- // else falls through untouched: nextRunAt and the lease both stand.- const next = computeNextRunAt({- cadence: schedule.cadence,- timezone: schedule.timezone,- scheduleId: schedule.id,- // The claim's clock (see the misfire branch) so a skewed worker doesn't- // reschedule to an already-due occurrence and reclaim the same row.- after: new Date(dbNow),- });- if (next == null) {- const disabled = await deps.methods- .disableSchedule(schedule.id, 'invalid_schedule', schedule.claimToken)- .then(() => true)- .catch(() => false);- if (disabled) {- await advanceClaim(null);+ } catch (error) {+ // A transient preflight throw (user/config/permission/balance/capacity query)+ // must NOT advance past this occurrence: advancing schedules the NEXT+ // recurrence, so the due one is discarded permanently with no ScheduleRun row+ // and no evidence it was ever attempted. Leave nextRunAt alone and keep the+ // claim lease as backoff — the lease expires and the SAME occurrence is+ // re-claimed and retried, matching how the fire path already treats a+ // transient file-resolution failure.+ logger.error(+ `[schedules] unexpected fire error for ${schedule.id} (will retry):`,+ error,+ );+ // An UNCOMPUTABLE cadence is the one non-transient case: retrying can never+ // make progress, and leaving the lease would re-claim the same occurrence+ // forever. Disable so it stops being due, and only then clear nextRunAt —+ // advancing on a failed disable would leave `enabled: true` with no nextRunAt+ // and no disabledReason (permanently unclaimable and invisible). Everything+ // else falls through untouched: nextRunAt and the lease both stand.+ const next = computeNextRunAt({+ cadence: schedule.cadence,+ timezone: schedule.timezone,+ scheduleId: schedule.id,+ // The claim's clock (see the misfire branch) so a skewed worker doesn't+ // reschedule to an already-due occurrence and reclaim the same row.+ after: new Date(dbNow),+ });+ if (next == null) {+ const disabled = await deps.methods+ .disableSchedule(schedule.id, 'invalid_schedule', schedule.claimToken)+ .then(() => true)+ .catch(() => false);+ if (disabled) {+ await advanceClaim(null);+ }}}- }- return false;- });- if (done) {- break;- }+ }),+ );+ }+ const results = await Promise.allSettled(fires);+ const rejected = results.find(+ (result): result is PromiseRejectedResult => result.status === 'rejected',+ );+ if (rejected) {+ throw rejected.reason;}return fired;}@@ -597,6 +624,7 @@ export function startScheduleEngine(deps: ScheduleEngineDeps): ScheduleEngine {const engine: ScheduleEngine = {stop: () => {stopped = true;+ stopController.abort(new Error('Schedule engine stopped'));if (timer) {clearTimeout(timer);timer = undefined;diff --git a/packages/api/src/schedules/fire.spec.ts b/packages/api/src/schedules/fire.spec.tsindex 67b5acd9ba..c01138a2b2 100644--- a/packages/api/src/schedules/fire.spec.ts+++ b/packages/api/src/schedules/fire.spec.ts@@ -5,6 +5,7 @@ import { getAgentTriggerIdempotencyKey } from '../agents/triggers/envelope';import { AgentTriggerDeliveryError } from '../agents/triggers/delivery';import { buildFireClientRequestId, fireSchedule } from './fire';import { withCapacitySlot } from './capacity';+import { ScheduleMCPError } from './mcp';const OWNER: ScheduleUserContext = { id: 'user-1', tenantId: 't1', role: 'USER' };const LIMITS: ScheduleLimits = {@@ -12,7 +13,10 @@ const LIMITS: ScheduleLimits = {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,};@@ -41,7 +45,7 @@ function makeSchedule(overrides: Partial<FireableSchedule> = {}): FireableSchedufunction makeMethods() {const runs = new Map<string,- { status: string; conversationId?: string; capacitySlot?: number }+ { status: string; conversationId?: string; capacitySlot?: number; admissionOnly?: boolean }>();const calls = {advance: 0,@@ -88,6 +92,7 @@ function makeMethods() {scheduledFor: Date;conversationId?: string;capacitySlot?: number;+ admissionOnly?: boolean;deliveryKey?: string;}) => {const k = key(data.scheduleId, data.scheduledFor);@@ -115,6 +120,7 @@ function makeMethods() {status: 'started',conversationId: data.conversationId,capacitySlot: data.capacitySlot,+ admissionOnly: data.admissionOnly,});return { run: { scheduleId: data.scheduleId, scheduledFor: data.scheduledFor } };},@@ -126,6 +132,9 @@ function makeMethods() {if (r.status !== 'started') {continue;}+ if (r.admissionOnly) {+ continue;+ }if (typeof r.capacitySlot === 'number') {takenSlots.push(r.capacitySlot);} else {@@ -175,6 +184,7 @@ function makeDeps(getLimits: async () => LIMITS,getUserContext: async () => OWNER,isOutOfBalance: async () => false,+ preflightMCP: jest.fn().mockResolvedValue([]),agentAccess: async () => 'ok',hasScheduleAccess: async () => true,resolveFiles: async () => [],@@ -256,6 +266,21 @@ describe('buildFireClientRequestId', () => {});describe('fireSchedule', () => {+ it('preserves a claimed occurrence when the deployment switch turns off', async () => {+ const { methods } = makeMethods();+ const getLimits = jest.fn(async () => ({ ...LIMITS, enabled: false }));+ const deps = makeDeps(methods, {+ getLimits,+ });++ const result = await fireSchedule(deps, makeSchedule(), LIMITS, dueAt());++ expect(result).toMatchObject({ fired: false, skipped: 'superseded' });+ expect(methods.advanceSchedule).not.toHaveBeenCalled();+ expect(methods.releaseLeaseByHolder).toHaveBeenCalledWith('sched-1', 'inst-1');+ expect(getLimits).toHaveBeenCalledWith();+ });+it('fires the happy path and records fire details', async () => {const { methods, runs } = makeMethods();mockFetch(async () => okResponse());@@ -496,6 +521,27 @@ describe('fireSchedule', () => {expect(methods.deleteScheduleRun).not.toHaveBeenCalled();});+ it('completes readiness before requesting generation capacity', async () => {+ const { methods } = makeMethods();+ const order: string[] = [];+ const deps = makeDeps(methods, {+ preflightMCP: async () => {+ order.push('readiness');+ return [];+ },+ withGlobalCapacitySlot: async (_cap, claim) => {+ order.push('generation-capacity');+ const attempt = await claim(0);+ return attempt === 'slot-taken' ? 'capacity' : attempt;+ },+ });+ mockFetch(async () => okResponse());++ await fireSchedule(deps, makeSchedule(), LIMITS, dueAt());++ expect(order).toEqual(['readiness', 'generation-capacity']);+ });+it('does not let a principal override widen the global capacity cap', async () => {const { methods, runs } = makeMethods();// The single deployment-wide slot is already occupied.@@ -513,6 +559,7 @@ describe('fireSchedule', () => {expect(result.skipped).toBe('capacity');expect(global.fetch).not.toHaveBeenCalled();expect(methods.reserveStartedRun).not.toHaveBeenCalled();+ expect(methods.releaseLease).toHaveBeenCalledWith('sched-1', 'ct-1');});it('still honors an owner override that is STRICTER than the deployment cap', async () => {@@ -818,3 +865,181 @@ describe('fireSchedule', () => {expect(calls.advance).toBe(0);});});++it('settles an unavailable MCP occurrence without dispatching a generation', async () => {+ const { methods } = makeMethods();+ const failure = new ScheduleMCPError([{ server: 'Notion', status: 'mcp_reauth_required' }]);+ const deps = makeDeps(methods, {+ preflightMCP: async () => {+ throw failure;+ },+ });+ const capacitySpy = jest.spyOn(deps, 'withGlobalCapacitySlot');+ const result = await fireSchedule(deps, makeSchedule(), LIMITS, new Date('2026-09-09T12:00:00Z'));+ expect(result).toMatchObject({ fired: false, mcp: failure.outcomes });+ expect(capacitySpy).not.toHaveBeenCalled();+ expect(methods.reserveStartedRun).toHaveBeenCalledWith(+ expect.objectContaining({+ admissionOnly: true,+ error: failure.message,+ mcp: failure.outcomes,+ }),+ );+ expect(deps.enqueueTrigger).not.toHaveBeenCalled();+ expect(methods.recordRunOutcome).toHaveBeenCalledWith(+ expect.objectContaining({+ error: failure.message,+ status: 'error',+ clearConversationId: true,+ mcp: failure.outcomes,+ }),+ );+});++it('does not settle or disable from a failed MCP preflight after losing its claim', async () => {+ const { methods } = makeMethods();+ (methods.revalidateClaim as jest.Mock).mockResolvedValueOnce(true).mockResolvedValue(false);+ const deps = makeDeps(methods, {+ preflightMCP: async () => {+ throw new ScheduleMCPError([{ server: 'Notion', status: 'mcp_reauth_required' }]);+ },+ });+ const result = await fireSchedule(deps, makeSchedule(), LIMITS, new Date('2026-09-09T12:00:00Z'));+ expect(result.skipped).toBe('superseded');+ expect(methods.recordRunOutcome).not.toHaveBeenCalled();+ expect(methods.advanceSchedule).not.toHaveBeenCalled();+});++it('does not invent a server outcome for infrastructure preflight failures', async () => {+ const { methods } = makeMethods();+ const deps = makeDeps(methods, {+ preflightMCP: async () => {+ throw new Error('role database unavailable with private details');+ },+ });+ const result = await fireSchedule(deps, makeSchedule(), LIMITS, new Date('2026-09-09T12:00:00Z'));+ expect(result).toMatchObject({+ fired: false,+ error: 'MCP preflight unavailable',+ mcpPreflightUnavailable: true,+ });+ expect(result.mcp).toBeUndefined();+ expect(methods.recordRunOutcome).toHaveBeenCalledWith(+ expect.objectContaining({ error: 'MCP preflight unavailable' }),+ );+});++it('bounds MCP preflight by the claim lease and the stricter concurrency config', async () => {+ const { methods } = makeMethods();+ const leaseUntil = new Date(Date.now() + 10_000);+ const failure = new ScheduleMCPError([{ server: 'Notion', status: 'mcp_unavailable' }]);+ const preflightMCP = jest.fn(async () => {+ throw failure;+ });+ const deps = makeDeps(methods, {+ preflightMCP,+ getLimits: async (user) => ({+ ...LIMITS,+ mcpPreflightConcurrency: user == null ? 2 : 5,+ }),+ });++ await fireSchedule(deps, makeSchedule({ leaseUntil }), LIMITS, new Date('2026-09-09T12:00:00Z'));++ expect(preflightMCP).toHaveBeenCalledWith(+ 'agent-1',+ OWNER,+ expect.objectContaining({ concurrency: 2, deadlineMs: leaseUntil.getTime() }),+ );+});++it('bounds MCP preflight by the stricter owner and deployment timeout', async () => {+ const { methods } = makeMethods();+ const startedAt = Date.now();+ let deadlineMs: number | undefined;+ const preflightMCP: ScheduleEngineDeps['preflightMCP'] = async (_agentId, _user, options) => {+ deadlineMs = options?.deadlineMs;+ return [];+ };+ const deps = makeDeps(methods, {+ preflightMCP,+ getLimits: async (user) => ({+ ...LIMITS,+ mcpPreflightTimeoutMs: user == null ? 12_000 : 20_000,+ }),+ });++ await fireSchedule(+ deps,+ makeSchedule({ leaseUntil: new Date(startedAt + 240_000) }),+ LIMITS,+ new Date('2026-09-09T12:00:00Z'),+ );++ expect(deadlineMs).toBeGreaterThanOrEqual(startedAt + 11_900);+ expect(deadlineMs).toBeLessThanOrEqual(Date.now() + 12_000);+});++it('cancels MCP preflight before reserving or recording a run', async () => {+ const { methods } = makeMethods();+ const controller = new AbortController();+ const deps = makeDeps(methods, {+ preflightMCP: async (_agentId, _user, options) => {+ expect(options?.signal).toBe(controller.signal);+ controller.abort(new Error('schedule engine stopped'));+ throw controller.signal.reason;+ },+ });++ const result = await fireSchedule(+ deps,+ makeSchedule(),+ LIMITS,+ new Date('2026-09-09T12:00:00Z'),+ { signal: controller.signal },+ );++ expect(result).toMatchObject({ fired: false, skipped: 'superseded' });+ // Readiness now runs before generation reservation, so cancellation has no+ // started row or capacity slot to roll back.+ expect(methods.deleteScheduleRun).not.toHaveBeenCalled();+ expect(methods.recordRunOutcome).not.toHaveBeenCalled();+ expect(methods.advanceSchedule).not.toHaveBeenCalled();+});++it('does not enqueue when Run Now is cancelled during final claim validation', async () => {+ const { methods } = makeMethods();+ const controller = new AbortController();+ let releaseValidation: () => void = () => undefined;+ let markValidationStarted: () => void = () => undefined;+ const validationStarted = new Promise<void>((resolve) => {+ markValidationStarted = resolve;+ });+ const validationGate = new Promise<void>((resolve) => {+ releaseValidation = resolve;+ });+ let validations = 0;+ (methods.revalidateClaim as jest.Mock).mockImplementation(async () => {+ validations += 1;+ if (validations === 2) {+ markValidationStarted();+ await validationGate;+ }+ return true;+ });+ const deps = makeDeps(methods);++ const pending = fireSchedule(deps, makeSchedule(), LIMITS, new Date('2026-09-09T12:00:00Z'), {+ manual: true,+ signal: controller.signal,+ });+ await validationStarted;+ controller.abort(new Error('Run Now request closed'));+ releaseValidation();+ const result = await pending;++ expect(result).toMatchObject({ fired: false, skipped: 'superseded' });+ expect(methods.deleteScheduleRun).toHaveBeenCalled();+ expect(deps.enqueueTrigger).not.toHaveBeenCalled();+ expect(methods.recordRunOutcome).not.toHaveBeenCalled();+});diff --git a/packages/api/src/schedules/fire.ts b/packages/api/src/schedules/fire.tsindex 55c372827f..a8cea11411 100644--- a/packages/api/src/schedules/fire.ts+++ b/packages/api/src/schedules/fire.ts@@ -12,6 +12,7 @@ import { AgentTriggerServiceUnavailableError } from '../agents/triggers/service'import { AgentTriggerDeliveryError } from '../agents/triggers/delivery';import { computeNextRunAt, cadenceIntervalMinutes } from './cadence';import { resolveScheduleProjectId } from './types';+import { ScheduleMCPError } from './mcp';/** Consecutive balance skips (pre-fire or mid-generation) before auto-disable. */export const BALANCE_SKIP_DISABLE_THRESHOLD: number = 5;@@ -127,7 +128,7 @@ export async function fireSchedule(schedule: FireableSchedule,limits: ScheduleLimits,scheduledFor: Date,- options?: { manual?: boolean; dbNow?: Date },+ options?: { manual?: boolean; dbNow?: Date; signal?: AbortSignal },): Promise<FireResult> {const { methods } = deps;// Compute the NEXT occurrence relative to the CLAIM's clock (the engine passes@@ -250,7 +251,15 @@ export async function fireSchedule(// a tenant- or role-specific config (disabled schedules, different// auto-disable threshold) must win over the base config the engine read.const ownerLimits = await deps.getLimits(user);+ const deploymentLimits = await deps.getLimits();if (!ownerLimits.enabled) {+ // A deployment-wide stop freezes due occurrences. The engine may have claimed+ // this one just before the switch changed, so hand its lease back without+ // advancing. A principal-scoped disable still consumes the occurrence because+ // that owner is not allowed to dispatch it under the current policy.+ if (!deploymentLimits.enabled) {+ return stepAsideSuperseded();+ }await advance();return { fired: false, skipped: 'disabled' as const };}@@ -428,6 +437,42 @@ export async function fireSchedule(return stepAsideSuperseded();}+ // Readiness is admission work, not generation work. Probe before reserving a+ // durable started row or a global generation slot so a slow MCP endpoint cannot+ // consume the capacity healthy ready schedules need to dispatch.+ let mcp: Awaited<ReturnType<ScheduleEngineDeps['preflightMCP']>> = [];+ let mcpFailure: { error: ScheduleMCPError | null; message: string } | null = null;+ try {+ const leaseDeadline = schedule.leaseUntil?.getTime() ?? Number.POSITIVE_INFINITY;+ const preflightDeadline =+ Date.now() ++ Math.min(ownerLimits.mcpPreflightTimeoutMs, deploymentLimits.mcpPreflightTimeoutMs);+ mcp = await deps.preflightMCP(schedule.agent_id, user, {+ signal: options?.signal,+ concurrency: Math.min(+ ownerLimits.mcpPreflightConcurrency,+ deploymentLimits.mcpPreflightConcurrency,+ ),+ deadlineMs: Math.min(leaseDeadline, preflightDeadline),+ });+ } catch (error) {+ if (options?.signal?.aborted) {+ return stepAsideSuperseded();+ }+ if (+ claimToken != null &&+ !(await methods.revalidateClaim(schedule.id, claimToken, !options?.manual))+ ) {+ return stepAsideSuperseded();+ }+ const failure = error instanceof ScheduleMCPError ? error : null;+ mcpFailure = { error: failure, message: failure?.message ?? 'MCP preflight unavailable' };+ }++ if (options?.signal?.aborted) {+ return stepAsideSuperseded();+ }+// Pre-generate the conversation id and reserve the run row up front. The// loopback POST reuses it (streamId === conversationId), so reconciliation can// ALWAYS locate this occurrence's job — even if the post-accept detail write@@ -466,56 +511,88 @@ export async function fireSchedule(};}const deliveryKey = getAgentTriggerIdempotencyKey(triggerEnvelope);- // The GLOBAL fireConcurrency cap is enforced by claiming a unique capacity slot in- // the SAME insert that reserves the run, so it is decided by the DB rather than by- // a count read before the write. The allocator advances to the next free slot when- // another admission wins one, and reports 'capacity' only when genuinely saturated.- // Occupancy is read system-scoped so the cap stays global across tenants.- // CLAMPED to the deployment-wide cap. The slots are global across every owner, so a- // role/user/tenant override must never be able to WIDEN them: manual Run Now resolves- // the owner's limits and bypasses the engine tick's base-config budget entirely, so- // an override of 5 against a base of 1 would otherwise let concurrent clicks occupy- // slots 0-4 and run five billed generations at once. Re-read without a principal for- // the base value (the same read the tick budgets from); a STRICTER owner value still- // applies, since only widening is the defect.- const deploymentLimits = await deps.getLimits();- const allocation = await deps.withGlobalCapacitySlot(- Math.min(ownerLimits.fireConcurrency, deploymentLimits.fireConcurrency),- async (capacitySlot) => {- const attempt = await methods.reserveStartedRun({- ...baseRun,- conversationId,- firedAt: new Date(),- capacitySlot,- deliveryKey,- // The destination THIS occurrence used. The schedule-level value can move on- // (a pin redirects later fires, and a paused run does not block them), so a- // resume must re-validate what its own conversation was filed under.- // ALWAYS written, `null` when deliberately unscoped: a later reader has to be- // able to tell "this run had no project" from "this row predates the field",- // and only the latter may fall back to the schedule's current value.- chatProjectId: chatProjectId ?? null,- ...(typeof schedule.configRevision === 'number'- ? { configRevision: schedule.configRevision }- : {}),- });- return 'conflict' in attempt && attempt.conflict === 'slot-taken'- ? 'slot-taken'- : { claimed: attempt };+ const reserveRun = (+ capacitySlot?: number,+ admissionFailure?: {+ error: string;+ mcp?: Awaited<ReturnType<ScheduleEngineDeps['preflightMCP']>>;},- );- if (allocation === 'capacity') {- // Automatic claims keep the claim's lease as a backoff so the nextRunAt-sorted- // claimer doesn't immediately re-pick this row and starve others; nextRunAt is- // untouched, so the occurrence retries once the lease expires. A manual run-now- // MUST release its lease, or repeated Run-now clicks hit a misleading "already- // in progress" 409 for the full manual-lease TTL even after capacity frees.- if (options?.manual) {- await releaseManualLease();+ ) =>+ methods.reserveStartedRun({+ ...baseRun,+ conversationId,+ firedAt: new Date(),+ ...(capacitySlot != null ? { capacitySlot } : {}),+ ...(admissionFailure+ ? {+ admissionOnly: true,+ error: admissionFailure.error,+ ...(admissionFailure.mcp ? { mcp: admissionFailure.mcp } : {}),+ }+ : {}),+ deliveryKey,+ // The destination THIS occurrence used. The schedule-level value can move on+ // (a pin redirects later fires, and a paused run does not block them), so a+ // resume must re-validate what its own conversation was filed under.+ // ALWAYS written, `null` when deliberately unscoped: a later reader has to be+ // able to tell "this run had no project" from "this row predates the field",+ // and only the latter may fall back to the schedule's current value.+ chatProjectId: chatProjectId ?? null,+ ...(typeof schedule.configRevision === 'number'+ ? { configRevision: schedule.configRevision }+ : {}),+ });++ let reservation: Awaited<ReturnType<typeof methods.reserveStartedRun>>;+ if (mcpFailure != null) {+ // A terminal admission failure needs durable evidence and schedule bookkeeping,+ // but it never starts a generation. Reserve the occurrence idempotently without+ // a generation slot, then settle it immediately below.+ reservation = await reserveRun(undefined, {+ error: mcpFailure.message.slice(0, 2048),+ ...(mcpFailure.error ? { mcp: mcpFailure.error.outcomes } : {}),+ });+ } else {+ // The GLOBAL fireConcurrency cap is enforced by claiming a unique capacity slot+ // in the SAME insert that reserves a generation, so it is decided by the DB rather+ // than by a count read before the write. The allocator advances to the next free+ // slot when another ready admission wins one, and reports 'capacity' only when+ // genuinely saturated. Occupancy is read system-scoped so the cap stays global+ // across tenants.+ // CLAMPED to the deployment-wide cap. The slots are global across every owner, so a+ // role/user/tenant override must never be able to WIDEN them: manual Run Now resolves+ // the owner's limits and bypasses the engine tick's base-config budget entirely, so+ // an override of 5 against a base of 1 would otherwise let concurrent clicks occupy+ // slots 0-4 and run five billed generations at once. Re-read without a principal for+ // the base value (the same read the tick budgets from); a STRICTER owner value still+ // applies, since only widening is the defect.+ const allocation = await deps.withGlobalCapacitySlot(+ Math.min(ownerLimits.fireConcurrency, deploymentLimits.fireConcurrency),+ async (capacitySlot) => {+ const attempt = await reserveRun(capacitySlot);+ return 'conflict' in attempt && attempt.conflict === 'slot-taken'+ ? 'slot-taken'+ : { claimed: attempt };+ },+ );+ if (allocation === 'capacity') {+ // Automatic claims keep the claim's lease as a backoff so the nextRunAt-sorted+ // claimer doesn't immediately re-pick this row and starve others; nextRunAt is+ // untouched, so the occurrence retries once the lease expires. A manual run-now+ // MUST release its lease, or repeated Run-now clicks hit a misleading "already+ // in progress" 409 for the full manual-lease TTL even after capacity frees.+ if (options?.manual) {+ await releaseManualLease();+ } else {+ const released = await methods.releaseLease(schedule.id, claimToken);+ if (!released) {+ await releaseSupersededLease();+ }+ }+ return { fired: false, skipped: 'capacity' as const };}- return { fired: false, skipped: 'capacity' as const };+ reservation = allocation.claimed;}- const reservation = allocation.claimed;if ('conflict' in reservation) {if (reservation.conflict === 'overlap') {// Another occurrence of this schedule is already active. Record the skip@@ -569,6 +646,31 @@ export async function fireSchedule(return { fired: false, skipped: 'duplicate' as const };}+ if (mcpFailure != null) {+ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor,+ status: 'error',+ error: mcpFailure.message,+ ...(mcpFailure.error ? { mcp: mcpFailure.error.outcomes } : {}),+ autoDisableAfterFailures: ownerLimits.autoDisableAfterFailures,+ clearConversationId: true,+ });+ await advance();+ return {+ fired: false,+ error: mcpFailure.message,+ ...(mcpFailure.error+ ? { mcp: mcpFailure.error.outcomes }+ : { mcpPreflightUnavailable: true }),+ };+ }++ if (options?.signal?.aborted) {+ await rollbackReservation(conversationId);+ return stepAsideSuperseded();+ }+// Last check before the point of no return: re-verify this fire still holds an// authoritative claim (same claim token, lease unexpired, not deleting; and for// an automatic fire, still enabled). An owner delete/edit or a lease-expiry@@ -585,6 +687,11 @@ export async function fireSchedule(return stepAsideSuperseded();}+ if (options?.signal?.aborted) {+ await rollbackReservation(conversationId);+ return stepAsideSuperseded();+ }+// SHUTDOWN recheck immediately before dispatch: the gate before the reservation// is not the last dispatch-boundary operation — the deployment-limit read,// capacity allocation, and claim revalidation all run after it and can overlap@@ -638,6 +745,7 @@ export async function fireSchedule(await advance();await methods.setRunFireDetails(schedule.id, scheduledFor, {conversationId,+ ...(mcp.length > 0 ? { mcp } : {}),...(droppedFileIds.length > 0 ? { droppedFileIds } : {}),});if (droppedFileIds.length > 0) {diff --git a/packages/api/src/schedules/gate.spec.ts b/packages/api/src/schedules/gate.spec.tsindex efcec3e461..b56c997d6e 100644--- a/packages/api/src/schedules/gate.spec.ts+++ b/packages/api/src/schedules/gate.spec.ts@@ -31,6 +31,7 @@ function makeService(base: Cfg, merged: Cfg = base) {findBalance: jest.fn(async () => null),upsertBalance: jest.fn(async () => null),initializeNullBalance: jest.fn(async () => null),+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(async () => 'ok' as const),getChatProject: jest.fn(async () => ({ _id: 'proj-1' })),isUserDeleting: jest.fn(async () => false),@@ -46,7 +47,10 @@ const limits = {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,};@@ -121,10 +125,16 @@ describe('v1 experimental gate, asserted at real entry points', () => {expect((await makeService({ interfaceConfig: { schedules: true } }).getLimits()).enabled).toBe(true,);- const tuned = makeService({ interfaceConfig: { schedules: { maxPerUser: 3 } } });+ const tuned = makeService({+ interfaceConfig: {+ schedules: { maxPerUser: 3, admissionConcurrency: 12, mcpPreflightConcurrency: 2 },+ },+ });const resolved = await tuned.getLimits();expect(resolved.enabled).toBe(true);expect(resolved.maxPerUser).toBe(3);+ expect(resolved.admissionConcurrency).toBe(12);+ expect(resolved.mcpPreflightConcurrency).toBe(2);});it('REFUSES a manual run-now while the global kill switch is on', async () => {@@ -157,6 +167,7 @@ describe('v1 experimental gate, asserted at real entry points', () => {findBalance: jest.fn(),upsertBalance: jest.fn(),initializeNullBalance: jest.fn(),+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(),getChatProject: jest.fn(),} as unknown as SchedulesServiceDeps),diff --git a/packages/api/src/schedules/handlers.spec.ts b/packages/api/src/schedules/handlers.spec.tsindex f707986b3a..7afc4dcdf1 100644--- a/packages/api/src/schedules/handlers.spec.ts+++ b/packages/api/src/schedules/handlers.spec.ts@@ -4,9 +4,10 @@ import type { Response } from 'express';import type { SchedulesHandlersDeps } from './handlers';import type { ServerRequest } from '~/types';import { createSchedulesHandlers, toWireSchedule, computeCreateDigest } from './handlers';+import { ScheduleMCPError } from './mcp';/** A lean schedule doc carrying both public fields and internal bookkeeping. */-function fullScheduleDoc(): ISchedule {+function fullScheduleDoc(overrides: Partial<ISchedule> = {}): ISchedule {return {_id: 'mongo-id',__v: 0,@@ -37,6 +38,7 @@ function fullScheduleDoc(): ISchedule {bookkept: true,createdAt: new Date('2026-07-01T00:00:00Z'),updatedAt: new Date('2026-07-10T00:00:00Z'),+ ...overrides,} as unknown as ISchedule;}@@ -105,6 +107,7 @@ function makeRes() {const captured: { status?: number; body?: unknown; headers: Record<string, string> } = {headers: {},};+ const listeners = new Map<string, () => void>();const res = {status(code: number) {captured.status = code;@@ -118,6 +121,19 @@ function makeRes() {captured.headers[name] = value;return this;},+ once(event: string, listener: () => void) {+ listeners.set(event, listener);+ return this;+ },+ off(event: string, listener: () => void) {+ if (listeners.get(event) === listener) listeners.delete(event);+ return this;+ },+ emit(event: string) {+ const listener = listeners.get(event);+ listeners.delete(event);+ listener?.();+ },};return { res: res as unknown as Response, captured };}@@ -164,9 +180,13 @@ function makeCreateDeps(over: Partial<SchedulesHandlersDeps> = {}): SchedulesHanmaxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),+ preflightMCP: jest.fn().mockResolvedValue([]),canViewAgent: async () => true,filterOwnedFileIds: async (ids: string[]) => ids,markFilesUsed: async () => undefined,@@ -417,6 +437,9 @@ describe('create with a cron cadence', () => {} as unknown as ISchedule;const deps = makeCreateDeps({isUserDeleting: jest.fn(async () => false),+ preflightMCP: jest.fn(async () => {+ throw new Error('MCP became unavailable after the first create');+ }),getLimits: async () => ({enabled: true,maxPerUser: 10,@@ -424,7 +447,10 @@ describe('create with a cron cadence', () => {// clears the floor it was admitted under.minIntervalMinutes: 100_000,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -434,6 +460,7 @@ describe('create with a cron cadence', () => {await createSchedulesHandlers(deps).createSchedule(makeCreateReq(), res);expect(captured.status).not.toBe(400);+ expect(deps.preflightMCP).not.toHaveBeenCalled();expect(deps.methods.createScheduleWithSlot).not.toHaveBeenCalled();});@@ -445,7 +472,10 @@ describe('create with a cron cadence', () => {maxPerUser: 10,minIntervalMinutes: 100_000,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -470,7 +500,10 @@ describe('create with a cron cadence', () => {maxPerUser: 10,minIntervalMinutes: 100_000,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -1022,7 +1055,10 @@ describe('updateSchedule cadence timezone resolution', () => {maxPerUser: 10,minIntervalMinutes: 700,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -1046,7 +1082,10 @@ describe('updateSchedule cadence timezone resolution', () => {maxPerUser: 10,minIntervalMinutes: 700,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -1078,7 +1117,10 @@ describe('updateSchedule cadence timezone resolution', () => {maxPerUser: 10,minIntervalMinutes: 700,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),});@@ -1147,6 +1189,32 @@ describe('updateSchedule re-enable attachment revalidation', () => {expect(deps.methods.updateScheduleById).toHaveBeenCalled();});+ it('preserves run history when re-enable preflight succeeds', async () => {+ const deps = makeCreateDeps({ isUserDeleting: async () => false });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue({+ ...disabledWithFiles(),+ file_ids: [],+ lastRun: {+ status: 'error',+ firedAt: new Date(),+ error: 'mcp_reauth_required: [{"server":"Notion","status":"mcp_reauth_required"}]',+ },+ } as ISchedule);+ const { res } = makeRes();++ await createSchedulesHandlers(deps).updateSchedule(makeReEnableReq(), res);++ expect(deps.methods.updateScheduleById).toHaveBeenCalledWith(+ 'sched-1',+ 'user-1',+ expect.objectContaining({ enabled: true }),+ expect.objectContaining({ disabledReason: 1 }),+ expect.any(Object),+ );+ const [, , , unset] = jest.mocked(deps.methods.updateScheduleById).mock.calls[0];+ expect(unset).not.toHaveProperty('lastRun');+ });+it('skips the stored-attachment recheck when the edit replaces file_ids', async () => {const filterOwnedFileIds = jest.fn(async (ids: string[]) => ids);const deps = makeCreateDeps({@@ -1185,3 +1253,228 @@ describe('late-create compensation with a live manual run', () => {expect(captured.status).toBe(410);});});++describe('unattended MCP admission', () => {+ it('does not treat a consumed request stream as a client disconnect', async () => {+ const deps = makeCreateDeps({ isUserDeleting: async () => false });+ const req = Object.assign(makeCreateReq(), { destroyed: true });+ (req as unknown as { body: Record<string, unknown> }).body = {+ ...(req.body as unknown as Record<string, unknown>),+ enabled: false,+ };+ const { res, captured } = makeRes();++ await createSchedulesHandlers(deps).createSchedule(req, res);++ expect(captured.status).toBe(201);+ expect(deps.preflightMCP).not.toHaveBeenCalled();+ expect(deps.methods.createScheduleWithSlot).toHaveBeenCalledTimes(1);+ });++ it.each([+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied',+ 'mcp_unavailable',+ ] as const)('refuses create before persisting when preflight reports %s', async (status) => {+ const deps = makeCreateDeps({+ preflightMCP: async () => {+ throw new ScheduleMCPError([{ server: 'Notion', status }]);+ },+ });+ const { res, captured } = makeRes();+ await createSchedulesHandlers(deps).createSchedule(makeCreateReq(), res);+ expect(captured.status).toBe(status === 'mcp_unavailable' ? 503 : 400);+ expect(captured.body).toMatchObject({ code: status, mcp: [{ server: 'Notion', status }] });+ expect(deps.methods.createScheduleWithSlot).not.toHaveBeenCalled();+ });++ it('cancels MCP preflight and does not persist after the request closes', async () => {+ let markStarted: () => void = () => undefined;+ const started = new Promise<void>((resolve) => {+ markStarted = resolve;+ });+ const deps = makeCreateDeps({+ preflightMCP: async (_agentId, _user, options) =>+ new Promise((_resolve, reject) => {+ markStarted();+ options?.signal?.addEventListener('abort', () => reject(options.signal?.reason), {+ once: true,+ });+ }),+ });+ const { res, captured } = makeRes();+ const pending = createSchedulesHandlers(deps).createSchedule(makeCreateReq(), res);+ await started;++ (res as unknown as { emit: (event: string) => void }).emit('close');+ await pending;++ expect(captured.body).toBeUndefined();+ expect(deps.methods.createScheduleWithSlot).not.toHaveBeenCalled();+ });++ it('observes a disconnect that occurs during the first awaited admission read', async () => {+ let release: () => void = () => undefined;+ const blocked = new Promise<void>((resolve) => {+ release = resolve;+ });+ const preflightMCP = jest.fn(async () => []);+ const deps = makeCreateDeps({+ isUserDeleting: async () => {+ await blocked;+ return false;+ },+ preflightMCP,+ });+ const { res, captured } = makeRes();+ const pending = createSchedulesHandlers(deps).createSchedule(makeCreateReq(), res);++ (res as unknown as { emit: (event: string) => void }).emit('close');+ release();+ await pending;++ expect(captured.body).toBeUndefined();+ expect(deps.methods.createScheduleWithSlot).not.toHaveBeenCalled();+ });+});++describe('Run Now MCP failures', () => {+ it.each([+ ['mcp_unavailable', 503],+ ['mcp_reauth_required', 400],+ ['mcp_configuration_missing', 400],+ ['mcp_permission_denied', 400],+ ] as const)('returns the correct status for %s', async (mcpStatus, expectedStatus) => {+ const deps = makeCreateDeps({+ isUserDeleting: async () => false,+ fireNow: async () => ({+ fired: false,+ error: 'MCP preflight failed',+ mcp: [+ { server: 'Ready', status: 'ready' },+ { server: 'Blocked', status: mcpStatus },+ ],+ }),+ });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue(fullScheduleDoc());+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ const { res, captured } = makeRes();++ await createSchedulesHandlers(deps).runScheduleNow(req, res);++ expect(captured.status).toBe(expectedStatus);+ expect(captured.body).toMatchObject({ code: mcpStatus });+ });++ it.each([+ [+ [+ { server: 'OAuth', status: 'mcp_reauth_required' as const },+ { server: 'Config', status: 'mcp_configuration_missing' as const },+ ],+ 'mcp_configuration_missing',+ ],+ [+ [+ { server: 'OAuth', status: 'mcp_reauth_required' as const },+ { server: 'Config', status: 'mcp_configuration_missing' as const },+ { server: 'Policy', status: 'mcp_permission_denied' as const },+ ],+ 'mcp_permission_denied',+ ],+ ])('uses shared failure precedence for mixed outcomes: %j', async (mcp, expectedCode) => {+ const deps = makeCreateDeps({+ isUserDeleting: async () => false,+ fireNow: async () => ({ fired: false, error: 'MCP preflight failed', mcp }),+ });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue(fullScheduleDoc());+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ const { res, captured } = makeRes();++ await createSchedulesHandlers(deps).runScheduleNow(req, res);++ expect(captured.status).toBe(400);+ expect(captured.body).toMatchObject({ code: expectedCode });+ });++ it('returns service unavailable when MCP infrastructure preflight fails', async () => {+ const deps = makeCreateDeps({+ isUserDeleting: async () => false,+ fireNow: async () => ({+ fired: false,+ error: 'MCP preflight unavailable',+ mcpPreflightUnavailable: true,+ }),+ });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue(fullScheduleDoc());+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ const { res, captured } = makeRes();++ await createSchedulesHandlers(deps).runScheduleNow(req, res);++ expect(captured.status).toBe(503);+ expect(captured.body).toMatchObject({+ code: 'mcp_unavailable',+ error: 'MCP preflight unavailable',+ });+ });+});++it.each([{ enabled: true }, { prompt: 'Updated prompt' }, { agent_id: 'replacement' }])(+ 'rechecks effective MCP configuration for edits and enable: %j',+ async (body) => {+ const deps = makeCreateDeps({+ isUserDeleting: async () => false,+ preflightMCP: async () => {+ throw new ScheduleMCPError([{ server: 'Notion', status: 'mcp_reauth_required' }]);+ },+ });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue(fullScheduleDoc());+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ Object.assign(req, { body });+ const { res, captured } = makeRes();+ await createSchedulesHandlers(deps).updateSchedule(req, res);+ expect(captured.status).toBe(400);+ expect(deps.methods.updateScheduleById).not.toHaveBeenCalled();+ },+);++it('allows pausing even when MCP preflight would fail', async () => {+ const preflightMCP = jest.fn(async () => {+ throw new Error('unavailable');+ });+ const deps = makeCreateDeps({ isUserDeleting: async () => false, preflightMCP });+ jest.mocked(deps.methods.getScheduleById).mockResolvedValue(fullScheduleDoc());+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ Object.assign(req, { body: { enabled: false } });+ const { res } = makeRes();+ await createSchedulesHandlers(deps).updateSchedule(req, res);+ expect(preflightMCP).not.toHaveBeenCalled();+ expect(deps.methods.updateScheduleById).toHaveBeenCalled();+});++it('allows repointing a disabled schedule without MCP preflight', async () => {+ const preflightMCP = jest.fn(async () => {+ throw new Error('unavailable');+ });+ const deps = makeCreateDeps({ isUserDeleting: async () => false, preflightMCP });+ jest+ .mocked(deps.methods.getScheduleById)+ .mockResolvedValue(fullScheduleDoc({ enabled: false, nextRunAt: undefined }));+ const req = makeCreateReq();+ req.params = { id: 'sched-1' };+ Object.assign(req, { body: { agent_id: 'replacement' } });+ const { res, captured } = makeRes();++ await createSchedulesHandlers(deps).updateSchedule(req, res);++ expect(captured.status ?? 200).toBe(200);+ expect(preflightMCP).not.toHaveBeenCalled();+ expect(deps.methods.updateScheduleById).toHaveBeenCalled();+});diff --git a/packages/api/src/schedules/handlers.ts b/packages/api/src/schedules/handlers.tsindex 4bee2da702..2468ca4ed9 100644--- a/packages/api/src/schedules/handlers.ts+++ b/packages/api/src/schedules/handlers.ts@@ -12,6 +12,7 @@ import type {ScheduleDeleteResult,ScheduleUserContext,FireableSchedule,+ ScheduleMCPPreflight,ScheduleLimits,FireResult,} from './types';@@ -22,9 +23,11 @@ import {computeNextRunAt,isValidTimezone,} from './cadence';+import { ScheduleMCPError, getScheduleMCPFailureCode } from './mcp';import { resolveScheduleProjectId } from './types';export interface SchedulesHandlersDeps {+ preflightMCP: ScheduleMCPPreflight;methods: ScheduleMethods;getLimits: (user?: ScheduleUserContext) => Promise<ScheduleLimits>;/** Agent existence + VIEW access for the requesting user. */@@ -39,7 +42,11 @@ export interface SchedulesHandlersDeps {* hold lapse instead of retaining the upload forever. Throws when any file is gone. */markFilesUsed: (fileIds: string[], userId: string) => Promise<void>;/** Serialized manual fire (acquires the schedule lease); null if already leased. */- fireNow: (schedule: FireableSchedule, limits: ScheduleLimits) => Promise<FireResult | null>;+ fireNow: (+ schedule: FireableSchedule,+ limits: ScheduleLimits,+ options?: { signal?: AbortSignal },+ ) => Promise<FireResult | null>;/*** Soft-deletes a schedule with quiescing: stops new claims, aborts in-flight* runs, and erases once drained. See ScheduleDeleteResult for the honest states.@@ -360,6 +367,49 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHreturn false;}+ function responseAbortSignal(req: ServerRequest, res: Response): AbortSignal {+ const controller = new AbortController();+ const abort = () => controller.abort(new Error('Schedule request closed'));+ const detach = () => {+ req.off?.('aborted', abort);+ res.off?.('close', abort);+ };+ req.once?.('aborted', abort);+ res.once?.('close', abort);+ res.once?.('finish', detach);+ if (req.aborted === true || res.destroyed === true) abort();+ return controller.signal;+ }++ async function validateMCP(+ agentId: string,+ req: ServerRequest,+ res: Response,+ signal: AbortSignal,+ limits: ScheduleLimits,+ ): Promise<boolean> {+ try {+ await deps.preflightMCP(agentId, requestUser(req), {+ signal,+ concurrency: limits.mcpPreflightConcurrency,+ deadlineMs: Date.now() + limits.mcpPreflightTimeoutMs,+ });+ return true;+ } catch (error) {+ if (signal.aborted) return false;+ if (error instanceof ScheduleMCPError) {+ res.status(error.code === 'mcp_unavailable' ? 503 : 400).json({+ code: error.code,+ error: error.message,+ mcp: error.outcomes,+ });+ } else {+ res.status(503).json({ code: 'mcp_unavailable', error: 'MCP preflight unavailable' });+ }+ return false;+ }+ }+async function validatePayload(req: ServerRequest,res: Response,@@ -565,6 +615,8 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesH}async function createSchedule(req: ServerRequest, res: Response): Promise<void> {+ const mcpSignal = responseAbortSignal(req, res);+ if (mcpSignal.aborted) return;const parsed = createSchedulePayloadSchema.safeParse(req.body);if (!parsed.success) {res.status(400).json({ error: 'Invalid schedule payload', issues: parsed.error.issues });@@ -648,10 +700,16 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHuser.id,parsed.data.clientRequestId,);+ if (mcpSignal.aborted) return;if (replayed != null) {await respondToReplay(replayed);return;}+ if (+ parsed.data.enabled &&+ !(await validateMCP(parsed.data.agent_id, req, res, mcpSignal, limits))+ )+ return;// Project policy applies to a NEW insert only, and is therefore resolved AFTER every// replay lookup above. A committed create whose response was lost must still be// recoverable by an identical retry: applying today's policy first let a raised@@ -711,6 +769,7 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHres.status(500).json({ error: 'Failed to retain schedule attachments' });return;}+ if (mcpSignal.aborted) return;// Atomic cap: createScheduleWithSlot claims a free per-user slot via the// {user, slot} partial unique index, so concurrent creates can never exceed// maxPerUser. 'limit' means a concurrent racer took the last slot after the@@ -832,6 +891,8 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesH}async function updateSchedule(req: ServerRequest, res: Response): Promise<void> {+ const mcpSignal = responseAbortSignal(req, res);+ if (mcpSignal.aborted) return;const parsed = updateSchedulePayloadSchema.safeParse(req.body);if (!parsed.success) {res.status(400).json({ error: 'Invalid schedule payload', issues: parsed.error.issues });@@ -856,6 +917,7 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHreturn;}const existing = await deps.methods.getScheduleById(id, user.id);+ if (mcpSignal.aborted) return;if (existing == null) {res.status(404).json({ error: 'Schedule not found' });return;@@ -908,6 +970,11 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHres.status(400).json({ error: 'Agent not found or not accessible' });return;}+ if (+ enabled &&+ !(await validateMCP(parsed.data.agent_id ?? existing.agent_id, req, res, mcpSignal, limits))+ )+ return;// The destination is re-resolved on every edit that leaves the schedule ENABLED,// against the stored id when this PATCH does not touch the field — the same shape// as the stored-agent and effective-cadence rechecks above, and for the same@@ -1018,6 +1085,7 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHreturn;}}+ if (mcpSignal.aborted) return;// FENCED on the revision this edit was computed from. `nextRunAt` above is derived// from (cadence, timezone) resolved against the row read at the top of this handler,// so two overlapping edits — one changing cadence, one changing timezone — would@@ -1071,6 +1139,8 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesH}async function runScheduleNow(req: ServerRequest, res: Response): Promise<void> {+ const signal = responseAbortSignal(req, res);+ if (signal.aborted) return;const { id } = req.params as { id: string };if (await rejectIfUserDeleting(deps, requestUser(req).id, res)) {return;@@ -1081,7 +1151,9 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHreturn;}const limits = await deps.getLimits(requestUser(req));- const result = await deps.fireNow(schedule, limits);+ if (signal.aborted) return;+ const result = await deps.fireNow(schedule, limits, { signal });+ if (signal.aborted) return;if (result == null) {res.status(409).json({ error: 'A run for this schedule is already in progress' });return;@@ -1089,12 +1161,24 @@ export function createSchedulesHandlers(deps: SchedulesHandlersDeps): SchedulesHif (!result.fired) {// A limiter refusal is the caller's own quota, not a conflicting schedule state,// so answer 429 rather than burying it in the generic 409.- res.status(result.skipped === 'rate_limited' ? 429 : 409).json({- error:- result.skipped === 'rate_limited'- ? 'Too many messages. Try running this schedule again shortly.'- : (result.error ?? `Run skipped (${result.skipped ?? 'unknown'})`),+ const failedMCP = result.mcp?.filter((outcome) => outcome.status !== 'ready') ?? [];+ const mcpStatus = failedMCP.length > 0 ? getScheduleMCPFailureCode(failedMCP) : undefined;+ let status = 409;+ if (result.skipped === 'rate_limited') status = 429;+ else if (mcpStatus === 'mcp_unavailable' || result.mcpPreflightUnavailable === true)+ status = 503;+ else if (mcpStatus != null) status = 400;+ const error =+ result.skipped === 'rate_limited'+ ? 'Too many messages. Try running this schedule again shortly.'+ : (result.error ?? `Run skipped (${result.skipped ?? 'unknown'})`);+ const responseCode =+ mcpStatus ?? (result.mcpPreflightUnavailable === true ? 'mcp_unavailable' : undefined);+ res.status(status).json({+ error,skipped: result.skipped,+ mcp: result.mcp,+ ...(responseCode != null ? { code: responseCode } : {}),});return;}diff --git a/packages/api/src/schedules/index.ts b/packages/api/src/schedules/index.tsindex bc2755a66a..bd702113d7 100644--- a/packages/api/src/schedules/index.ts+++ b/packages/api/src/schedules/index.ts@@ -7,3 +7,4 @@ export * from './handlers';export * from './readiness';export * from './trigger';export * from './types';+export * from './mcp';diff --git a/packages/api/src/schedules/mcp.spec.ts b/packages/api/src/schedules/mcp.spec.tsnew file mode 100644index 0000000000..803450d906--- /dev/null+++ b/packages/api/src/schedules/mcp.spec.ts@@ -0,0 +1,1385 @@+import { AgentCapabilities, Permissions, PermissionTypes } from 'librechat-data-provider';+import type { IUser, IRole, AppConfig, AgentGraphNode } from '@librechat/data-schemas';+import type { ParsedServerConfig } from '../mcp/types';+import { createScheduleMCPPreflight, ScheduleMCPError } from './mcp';++const principal = { id: 'owner', role: 'USER' };+const server: ParsedServerConfig = { type: 'streamable-http', url: 'https://mcp.example.test/mcp' };++function graphNode(id: string, fields: Partial<AgentGraphNode> = {}): AgentGraphNode {+ return { id, provider: 'openAI', model: 'gpt-test', ...fields };+}++function setup(tools = ['search_mcp_docs']) {+ const disconnect = jest.fn();+ const deps: Parameters<typeof createScheduleMCPPreflight>[0] = {+ resolveAgentGraphAccess: jest.fn(async () => ({}) as never),+ getAgentGraphNodes: jest.fn(async (ids) =>+ ids.map((id) => ({ id, provider: 'openAI', model: 'gpt-test', tools })),+ ),+ getModelsConfig: jest.fn(async () => ({ openAI: ['gpt-test'] })),+ getRoleByName: jest.fn(+ async () =>+ ({ permissions: { [PermissionTypes.MCP_SERVERS]: { [Permissions.USE]: true } } }) as IRole,+ ),+ getUser: jest.fn(+ async () => ({ id: 'owner', role: 'USER', email: '[email protected]' }) as IUser,+ ),+ getAppConfig: jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ }) as AppConfig,+ ),+ ensureConfigServers: jest.fn(async () => ({})),+ getServerConfigs: jest.fn(async () => ({ docs: server })),+ findPluginAuthsByKeys: jest.fn(async () => []),+ connect: jest.fn(async (options) => {+ options.requestScopedConnections?.connections.set(options.serverName, { disconnect });+ return {+ fetchToolsSnapshot: async () => ({+ tools: [{ name: 'search', inputSchema: { type: 'object' as const } }],+ complete: true,+ }),+ };+ }),+ };+ const preflight = createScheduleMCPPreflight(deps);+ return {+ deps,+ disconnect,+ check: (+ agentId: string,+ user: typeof principal,+ options?: { concurrency?: number; signal?: AbortSignal; deadlineMs?: number },+ ) => preflight(agentId, user, { concurrency: 3, ...options }),+ };+}++it('leaves agents without MCP tools independent of MCP config and credentials', async () => {+ const { check, deps } = setup(['web_search']);+ await expect(check('agent', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('uses persisted identity with isolated connections and disposes them after discovery', async () => {+ const { check, deps, disconnect } = setup();+ await expect(check('agent', principal)).resolves.toEqual([{ server: 'docs', status: 'ready' }]);+ expect(deps.connect).toHaveBeenCalledWith(+ expect.objectContaining({+ user: { id: 'owner', role: 'USER', email: '[email protected]' },+ ephemeralConnection: true,+ returnOnOAuth: true,+ requestBody: expect.objectContaining({+ parentMessageId: '00000000-0000-0000-0000-000000000000',+ }),+ }),+ );+ expect(disconnect).toHaveBeenCalledTimes(1);+});++it('rejects partial readiness and reports each server without exception details', async () => {+ const { check, deps, disconnect } = setup(['search_mcp_docs', 'read_mcp_private']);+ deps.getServerConfigs = async () => ({ docs: server, private: server });+ const connect = deps.connect;+ deps.connect = async (options) => {+ if (options.serverName === 'private') {+ await options.oauthStart?.('https://example.test/secret-oauth-code');+ throw new Error('secret credential');+ }+ return connect(options);+ };+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_reauth_required',+ outcomes: [+ { server: 'docs', status: 'ready' },+ { server: 'private', status: 'mcp_reauth_required' },+ ],+ });+ expect(disconnect).toHaveBeenCalledTimes(1);+});++it('rejects missing durable user variables before connecting', async () => {+ const { check, deps } = setup();+ deps.getServerConfigs = async () => ({+ docs: { ...server, customUserVars: { API_KEY: { title: 'API key', description: 'Key' } } },+ });+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ });+ expect(deps.connect).not.toHaveBeenCalled();+});++it('does not classify a credential-store outage as missing configuration', async () => {+ const { check, deps } = setup();+ deps.findPluginAuthsByKeys = async () => {+ throw new Error('database unavailable');+ };+ await expect(check('agent', principal)).rejects.not.toBeInstanceOf(ScheduleMCPError);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('classifies a transport outage as retryable', async () => {+ const { check, deps } = setup();+ deps.connect = async () => {+ throw new Error('connection refused with secret details');+ };+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_unavailable',+ message: 'mcp_unavailable: [{"server":"docs","status":"mcp_unavailable"}]',+ });+});++it('checks graph agents once even when edges cycle', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, { tools: [], edges: [{ from: 'root', to: 'child' }] })+ : graphNode(id, { tools: ['search_mcp_docs'], agent_ids: ['root'] }),+ ),+ );+ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'child' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledTimes(2);+});++it('loads each graph frontier in one batch', async () => {+ const childIds = Array.from({ length: 20 }, (_, index) => `child-${index}`);+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ graphNode(id, {+ tools: id === childIds[0] ? ['search_mcp_docs'] : [],+ edges:+ id === 'root' ? childIds.map((childId) => ({ from: 'root', to: childId })) : undefined,+ }),+ ),+ );+ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'child-0' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenNthCalledWith(1, ['root']);+ expect(deps.getAgentGraphNodes).toHaveBeenNthCalledWith(2, childIds, expect.any(Object));+ expect(deps.resolveAgentGraphAccess).toHaveBeenCalledWith(+ expect.objectContaining({ userId: 'owner', role: 'USER' }),+ );+ expect(deps.getAgentGraphNodes).toHaveBeenCalledTimes(2);+});++it('does not count the root or legacy handoff nodes against the spawn graph budget', async () => {+ const spawnIds = Array.from({ length: 49 }, (_, index) => `spawn-${index}`);+ const legacyIds = Array.from({ length: 55 }, (_, index) => `handoff-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ tools: [],+ agent_ids: legacyIds,+ subagents: { enabled: true, agent_ids: spawnIds } as never,+ })+ : graphNode(id, {+ tools: id === spawnIds[0] ? ['search_mcp_docs'] : [],+ }),+ ),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'spawn-0' },+ ]);+});++it('rejects direct trees beyond the runtime expanded-config limit', async () => {+ const spawnIds = Array.from({ length: 50 }, (_, index) => `spawn-${index}`);+ const { check, deps } = setup([]);+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ subagents: { enabled: true, agent_ids: spawnIds } as never,+ })+ : graphNode(id, { subagents: { enabled: true } as never }),+ ),+ );++ await expect(check('root', principal)).rejects.toThrow('maximum of 100 expanded entries');+});++it('counts accepted graph descriptors against the runtime run-config limit', async () => {+ const { check, deps } = setup([]);+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ subagents: {+ enabled: true,+ graphs: Array.from({ length: 100 }, (_, index) => ({+ name: `graph-${index}`,+ agent_ids: ['member'],+ })),+ } as never,+ })+ : graphNode(id),+ ),+ );++ await expect(check('root', principal)).rejects.toThrow('maximum of 100 expanded entries');+});++it('tracks accepted lazy graphs per descriptor path', async () => {+ const { check, deps } = setup([]);+ const graphs = Array.from({ length: 50 }, (_, index) => ({+ name: `graph-${index}`,+ agent_ids: ['member'],+ }));+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ subagents: { enabled: true, agent_ids: ['a', 'b'] } as never,+ });+ }+ if (id === 'a' || id === 'b') {+ return graphNode(id, {+ subagents: { enabled: true, agent_ids: ['shared'] } as never,+ });+ }+ if (id === 'shared') {+ return graphNode(id, { subagents: { enabled: true, graphs } as never });+ }+ return graphNode(id);+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+});++it('keeps lazy descriptor ancestors when validating cyclic run-config limits', async () => {+ const { check, deps } = setup([]);+ const graphs = Array.from({ length: 49 }, (_, index) => ({+ name: `graph-${index}`,+ agent_ids: ['member'],+ }));+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ subagents: { enabled: true, agent_ids: ['child'], graphs } as never,+ });+ }+ if (id === 'child') {+ return graphNode(id, {+ subagents: { enabled: true, agent_ids: ['root'], graphs } as never,+ });+ }+ return graphNode(id);+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+});++it('skips only a subagent graph definition that exceeds the runtime member budget', async () => {+ const acceptedIds = Array.from({ length: 50 }, (_, index) => `accepted-${index}`);+ const { check, deps } = setup([]);+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ subagents: {+ enabled: true,+ graphs: [{ agent_ids: acceptedIds }, { agent_ids: ['overflow'] }],+ } as never,+ });+ }+ return graphNode(id, { tools: id === acceptedIds[0] ? ['search_mcp_docs'] : [] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'accepted-0' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledTimes(2);+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(+ expect.arrayContaining(['overflow']),+ expect.anything(),+ );+});++it('charges direct subagents before admitting graph definitions', async () => {+ const graphIds = Array.from({ length: 50 }, (_, index) => `graph-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ tools: [],+ subagents: {+ enabled: true,+ agent_ids: ['direct'],+ graphs: [{ agent_ids: graphIds }, { agent_ids: ['accepted'] }],+ } as never,+ })+ : graphNode(id, { tools: ['search_mcp_docs'] }),+ ),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'direct' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledWith(['direct'], expect.any(Object));+ expect(deps.getAgentGraphNodes).toHaveBeenCalledWith(['accepted'], expect.any(Object));+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(+ expect.arrayContaining([graphIds[0]]),+ expect.anything(),+ );+});++it('counts the complete nested direct tree before root graph admission', async () => {+ const graphIds = Array.from({ length: 49 }, (_, index) => `graph-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ subagents: {+ enabled: true,+ agent_ids: ['direct-a'],+ graphs: [{ agent_ids: graphIds }],+ } as never,+ });+ }+ if (id === 'direct-a') {+ return graphNode(id, {+ subagents: { enabled: true, agent_ids: ['direct-b'] } as never,+ });+ }+ return graphNode(id, { tools: id === 'direct-b' ? ['search_mcp_docs'] : [] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'direct-b' },+ ]);+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(+ expect.arrayContaining([graphIds[0]]),+ expect.anything(),+ );+});++it('does not charge inaccessible direct targets to the graph budget', async () => {+ const graphIds = Array.from({ length: 50 }, (_, index) => `graph-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.flatMap((id) => {+ if (id === 'root') {+ return [+ graphNode(id, {+ tools: [],+ subagents: {+ enabled: true,+ agent_ids: ['private'],+ graphs: [{ agent_ids: graphIds }],+ } as never,+ }),+ ];+ }+ if (id === 'private') return [];+ return [graphNode(id, { tools: id === graphIds[0] ? ['search_mcp_docs'] : [] })];+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'graph-0' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledWith(graphIds, expect.any(Object));+});++it('charges viewable invalid-model direct targets to the runtime graph budget', async () => {+ const graphIds = Array.from({ length: 50 }, (_, index) => `graph-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ tools: [],+ subagents: {+ enabled: true,+ agent_ids: ['retired'],+ graphs: [{ agent_ids: graphIds }],+ } as never,+ });+ }+ if (id === 'retired') {+ return graphNode(id, {+ provider: 'anthropic',+ model: 'retired-model',+ tools: ['search_mcp_docs'],+ });+ }+ return graphNode(id, { tools: id === graphIds[0] ? ['search_mcp_docs'] : [] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(graphIds, expect.anything());+ expect(deps.connect).not.toHaveBeenCalled();+});++it('does not retry a model-invalid handoff as a direct subagent descriptor', async () => {+ const graphIds = Array.from({ length: 50 }, (_, index) => `graph-${index}`);+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ tools: [],+ edges: [{ from: 'root', to: 'retired' }],+ subagents: {+ enabled: true,+ agent_ids: ['retired'],+ graphs: [{ agent_ids: graphIds }],+ } as never,+ });+ }+ if (id === 'retired') {+ return graphNode(id, { provider: 'anthropic', model: 'retired-model' });+ }+ return graphNode(id, { tools: id === graphIds[0] ? ['search_mcp_docs'] : [] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'graph-0' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledWith(graphIds, expect.any(Object));+});++it('rejects direct subagent trees beyond the runtime depth limit', async () => {+ const { check, deps } = setup([]);+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ const depth = id === 'root' ? 0 : Number(id.slice('depth-'.length));+ return graphNode(id, {+ subagents: {+ enabled: true,+ agent_ids: [depth === 5 ? 'depth-6' : `depth-${depth + 1}`],+ } as never,+ });+ }),+ );++ await expect(check('root', principal)).rejects.toThrow('maximum depth of 5');+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(['depth-6'], expect.anything());+});++it('does not expand persisted handoffs from graph-only members', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, {+ tools: [],+ subagents: { enabled: true, graphs: [{ agent_ids: ['member'] }] } as never,+ });+ }+ if (id === 'member') {+ return graphNode(id, {+ tools: ['search_mcp_docs'],+ edges: [{ from: 'member', to: 'downstream' }],+ });+ }+ return graphNode(id, { tools: ['read_mcp_private'] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'member' },+ ]);+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(+ expect.arrayContaining(['downstream']),+ expect.anything(),+ );+});++it('skips MCP tools on graph agents the owner cannot view', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids, access) =>+ ids.flatMap((id) => {+ if (id === 'root') {+ return [graphNode(id, { tools: [], edges: [{ from: 'root', to: 'private' }] })];+ }+ return access == null ? [graphNode(id, { tools: ['search_mcp_docs'] })] : [];+ }),+ );+ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('reuses one resolved access context across deep graph frontiers', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, { tools: [], edges: [{ from: 'root', to: 'middle' }] });+ }+ if (id === 'middle') {+ return graphNode(id, { tools: [], edges: [{ from: 'middle', to: 'leaf' }] });+ }+ return graphNode(id, { tools: ['search_mcp_docs'] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'leaf' },+ ]);+ expect(deps.getAgentGraphNodes).toHaveBeenCalledTimes(3);+ expect(deps.resolveAgentGraphAccess).toHaveBeenCalledTimes(1);+});++it('ignores accessible descendants whose provider model is unavailable at runtime', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, { tools: [], edges: [{ from: 'root', to: 'retired' }] })+ : graphNode(id, {+ provider: 'anthropic',+ model: 'retired-model',+ tools: ['search_mcp_docs'],+ }),+ ),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('prunes viewable descendants stranded behind an inaccessible edge node', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids, access) =>+ ids.flatMap((id) => {+ if (id === 'root') {+ return [+ graphNode(id, {+ tools: [],+ edges: [+ { from: 'root', to: 'private' },+ { from: 'private', to: 'visible' },+ ],+ }),+ ];+ }+ if (id === 'visible' && access != null) {+ return [graphNode(id, { tools: ['search_mcp_docs'] })];+ }+ return [];+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('prunes later legacy chain members when an earlier member is unavailable', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.flatMap((id) => {+ if (id === 'root') {+ return [graphNode(id, { tools: [], agent_ids: ['missing', 'visible'] })];+ }+ if (id === 'visible') {+ return [graphNode(id, { tools: ['search_mcp_docs'] })];+ }+ return [];+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('does not expand persisted handoffs from legacy-chain-only agents', async () => {+ const { check, deps } = setup();+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) => {+ if (id === 'root') {+ return graphNode(id, { tools: [], agent_ids: ['legacy'] });+ }+ if (id === 'legacy') {+ return graphNode(id, {+ tools: ['search_mcp_docs'],+ edges: [{ from: 'legacy', to: 'downstream' }],+ });+ }+ return graphNode(id, { tools: ['read_mcp_private'] });+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'legacy' },+ ]);+ expect(deps.getAgentGraphNodes).not.toHaveBeenCalledWith(+ expect.arrayContaining(['downstream']),+ expect.anything(),+ );+});++it('includes enabled spawn-graph members when the capability is available', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ tools: [],+ subagents: {+ enabled: true,+ graphs: [{ name: 'research', type: 'single_agent', agent_ids: ['spawned'] }],+ } as never,+ })+ : graphNode(id, { tools: ['search_mcp_docs'] }),+ ),+ );+ await expect(check('root', principal)).resolves.toEqual([+ { server: 'docs', status: 'ready', agentId: 'spawned' },+ ]);+});++it('skips every member of an incomplete spawn graph', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids, access) =>+ ids.flatMap((id) => {+ if (id === 'root') {+ return [+ graphNode(id, {+ tools: [],+ subagents: {+ enabled: true,+ graphs: [+ {+ name: 'team',+ type: 'team',+ agent_ids: ['visible', 'private'],+ },+ ],+ } as never,+ }),+ ];+ }+ if (id === 'visible' && access != null) {+ return [graphNode(id, { tools: ['search_mcp_docs'] })];+ }+ return [];+ }),+ );++ await expect(check('root', principal)).resolves.toEqual([]);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('ignores a server pin when the agent selected no tools from that server', async () => {+ const { check, deps } = setup(['sys__server__sys_mcp_docs']);+ await expect(check('agent', principal)).resolves.toEqual([]);+ expect(deps.getServerConfigs).not.toHaveBeenCalled();+ expect(deps.connect).not.toHaveBeenCalled();+});++it('propagates principal-config outages instead of reporting missing configuration', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(async (options) => {+ expect(options).toMatchObject({ failClosed: true });+ throw new Error('principal config unavailable');+ });+ await expect(check('agent', principal)).rejects.not.toBeInstanceOf(ScheduleMCPError);+});++it('reuses the loaded external identity for principal configuration', async () => {+ const { check, deps } = setup();+ deps.getUser = jest.fn(+ async () =>+ ({+ id: 'owner',+ role: 'USER',+ email: '[email protected]',+ idOnTheSource: 'external-owner',+ }) as IUser,+ );++ await check('agent', principal);++ expect(deps.getAppConfig).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'owner',+ role: 'USER',+ idOnTheSource: 'external-owner',+ failClosed: true,+ }),+ );+});++it('uses the freshly loaded role for MCP server ACL resolution', async () => {+ const { check, deps } = setup();+ deps.getUser = jest.fn(+ async () => ({ id: 'owner', role: 'ADMIN', email: '[email protected]' }) as IUser,+ );++ await check('agent', principal);++ expect(deps.getServerConfigs).toHaveBeenCalledWith('owner', {}, 'ADMIN');+});++it('initializes only config servers selected by the runnable graph', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: {+ docs: { type: 'streamable-http', url: 'https://docs.example.test/mcp' },+ unrelated: { type: 'streamable-http', url: 'https://other.example.test/mcp' },+ },+ }) as unknown as AppConfig,+ );++ await check('agent', principal);++ expect(deps.ensureConfigServers).toHaveBeenCalledWith(+ {+ docs: { type: 'streamable-http', url: 'https://docs.example.test/mcp' },+ },+ expect.any(Function),+ );+});++it('lets authoritative config names claim normalized aliases before stored hints', async () => {+ const { check, deps } = setup(['search_mcp_Sales_Force']);+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ graphNode(id, { tools: ['search_mcp_Sales_Force'], mcpServerNames: ['Sales_Force'] }),+ ),+ );+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: {+ 'Sales Force': { type: 'streamable-http', url: 'https://sales.example.test/mcp' },+ },+ }) as unknown as AppConfig,+ );+ deps.getServerConfigs = async () => ({ 'Sales Force': server });++ await expect(check('agent', principal)).resolves.toEqual([+ { server: 'Sales Force', status: 'ready' },+ ]);+ expect(deps.ensureConfigServers).toHaveBeenCalledWith(+ {+ 'Sales Force': { type: 'streamable-http', url: 'https://sales.example.test/mcp' },+ },+ expect.any(Function),+ );+});++it('prefers an exact accessible registry name over a colliding config alias', async () => {+ const { check, deps } = setup(['search_mcp_sales-force']);+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ graphNode(id, { tools: ['search_mcp_sales-force'], mcpServerNames: ['sales-force'] }),+ ),+ );+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: {+ 'sales-force!': { type: 'streamable-http', url: 'https://alias.example.test/mcp' },+ },+ }) as unknown as AppConfig,+ );+ deps.getServerConfigs = jest.fn(async () => ({ 'sales-force': server }));++ await expect(check('agent', principal)).resolves.toEqual([+ { server: 'sales-force', status: 'ready' },+ ]);+ expect(deps.ensureConfigServers).toHaveBeenCalledWith({}, expect.any(Function));+});++it('retains a normalized alias for an inaccessible raw server hint', async () => {+ const { check, deps } = setup(['search_mcp_Sales_Force']);+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ graphNode(id, { tools: ['search_mcp_Sales_Force'], mcpServerNames: ['Sales Force'] }),+ ),+ );+ deps.getServerConfigs = jest.fn(async () => ({}));++ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ outcomes: [{ server: 'Sales Force', status: 'mcp_configuration_missing' }],+ });+ expect(deps.connect).not.toHaveBeenCalled();+});++it('rejects a selected server shadowed by an unselected config server', async () => {+ const { check, deps } = setup(['search_mcp_Sales Force']);+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: {+ 'Sales Force': { type: 'streamable-http', url: 'https://first.example.test/mcp' },+ Sales_Force: { type: 'streamable-http', url: 'https://second.example.test/mcp' },+ },+ }) as unknown as AppConfig,+ );+ deps.getServerConfigs = async () => ({ 'Sales Force': server });++ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ });+ expect(deps.ensureConfigServers).toHaveBeenCalledWith(+ {+ 'Sales Force': { type: 'streamable-http', url: 'https://first.example.test/mcp' },+ },+ expect.any(Function),+ );+ expect(deps.connect).not.toHaveBeenCalled();+});++it('rejects an explicitly selected tool removed from an otherwise healthy server', async () => {+ const { check } = setup(['deleted_mcp_docs']);+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ });+});++it('attributes a missing shared-server tool to the agent that selected it', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ tools: ['search_mcp_docs'],+ subagents: { enabled: true, agent_ids: ['child'] } as never,+ })+ : graphNode(id, { tools: ['deleted_mcp_docs'] }),+ ),+ );++ await expect(check('root', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ outcomes: [{ server: 'docs', status: 'mcp_configuration_missing', agentId: 'child' }],+ });+});++it('preserves every owner with a missing tool on a shared server', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: {+ agents: { capabilities: [AgentCapabilities.tools, AgentCapabilities.subagents] },+ },+ }) as unknown as AppConfig,+ );+ deps.getAgentGraphNodes = jest.fn(async (ids) =>+ ids.map((id) =>+ id === 'root'+ ? graphNode(id, {+ tools: ['search_mcp_docs'],+ subagents: { enabled: true, agent_ids: ['researcher', 'writer'] } as never,+ })+ : graphNode(id, {+ tools: [id === 'researcher' ? 'deleted_search_mcp_docs' : 'deleted_write_mcp_docs'],+ }),+ ),+ );++ await expect(check('root', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ outcomes: [+ { server: 'docs', status: 'mcp_configuration_missing', agentId: 'researcher' },+ { server: 'docs', status: 'mcp_configuration_missing', agentId: 'writer' },+ ],+ });+});++it('distinguishes an incomplete catalog from missing tools', async () => {+ const { check, deps } = setup(['deleted_mcp_docs']);+ deps.connect = async () => ({ fetchToolsSnapshot: async () => ({ tools: [], complete: false }) });+ await expect(check('agent', principal)).rejects.toMatchObject({ code: 'mcp_unavailable' });+});++it('treats a complete empty catalog as missing selected configuration', async () => {+ const { check, deps } = setup(['deleted_mcp_docs']);+ deps.connect = async () => ({ fetchToolsSnapshot: async () => ({ tools: [], complete: true }) });+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ });+});++it('preserves authentication failures reported by tools/list snapshots', async () => {+ const { check, deps } = setup();+ deps.connect = async () => ({+ fetchToolsSnapshot: async () => ({+ tools: [],+ complete: false,+ authenticationError: { status: 401 },+ }),+ });+ await expect(check('agent', principal)).rejects.toMatchObject({ code: 'mcp_reauth_required' });+});++it('does not connect when the owner loses MCP permission', async () => {+ const { check, deps } = setup();+ deps.getRoleByName = async () => null;+ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_permission_denied',+ });+ expect(deps.connect).not.toHaveBeenCalled();+});++it('rejects selected MCP tools when the effective tools capability is disabled', async () => {+ const { check, deps } = setup();+ deps.getAppConfig = jest.fn(+ async () => ({ endpoints: { agents: { capabilities: [] } } }) as unknown as AppConfig,+ );++ await expect(check('agent', principal)).rejects.toMatchObject({+ code: 'mcp_configuration_missing',+ });+ expect(deps.connect).not.toHaveBeenCalled();+});++it('keeps a role-store outage retryable instead of disabling the schedule', async () => {+ const { check, deps } = setup();+ deps.getRoleByName = async () => {+ throw new Error('role store unavailable');+ };+ await expect(check('agent', principal)).rejects.not.toBeInstanceOf(ScheduleMCPError);+ expect(deps.connect).not.toHaveBeenCalled();+});++it('starts independent server probes together instead of serializing their timeouts', async () => {+ const { check, deps } = setup(['search_mcp_docs', 'search_mcp_private']);+ deps.getServerConfigs = async () => ({ docs: server, private: server });+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ const connect = deps.connect;+ deps.connect = jest.fn(async (options) => {+ await gate;+ return connect(options);+ });+ const result = check('agent', principal);+ await new Promise<void>((resolve) => setImmediate(resolve));+ try {+ expect(deps.connect).toHaveBeenCalledTimes(2);+ } finally {+ release();+ }+ await expect(result).resolves.toEqual([+ { server: 'docs', status: 'ready' },+ { server: 'private', status: 'ready' },+ ]);+});++it('bounds simultaneous MCP connection probes', async () => {+ const serverNames = ['one', 'two', 'three', 'four', 'five'];+ const { check, deps } = setup(serverNames.map((name) => `search_mcp_${name}`));+ deps.getServerConfigs = async () => Object.fromEntries(serverNames.map((name) => [name, server]));+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ const connect = deps.connect;+ deps.connect = jest.fn(async (options) => {+ await gate;+ return connect(options);+ });++ const result = check('agent', principal);+ await new Promise<void>((resolve) => setImmediate(resolve));+ try {+ expect(deps.connect).toHaveBeenCalledTimes(3);+ } finally {+ release();+ }+ await expect(result).resolves.toHaveLength(5);+ expect(deps.connect).toHaveBeenCalledTimes(5);+});++it('disposes each transport before releasing its shared probe slot', async () => {+ const serverNames = Array.from({ length: 12 }, (_, index) => `server-${index}`);+ const { check, deps } = setup(serverNames.map((name) => `search_mcp_${name}`));+ deps.getServerConfigs = async () => Object.fromEntries(serverNames.map((name) => [name, server]));+ let live = 0;+ let maxLive = 0;+ const disconnect = jest.fn(async () => {+ live -= 1;+ });+ deps.connect = jest.fn(async (options) => {+ live += 1;+ maxLive = Math.max(maxLive, live);+ options.requestScopedConnections?.connections.set(options.serverName, { disconnect });+ return {+ fetchToolsSnapshot: async () => ({+ tools: [{ name: 'search', inputSchema: { type: 'object' as const } }],+ complete: true,+ }),+ };+ });++ await expect(check('agent', principal, { concurrency: 10 })).resolves.toHaveLength(12);+ expect(maxLive).toBeLessThanOrEqual(10);+ expect(live).toBe(0);+ expect(disconnect).toHaveBeenCalledTimes(12);+});++it('bounds config-source initialization before connection probing', async () => {+ const serverNames = Array.from({ length: 12 }, (_, index) => `server-${index}`);+ const { check, deps } = setup(serverNames.map((name) => `search_mcp_${name}`));+ const serverConfigs = Object.fromEntries(serverNames.map((name) => [name, server]));+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: serverConfigs,+ }) as unknown as AppConfig,+ );+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ let markTenStarted: () => void = () => undefined;+ const tenStarted = new Promise<void>((resolve) => {+ markTenStarted = resolve;+ });+ let active = 0;+ let maxActive = 0;+ deps.ensureConfigServers = jest.fn(async (config, limit = (task) => task()) => {+ const initialized: Record<string, ParsedServerConfig> = {};+ await Promise.all(+ Object.entries(config).map(([name, value]) =>+ limit(async () => {+ active += 1;+ maxActive = Math.max(maxActive, active);+ if (active === 10) markTenStarted();+ await gate;+ active -= 1;+ initialized[name] = value as ParsedServerConfig;+ }),+ ),+ );+ return initialized;+ });+ deps.getServerConfigs = async (_userId, config) => config;++ const result = check('agent', principal, { concurrency: 10 });+ await tenStarted;+ expect(active).toBe(10);+ release();+ await expect(result).resolves.toHaveLength(12);+ expect(maxActive).toBe(10);+});++it('does not start queued config initialization after cancellation', async () => {+ const serverNames = ['first', 'queued-1', 'queued-2'];+ const { check, deps } = setup(serverNames.map((name) => `search_mcp_${name}`));+ const serverConfigs = Object.fromEntries(serverNames.map((name) => [name, server]));+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: serverConfigs,+ }) as unknown as AppConfig,+ );+ let releaseFirst: () => void = () => undefined;+ const firstGate = new Promise<void>((resolve) => {+ releaseFirst = resolve;+ });+ let markFirstStarted: () => void = () => undefined;+ const firstStarted = new Promise<void>((resolve) => {+ markFirstStarted = resolve;+ });+ let markFinished: () => void = () => undefined;+ const finished = new Promise<void>((resolve) => {+ markFinished = resolve;+ });+ const started: string[] = [];+ deps.ensureConfigServers = jest.fn(async (config, limit = (task) => task()) => {+ await Promise.allSettled(+ Object.entries(config).map(([name]) =>+ limit(async () => {+ started.push(name);+ if (name === 'first') {+ markFirstStarted();+ await firstGate;+ }+ }),+ ),+ );+ markFinished();+ return config as Record<string, ParsedServerConfig>;+ });+ const controller = new AbortController();+ const result = check('agent', principal, { concurrency: 1, signal: controller.signal });++ await firstStarted;+ controller.abort(new Error('canceled'));+ await expect(result).rejects.toThrow('canceled');+ releaseFirst();+ await finished;+ expect(started).toEqual(['first']);+});++it('bounds MCP connection probes across concurrent schedule preflights', async () => {+ const serverNames = Array.from({ length: 12 }, (_, index) => `server-${index}`);+ const { check, deps } = setup(serverNames.map((name) => `search_mcp_${name}`));+ const serverConfigs = Object.fromEntries(serverNames.map((name) => [name, server]));+ deps.getAppConfig = jest.fn(+ async () =>+ ({+ endpoints: { agents: { capabilities: [AgentCapabilities.tools] } },+ mcpConfig: serverConfigs,+ }) as unknown as AppConfig,+ );+ deps.getServerConfigs = async () => serverConfigs;+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ let markTenStarted: () => void = () => undefined;+ const tenStarted = new Promise<void>((resolve) => {+ markTenStarted = resolve;+ });+ const connect = deps.connect;+ let active = 0;+ let maxActive = 0;+ deps.connect = jest.fn(async (options) => {+ active += 1;+ maxActive = Math.max(maxActive, active);+ if (active === 10) markTenStarted();+ await gate;+ active -= 1;+ return connect(options);+ });++ const first = check('agent', principal, { concurrency: 10 });+ const second = check('agent', principal, { concurrency: 10 });+ await tenStarted;+ expect(deps.connect).toHaveBeenCalledTimes(10);+ release();+ await expect(Promise.all([first, second])).resolves.toEqual([+ expect.arrayContaining([{ server: serverNames[0], status: 'ready' }]),+ expect.arrayContaining([{ server: serverNames[0], status: 'ready' }]),+ ]);+ expect(maxActive).toBe(10);+ expect(deps.connect).toHaveBeenCalledTimes(24);+});++it('honors the configured MCP probe concurrency', async () => {+ const { check, deps } = setup(['search_mcp_docs', 'search_mcp_private']);+ deps.getServerConfigs = async () => ({ docs: server, private: server });+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ const connect = deps.connect;+ deps.connect = jest.fn(async (options) => {+ await gate;+ return connect(options);+ });++ const result = check('agent', principal, { concurrency: 1 });+ await new Promise<void>((resolve) => setImmediate(resolve));+ try {+ expect(deps.connect).toHaveBeenCalledTimes(1);+ } finally {+ release();+ }+ await expect(result).resolves.toHaveLength(2);+});++it('passes cancellation to connection setup and tool discovery', async () => {+ const { check, deps } = setup();+ const controller = new AbortController();+ const fetchToolsSnapshot = jest.fn(+ async (+ _deadline?: number,+ signal?: AbortSignal,+ ): Promise<import('../mcp/connection').MCPToolsSnapshot> => {+ expect(signal).toBe(controller.signal);+ return {+ tools: [{ name: 'search', inputSchema: { type: 'object' as const } }],+ complete: true,+ };+ },+ );+ deps.connect = jest.fn(async (options) => {+ expect(options.signal).toBe(controller.signal);+ return { fetchToolsSnapshot };+ });++ await expect(check('agent', principal, { signal: controller.signal })).resolves.toEqual([+ { server: 'docs', status: 'ready' },+ ]);+ expect(fetchToolsSnapshot).toHaveBeenCalledWith(undefined, controller.signal);+});++it('passes the aggregate lease deadline to tool discovery', async () => {+ const { check, deps } = setup();+ const deadlineMs = Date.now() + 60_000;+ const fetchToolsSnapshot = jest.fn(async () => ({+ tools: [{ name: 'search', inputSchema: { type: 'object' as const } }],+ complete: true,+ }));+ deps.connect = jest.fn(async (options) => {+ expect(options.signal).toBeDefined();+ return { fetchToolsSnapshot };+ });++ await check('agent', principal, { deadlineMs });++ expect(fetchToolsSnapshot).toHaveBeenCalledWith(deadlineMs, expect.any(AbortSignal));+});++it('enforces the aggregate deadline while loading the agent graph', async () => {+ const { check, deps } = setup([]);+ deps.getAgentGraphNodes = jest.fn(() => new Promise<AgentGraphNode[]>(() => undefined));++ await expect(check('agent', principal, { deadlineMs: Date.now() + 20 })).rejects.toMatchObject({+ name: 'TimeoutError',+ });+});diff --git a/packages/api/src/schedules/mcp.ts b/packages/api/src/schedules/mcp.tsnew file mode 100644index 0000000000..7bbb1a9de0--- /dev/null+++ b/packages/api/src/schedules/mcp.ts@@ -0,0 +1,677 @@+import { randomUUID } from 'node:crypto';+import {+ AgentCapabilities,+ Constants,+ EModelEndpoint,+ MAX_SUBAGENT_DEPTH,+ MAX_SUBAGENT_GRAPH_NODES,+ MAX_SUBAGENT_RUN_CONFIGS,+ Permissions,+ PermissionTypes,+ isActionTool,+ buildServerNameAliases,+ normalizeMCPToolKey,+ normalizeServerName,+ resolveModelCatalogKey,+} from 'librechat-data-provider';+import type {+ IUser,+ AppConfig,+ PluginAuthMethods,+ AgentGraphNode,+ AgentGraphAccessContext,+} from '@librechat/data-schemas';+import type { TModelsConfig, ScheduleMCPStatus, ScheduleMCPOutcome } from 'librechat-data-provider';+import type { ParsedServerConfig, UserMCPConnectionOptions } from '../mcp/types';+import type { CheckAccessParams } from '../middleware/access';+import type { MCPToolsSnapshot } from '../mcp/connection';+import type { GetAppConfigOptions } from '../app/service';+import type { ScheduleMCPPreflight } from './types';+import {+ MCPAuthenticationRejectedError,+ MCPOAuthSecretReentryRequiredError,+ isOAuthAuthenticationError,+} from '../mcp/errors';+import {+ getMissingCustomUserVars,+ splitMCPToolKey,+ findShadowedServerNames,+ createDeadlineAbortSignal,+} from '../mcp/utils';+import { MCPConfigInitializationCanceledError } from '../mcp/registry/MCPServersRegistry';+import { createMCPRequestContext, cleanupMCPRequestContext } from '../mcp/request';+import { getAppConfigOptionsFromUser } from '../app/service';+import { createConcurrencyLimiter } from '../utils/promise';+import { OpenIDReauthRequiredError } from '../utils/oidc';+import { resolveReachableGraph } from '../agents/edges';+import { formatMCPServerTools } from '../mcp/tools';+import { checkAccess } from '../middleware/access';+import { detachOnAbort } from '../utils/promises';+import { getPluginAuthMap } from '../agents/auth';++// The public schedule schema caps mcpPreflightConcurrency at 10. Keep the same+// ceiling across every preflight owned by this process so concurrent schedules+// cannot multiply that per-request fan-out into an unbounded connection burst.+const MAX_SHARED_MCP_PREFLIGHT_CONCURRENCY = 10;++export class ScheduleMCPError extends Error {+ readonly code: Exclude<ScheduleMCPStatus, 'ready'>;++ constructor(readonly outcomes: ScheduleMCPOutcome[]) {+ const code = getScheduleMCPFailureCode(outcomes);+ super(`${code}: ${JSON.stringify(outcomes)}`);+ this.code = code;+ }+}++/** One response discriminator for every schedule admission surface. */+export function getScheduleMCPFailureCode(+ outcomes: ScheduleMCPOutcome[],+): Exclude<ScheduleMCPStatus, 'ready'> {+ if (outcomes.some((item) => item.status === 'mcp_permission_denied'))+ return 'mcp_permission_denied';+ if (outcomes.some((item) => item.status === 'mcp_configuration_missing'))+ return 'mcp_configuration_missing';+ if (outcomes.some((item) => item.status === 'mcp_reauth_required')) return 'mcp_reauth_required';+ return 'mcp_unavailable';+}++interface ScheduleMCPDeps {+ resolveAgentGraphAccess: (access: {+ userId: string;+ role?: string | null;+ idOnTheSource?: string | null;+ }) => Promise<AgentGraphAccessContext>;+ getAgentGraphNodes: (+ ids: string[],+ access?: AgentGraphAccessContext,+ ) => Promise<AgentGraphNode[]>;+ getModelsConfig: (user: IUser) => Promise<TModelsConfig>;+ getRoleByName: CheckAccessParams['getRoleByName'];+ getUser: (id: string) => Promise<IUser | null>;+ getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig | undefined>;+ ensureConfigServers: (+ config: NonNullable<AppConfig['mcpConfig']>,+ limit?: <T>(task: () => Promise<T>) => Promise<T>,+ ) => Promise<Record<string, ParsedServerConfig>>;+ getServerConfigs: (+ userId: string,+ config: Record<string, ParsedServerConfig>,+ role?: string,+ ) => Promise<Record<string, ParsedServerConfig>>;+ findPluginAuthsByKeys: PluginAuthMethods['findPluginAuthsByKeys'];+ connect: (options: UserMCPConnectionOptions) => Promise<{+ fetchToolsSnapshot: (deadlineMs?: number, signal?: AbortSignal) => Promise<MCPToolsSnapshot>;+ }>;+}++/** Probes only persisted identity and credentials, with isolated user connections and no OAuth wait. */+export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPreflight {+ const sharedProbeLimit = createConcurrencyLimiter(MAX_SHARED_MCP_PREFLIGHT_CONCURRENCY);+ const runPreflight: ScheduleMCPPreflight = async (agentId, principal, options) => {+ const signal = options.signal;+ const throwIfAborted = () => {+ if (signal?.aborted) throw signal.reason ?? new Error('MCP preflight aborted');+ };+ throwIfAborted();+ const user = await deps.getUser(principal.id);+ throwIfAborted();+ if (!user) throw new ScheduleMCPError([]);+ user.id = principal.id;+ let appConfig: AppConfig | undefined;+ const loadAppConfig = async (): Promise<AppConfig | undefined> => {+ appConfig ??= await deps.getAppConfig({+ ...getAppConfigOptionsFromUser(user),+ failClosed: true,+ });+ return appConfig;+ };+ const tools: Array<{ name: string; agentId: string }> = [];+ const serverHints = new Set<string>();+ const graphEdges: NonNullable<AgentGraphNode['edges']> = [];+ const explicitSeeds = new Set<string>([agentId]);+ const attempted = new Set<string>();+ const expanded = new Set<string>();+ const expandedHandoffs = new Set<string>();+ const expandedHandoffEdges = new Set<string>();+ const viewableById = new Map<string, AgentGraphNode>();+ const accessibleById = new Map<string, AgentGraphNode>();+ const subagentGraphIds = new Set<string>();+ const accessIdentity = {+ userId: user.id,+ role: user.role,+ idOnTheSource: user.idOnTheSource,+ };+ let accessContext: AgentGraphAccessContext | undefined;+ let modelsConfig: TModelsConfig | undefined;++ const loadNodes = async (ids: string[]): Promise<void> => {+ const frontier = [...new Set(ids)].filter(+ (id) => !attempted.has(id) && id !== '__start__' && id !== '__end__' && id.length > 0,+ );+ if (frontier.length === 0) return;+ frontier.forEach((id) => attempted.add(id));+ let loaded: AgentGraphNode[] = [];+ if (frontier.includes(agentId)) {+ const root = await deps.getAgentGraphNodes([agentId]);+ const descendants = frontier.filter((id) => id !== agentId);+ loaded = [+ ...root,+ ...(descendants.length > 0+ ? await deps.getAgentGraphNodes(+ descendants,+ (accessContext ??= await deps.resolveAgentGraphAccess(accessIdentity)),+ )+ : []),+ ];+ } else {+ loaded = await deps.getAgentGraphNodes(+ frontier,+ (accessContext ??= await deps.resolveAgentGraphAccess(accessIdentity)),+ );+ }+ throwIfAborted();+ const descendants = loaded.filter((agent) => agent.id !== agentId);+ if (descendants.length > 0) {+ modelsConfig ??= await deps.getModelsConfig(user);+ }+ for (const agent of loaded) {+ viewableById.set(agent.id, agent);+ const availableModels =+ agent.id === agentId+ ? undefined+ : modelsConfig?.[resolveModelCatalogKey(agent.provider, modelsConfig)];+ if (+ agent.id === agentId ||+ (agent.model.length > 0 && availableModels?.includes(agent.model) === true)+ ) {+ accessibleById.set(agent.id, agent);+ }+ }+ };++ // Match discoverConnectedAgents first: handoff agents are initialized and pruned+ // before any isolated subagent descriptors or graph definitions are considered.+ type HandoffCandidate = { id: string; expandEdges: boolean };+ let handoffFrontier: HandoffCandidate[] = [{ id: agentId, expandEdges: true }];+ while (handoffFrontier.length > 0) {+ const frontier = handoffFrontier;+ handoffFrontier = [];+ await loadNodes(frontier.map(({ id }) => id));+ for (const { id, expandEdges } of frontier) {+ const agent = accessibleById.get(id);+ if (!agent) continue;+ expandedHandoffs.add(id);+ expanded.add(id);+ if (agent.id === agentId) {+ let previousId = agent.id;+ for (const childId of agent.agent_ids ?? []) {+ if (childId === agent.id || childId.length === 0) continue;+ graphEdges.push({ from: previousId, to: childId });+ // discoverConnectedAgents initializes legacy chain members only after+ // recursive handoff discovery and never collects their persisted edges.+ handoffFrontier.push({ id: childId, expandEdges: false });+ previousId = childId;+ }+ }+ if (!expandEdges || expandedHandoffEdges.has(id)) continue;+ expandedHandoffEdges.add(id);+ graphEdges.push(...(agent.edges ?? []));+ for (const edge of agent.edges ?? []) {+ handoffFrontier.push(+ ...[edge.from, edge.to].flat().map((childId) => ({+ id: childId,+ expandEdges: true,+ })),+ );+ }+ }+ }++ const handoffSkippedIds = new Set(+ [...attempted].filter((id) => id !== agentId && !accessibleById.has(id)),+ );+ const { reachable: reachableHandoffIds } = resolveReachableGraph(+ new Set([agentId]),+ expandedHandoffs,+ graphEdges,+ handoffSkippedIds,+ );+ const rootConfigs = [...reachableHandoffIds]+ .map((id) => accessibleById.get(id))+ .filter((agent): agent is AgentGraphNode => agent != null);+ const rootConfigIds = new Set(rootConfigs.map((agent) => agent.id));+ const directValidationContexts: Array<{+ id: string;+ ancestors: Set<string>;+ acceptedGraphCount: number;+ }> = [];+ const acceptedGraphCounts = new Map<string, number>();+ let expandedSubagentConfigs = 0;+ let subagentsAvailable: boolean | undefined;+ const canUseSubagents = async (): Promise<boolean> => {+ if (subagentsAvailable != null) return subagentsAvailable;+ const config = await loadAppConfig();+ subagentsAvailable = (+ config?.endpoints?.[EModelEndpoint.agents]?.capabilities ?? []+ ).includes(AgentCapabilities.subagents);+ return subagentsAvailable;+ };+ const addGraphBudgetMember = (id: string): void => {+ if (id === agentId || subagentGraphIds.has(id)) return;+ if (subagentGraphIds.size >= MAX_SUBAGENT_GRAPH_NODES) {+ throw new Error(+ `Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.`,+ );+ }+ subagentGraphIds.add(id);+ };+ const countExpandedSubagentConfig = (): void => {+ expandedSubagentConfigs += 1;+ if (expandedSubagentConfigs > MAX_SUBAGENT_RUN_CONFIGS) {+ throw new Error(+ `Subagent run configuration exceeds the maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries.`,+ );+ }+ };+ const includeGraph = async (ids: string[], parentRunnable: boolean): Promise<boolean> => {+ await loadNodes(ids);+ if (!parentRunnable || ids.some((id) => !accessibleById.has(id))) return false;+ for (const id of ids) {+ explicitSeeds.add(id);+ expanded.add(id);+ }+ return true;+ };+ const processDirectGraphs = async (+ agent: AgentGraphNode,+ parentRunnable: boolean,+ ): Promise<number> => {+ if (!agent.subagents?.enabled || !(await canUseSubagents())) return 0;+ const definitions = agent.subagents.graphs ?? [];+ let acceptedGraphCount = 0;+ const memberIds = [...new Set(definitions.flatMap((graph) => graph.agent_ids ?? []))].filter(+ (id) => id !== agent.id && id !== agentId && !rootConfigIds.has(id),+ );+ const staged = memberIds.filter((id) => !subagentGraphIds.has(id));+ if (subagentGraphIds.size + staged.length > MAX_SUBAGENT_GRAPH_NODES) {+ throw new Error(+ `Subagent graph exceeds the maximum of ${MAX_SUBAGENT_GRAPH_NODES} unique agents.`,+ );+ }+ staged.forEach((id) => subagentGraphIds.add(id));+ await loadNodes(memberIds);+ for (const definition of definitions) {+ const ids = [...new Set(definition.agent_ids ?? [])];+ if (await includeGraph(ids, parentRunnable)) {+ acceptedGraphCount += 1;+ }+ }+ return acceptedGraphCount;+ };+ const visitDirectTree = async (+ agent: AgentGraphNode,+ depth: number,+ ancestors: Set<string>,+ parentRunnable: boolean,+ ): Promise<void> => {+ if (!agent.subagents?.enabled || !(await canUseSubagents())) return;+ if (agent.subagents.allowSelf !== false) countExpandedSubagentConfig();+ const directIds = [...new Set(agent.subagents.agent_ids ?? [])].filter(+ (id) => id.length > 0 && id !== agent.id,+ );+ if (directIds.length > 0 && depth >= MAX_SUBAGENT_DEPTH) {+ throw new Error(+ `Subagent graph exceeds the maximum depth of ${MAX_SUBAGENT_DEPTH} at agent ${agent.id}.`,+ );+ }+ await loadNodes(directIds);+ const nextAncestors = new Set(ancestors);+ nextAncestors.add(agent.id);+ for (const childId of directIds) {+ if (nextAncestors.has(childId) || handoffSkippedIds.has(childId)) continue;+ // Lazy runtime initialization loads VIEW-checked metadata before model+ // validation. Even an invalid-model descriptor consumes depth, expanded-+ // config, and graph-node budgets, but its MCP tools can never execute.+ const child = viewableById.get(childId);+ if (!child) continue;+ addGraphBudgetMember(childId);+ countExpandedSubagentConfig();+ const childRunnable = parentRunnable && accessibleById.has(childId);+ const validationContext = childRunnable+ ? { id: childId, ancestors: nextAncestors, acceptedGraphCount: 0 }+ : undefined;+ if (validationContext) {+ directValidationContexts.push(validationContext);+ explicitSeeds.add(childId);+ expanded.add(childId);+ }+ await visitDirectTree(child, depth + 1, nextAncestors, childRunnable);+ // initializeClient preloads a direct child's graph members only after its+ // complete nested direct tree, before root-level graphs are resolved.+ const acceptedGraphCount = await processDirectGraphs(child, childRunnable);+ if (validationContext) validationContext.acceptedGraphCount = acceptedGraphCount;+ }+ };++ for (const root of rootConfigs) {+ await visitDirectTree(root, 0, new Set(), true);+ }+ // Root and handoff graph definitions run after every direct tree. Each definition+ // is skipped atomically when its new members would exceed the shared runtime budget.+ for (const root of rootConfigs) {+ if (!root.subagents?.enabled || !(await canUseSubagents())) continue;+ for (const definition of root.subagents.graphs ?? []) {+ const ids = [...new Set(definition.agent_ids ?? [])];+ const staged = ids.filter(+ (id) => id !== agentId && !rootConfigIds.has(id) && !subagentGraphIds.has(id),+ );+ if (subagentGraphIds.size + staged.length > MAX_SUBAGENT_GRAPH_NODES) continue;+ staged.forEach((id) => subagentGraphIds.add(id));+ if (await includeGraph(ids, true)) {+ acceptedGraphCounts.set(root.id, (acceptedGraphCounts.get(root.id) ?? 0) + 1);+ }+ }+ }+ const validateRunConfigTree = (+ agent: AgentGraphNode,+ state: { count: number },+ ancestors: Set<string>,+ acceptedGraphCount = acceptedGraphCounts.get(agent.id) ?? 0,+ ): void => {+ if (!agent.subagents?.enabled || subagentsAvailable !== true) return;+ const count = (): void => {+ state.count += 1;+ if (state.count > MAX_SUBAGENT_RUN_CONFIGS) {+ throw new Error(+ `Subagent run configuration exceeds the maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries.`,+ );+ }+ };+ if (agent.subagents.allowSelf !== false) count();+ const nextAncestors = new Set(ancestors);+ nextAncestors.add(agent.id);+ for (const childId of new Set(agent.subagents.agent_ids ?? [])) {+ if (childId === agent.id || nextAncestors.has(childId)) continue;+ const child = viewableById.get(childId);+ if (!child) continue;+ count();+ // Only already initialized handoff configs are eager in the initial run.+ // Other direct children resolve lazily with their own fresh counter below.+ if (rootConfigIds.has(childId)) {+ validateRunConfigTree(child, state, nextAncestors);+ }+ }+ for (let index = 0; index < acceptedGraphCount; index++) count();+ };+ const initialRunState = { count: 0 };+ for (const root of rootConfigs) {+ validateRunConfigTree(root, initialRunState, new Set());+ }+ for (const { id: directId, ancestors, acceptedGraphCount } of directValidationContexts) {+ if (rootConfigIds.has(directId)) continue;+ const direct = accessibleById.get(directId);+ if (!direct) continue;+ // createLazySubagentConfig seeds the selected child's resolution at one.+ validateRunConfigTree(direct, { count: 1 }, ancestors, acceptedGraphCount);+ }+ const skippedAgentIds = new Set(+ [...attempted].filter((id) => id !== agentId && !accessibleById.has(id)),+ );+ const { reachable } = resolveReachableGraph(+ explicitSeeds,+ expanded,+ graphEdges,+ skippedAgentIds,+ );+ for (const id of reachable) {+ const agent = accessibleById.get(id);+ if (!agent || !expanded.has(id)) continue;+ tools.push(+ ...(agent.tools ?? [])+ .filter((tool) => !isActionTool(tool))+ .map((name) => ({ name, agentId: agent.id })),+ );+ for (const name of agent.mcpServerNames ?? []) serverHints.add(name);+ }+ const selectedTools = tools.filter(+ ({ name }) =>+ name.includes(Constants.mcp_delimiter) &&+ !name.startsWith(`${Constants.mcp_server}${Constants.mcp_delimiter}`),+ );+ if (selectedTools.length === 0) return [];++ const effectiveConfig = await loadAppConfig();+ const rawConfig = effectiveConfig?.mcpConfig ?? {};+ const configNames = Object.keys(rawConfig);+ const candidateNames = Array.from(new Set([...configNames, ...serverHints]));+ // Authoritative config names claim normalized aliases before persisted hints.+ // A hint is often already normalized (for example `Sales_Force` for the real+ // config name `Sales Force`) and must not shadow that registry identity.+ const aliases = buildServerNameAliases(configNames);+ for (const hint of serverHints) {+ if (!aliases.has(hint)) aliases.set(hint, hint);+ const normalized = normalizeServerName(hint);+ if (!aliases.has(normalized)) aliases.set(normalized, hint);+ }+ const collectSelected = (+ rawNames: string[],+ nameAliases: Map<string, string>,+ exactNames: Set<string>,+ ) => {+ const candidates = [...rawNames, ...nameAliases.keys()];+ const selected = new Map<string, string[]>();+ const serverAgentIds = new Map<string, Set<string>>();+ const toolAgentIds = new Map<string, Map<string, Set<string>>>();+ for (const { name: tool, agentId: toolAgentId } of selectedTools) {+ const [, name] = splitMCPToolKey(tool, candidates);+ if (!name) continue;+ const server = exactNames.has(name) ? name : (nameAliases.get(name) ?? name);+ const owners = serverAgentIds.get(server) ?? new Set<string>();+ owners.add(toolAgentId);+ serverAgentIds.set(server, owners);+ const required = selected.get(server) ?? [];+ if (!tool.startsWith(`${Constants.mcp_all}${Constants.mcp_delimiter}`)) {+ const normalizedTool = normalizeMCPToolKey(tool, rawNames);+ required.push(normalizedTool);+ const serverTools = toolAgentIds.get(server) ?? new Map<string, Set<string>>();+ const toolOwners = serverTools.get(normalizedTool) ?? new Set<string>();+ toolOwners.add(toolAgentId);+ serverTools.set(normalizedTool, toolOwners);+ toolAgentIds.set(server, serverTools);+ }+ selected.set(server, required);+ }+ return { selected, serverAgentIds, toolAgentIds };+ };+ let { selected, serverAgentIds, toolAgentIds } = collectSelected(+ candidateNames,+ aliases,+ new Set(configNames),+ );+ const outcomesForOwners = (+ server: string,+ status: ScheduleMCPStatus,+ preferredOwners?: Set<string>,+ ): ScheduleMCPOutcome[] => {+ const owners = preferredOwners ?? serverAgentIds.get(server);+ if (!owners || owners.size === 0) return [{ server, status }];+ if (status === 'ready') {+ const ownerId = owners.has(agentId) ? agentId : owners.values().next().value;+ return [{ server, status, ...(ownerId !== agentId ? { agentId: ownerId } : {}) }];+ }+ return [...owners].map((ownerId) => ({+ server,+ status,+ ...(ownerId !== agentId ? { agentId: ownerId } : {}),+ }));+ };+ const capabilities = effectiveConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities ?? [];+ if (!capabilities.includes(AgentCapabilities.tools)) {+ throw new ScheduleMCPError(+ [...selected.keys()].flatMap((server) =>+ outcomesForOwners(server, 'mcp_configuration_missing'),+ ),+ );+ }+ if (+ !(await checkAccess({+ user,+ permissionType: PermissionTypes.MCP_SERVERS,+ permissions: [Permissions.USE],+ getRoleByName: deps.getRoleByName,+ }))+ ) {+ throw new ScheduleMCPError(+ [...selected.keys()].flatMap((server) =>+ outcomesForOwners(server, 'mcp_permission_denied'),+ ),+ );+ }+ // Resolve once more against the ACL-filtered registry before initializing config.+ // Exact accessible identities must beat normalized aliases from another tier, just+ // as they do in the interactive runtime.+ const accessibleServers = await deps.getServerConfigs(user.id, {}, user.role);+ const authoritativeNames = Array.from(+ new Set([...Object.keys(accessibleServers), ...configNames]),+ );+ const authoritativeCandidates = Array.from(new Set([...authoritativeNames, ...serverHints]));+ const authoritativeAliases = buildServerNameAliases(authoritativeNames);+ for (const hint of serverHints) {+ if (!authoritativeAliases.has(hint)) authoritativeAliases.set(hint, hint);+ const normalized = normalizeServerName(hint);+ if (!authoritativeAliases.has(normalized)) authoritativeAliases.set(normalized, hint);+ }+ ({ selected, serverAgentIds, toolAgentIds } = collectSelected(+ authoritativeCandidates,+ authoritativeAliases,+ new Set([...Object.keys(accessibleServers), ...configNames]),+ ));+ const selectedRawConfig = Object.fromEntries(+ Object.entries(rawConfig).filter(([serverName]) => selected.has(serverName)),+ );+ const requestProbeLimit = createConcurrencyLimiter(options.concurrency);+ const config = await deps.ensureConfigServers(selectedRawConfig, (task) =>+ requestProbeLimit(() => {+ if (signal?.aborted) throw new MCPConfigInitializationCanceledError();+ return sharedProbeLimit(async () => {+ if (signal?.aborted) throw new MCPConfigInitializationCanceledError();+ return task();+ });+ }),+ );+ const servers = await deps.getServerConfigs(user.id, config, user.role);+ const shadowed = findShadowedServerNames(+ Array.from(new Set([...configNames, ...Object.keys(servers)])),+ );+ throwIfAborted();+ const auth = await getPluginAuthMap({+ userId: user.id,+ pluginKeys: [...selected.keys()].map((server) => `${Constants.mcp_prefix}${server}`),+ throwError: true,+ findPluginAuthsByKeys: deps.findPluginAuthsByKeys,+ });+ const requestBody = {+ messageId: randomUUID(),+ conversationId: randomUUID(),+ parentMessageId: String(Constants.NO_PARENT),+ };+ const outcomes = (+ await Promise.all(+ [...selected].map(([server, required]) =>+ requestProbeLimit(() =>+ sharedProbeLimit(async (): Promise<ScheduleMCPOutcome[]> => {+ const context = createMCPRequestContext();+ try {+ throwIfAborted();+ const serverConfig = servers[server];+ const customUserVars = auth[`${Constants.mcp_prefix}${server}`];+ if (+ !serverConfig ||+ shadowed.has(server) ||+ getMissingCustomUserVars(serverConfig, customUserVars).length > 0+ ) {+ return outcomesForOwners(server, 'mcp_configuration_missing');+ }+ let reauth = false;+ try {+ const connection = await deps.connect({+ user,+ serverName: server,+ serverConfig,+ customUserVars,+ requestBody,+ requestScopedConnections: context,+ ephemeralConnection: true,+ returnOnOAuth: true,+ oauthStart: async () => {+ reauth = true;+ },+ signal,+ });+ const snapshot = await connection.fetchToolsSnapshot(options.deadlineMs, signal);+ if (snapshot.authenticationError) throw snapshot.authenticationError;+ const available = new Set(+ Object.keys(formatMCPServerTools(server, snapshot.tools)),+ );+ for (const tool of snapshot.tools) {+ available.add(+ `${tool.name}${Constants.mcp_delimiter}${normalizeServerName(server)}`,+ );+ }+ let status: ScheduleMCPStatus = 'ready';+ if (reauth) {+ status = 'mcp_reauth_required';+ } else if (!snapshot.complete) {+ status = 'mcp_unavailable';+ } else if (+ available.size === 0 ||+ !required.every((tool) => available.has(tool))+ ) {+ status = 'mcp_configuration_missing';+ }+ const missingTools =+ status === 'mcp_configuration_missing'+ ? required.filter((tool) => !available.has(tool))+ : [];+ const missingOwners = new Set<string>();+ for (const missingTool of missingTools) {+ for (const ownerId of toolAgentIds.get(server)?.get(missingTool) ?? []) {+ missingOwners.add(ownerId);+ }+ }+ return outcomesForOwners(+ server,+ status,+ missingOwners.size > 0 ? missingOwners : undefined,+ );+ } catch (error) {+ return outcomesForOwners(+ server,+ reauth ||+ error instanceof MCPAuthenticationRejectedError ||+ error instanceof OpenIDReauthRequiredError ||+ error instanceof MCPOAuthSecretReentryRequiredError ||+ isOAuthAuthenticationError(error)+ ? 'mcp_reauth_required'+ : 'mcp_unavailable',+ );+ }+ } finally {+ // The shared slot bounds live transports, not only tools/list calls.+ // Dispose this probe's isolated connection before releasing the slot.+ await cleanupMCPRequestContext(context);+ }+ }),+ ),+ ),+ )+ ).flat();+ if (outcomes.some((item) => item.status !== 'ready')) throw new ScheduleMCPError(outcomes);+ return outcomes;+ };+ return (agentId, principal, options) => {+ const signal = createDeadlineAbortSignal(options.deadlineMs, options.signal);+ return detachOnAbort(runPreflight(agentId, principal, { ...options, signal }), signal);+ };+}diff --git a/packages/api/src/schedules/project.spec.ts b/packages/api/src/schedules/project.spec.tsindex 8e8b2bee5f..63e63102e1 100644--- a/packages/api/src/schedules/project.spec.ts+++ b/packages/api/src/schedules/project.spec.ts@@ -15,7 +15,10 @@ const BASE_LIMITS: ScheduleLimits = {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,};@@ -76,6 +79,7 @@ function makeEngineDeps(getLimits: async () => BASE_LIMITS,getUserContext: async () => OWNER,isOutOfBalance: async () => false,+ preflightMCP: jest.fn().mockResolvedValue([]),agentAccess: async () => 'ok',projectAccess: async () => 'ok',hasScheduleAccess: async () => true,@@ -351,6 +355,7 @@ function makeHandlerDeps(const deps = {methods: methods as unknown as SchedulesHandlersDeps['methods'],getLimits: async () => ({ ...BASE_LIMITS, ...limits }),+ preflightMCP: jest.fn().mockResolvedValue([]),canViewAgent: async () => true,canUseProject: async () => true,filterOwnedFileIds: async (ids: string[]) => ids,diff --git a/packages/api/src/schedules/service.spec.ts b/packages/api/src/schedules/service.spec.tsindex ae35656ab7..8aa1318d8e 100644--- a/packages/api/src/schedules/service.spec.ts+++ b/packages/api/src/schedules/service.spec.ts@@ -65,6 +65,7 @@ function makeService(findBalance: jest.fn(async () => null),upsertBalance: jest.fn(async () => null),initializeNullBalance: jest.fn(async () => null),+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(async () => 'ok' as const),getChatProject: jest.fn(async () => ({ _id: 'proj-1' })),isUserDeleting: jest.fn(async () => false),@@ -135,7 +136,10 @@ describe('manual Run Now lease cleanup', () => {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,requireProject: false,}),).rejects.toThrow('user lookup failed');@@ -169,6 +173,7 @@ describe('balance initialization', () => {findBalance,upsertBalance,initializeNullBalance,+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(async () => 'ok' as const),getChatProject: jest.fn(async () => ({ _id: 'proj-1' })),isUserDeleting: jest.fn(async () => false),@@ -281,6 +286,7 @@ describe('balance initialization', () => {})),upsertBalance,initializeNullBalance,+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(async () => 'ok' as const),getChatProject: jest.fn(async () => ({ _id: 'proj-1' })),isUserDeleting: jest.fn(async () => false),@@ -1515,7 +1521,10 @@ describe('scheduled resume capacity', () => {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 1,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 300_000,...(over.projectConfig ?? {}),},},@@ -1524,6 +1533,7 @@ describe('scheduled resume capacity', () => {findBalance: jest.fn(async () => null),upsertBalance: jest.fn(async () => null),initializeNullBalance: jest.fn(async () => null),+ preflightMCP: jest.fn().mockResolvedValue([]),resolveAgentFireAccess: jest.fn(async () => 'ok' as const),getChatProject: jest.fn(async () => ('project' in over ? over.project : { _id: 'proj-1' })),isUserDeleting: jest.fn(async () => false),@@ -1666,10 +1676,18 @@ describe('deployment-wide limits', () => {it('resolves a principal-less getLimits from the BASE config only', async () => {const getAppConfig = jest.fn(async (options?: { baseOnly?: boolean }) =>options?.baseOnly === true- ? { interfaceConfig: { schedules: { use: true, fireConcurrency: 1 } } }+ ? {+ interfaceConfig: {+ schedules: { use: true, fireConcurrency: 1, mcpPreflightConcurrency: 3 },+ },+ }: // The principal/tenant-merged view. A bare getAppConfig() resolves THIS,// including whatever tenant the ALS context happens to carry.- { interfaceConfig: { schedules: { use: true, fireConcurrency: 5 } } },+ {+ interfaceConfig: {+ schedules: { use: true, fireConcurrency: 5, mcpPreflightConcurrency: 3 },+ },+ },) as unknown as SchedulesServiceDeps['getAppConfig'];const service = makeService(noRuns(), getAppConfig);const limits = await service.getLimits();diff --git a/packages/api/src/schedules/service.ts b/packages/api/src/schedules/service.tsindex b09dc3e0c0..24ce736b1c 100644--- a/packages/api/src/schedules/service.ts+++ b/packages/api/src/schedules/service.ts@@ -6,6 +6,7 @@ import type { Types } from 'mongoose';import type {ScheduleEngineDeps,ScheduleDeleteResult,+ ScheduleMCPPreflight,ScheduleLimits,ScheduleUserContext,FireableSchedule,@@ -114,6 +115,7 @@ export type ScheduleResumeClaimResult =* directly.*/export interface SchedulesServiceDeps {+ preflightMCP: ScheduleMCPPreflight;methods: ScheduleMethods & {getRoleByName: (role?: string,@@ -187,6 +189,7 @@ export interface SchedulesService {fireScheduleNow: (schedule: FireableSchedule,limits: ScheduleLimits,+ options?: { signal?: AbortSignal },) => Promise<FireResult | null>;recordScheduleOutcome: (input: RecordScheduleOutcomeInput) => Promise<boolean>;/**@@ -377,7 +380,13 @@ export function createSchedulesService(minIntervalMinutes: config.minIntervalMinutes ?? DEFAULT_SCHEDULE_LIMITS.minIntervalMinutes,autoDisableAfterFailures:config.autoDisableAfterFailures ?? DEFAULT_SCHEDULE_LIMITS.autoDisableAfterFailures,+ admissionConcurrency:+ config.admissionConcurrency ?? DEFAULT_SCHEDULE_LIMITS.admissionConcurrency,fireConcurrency: config.fireConcurrency ?? DEFAULT_SCHEDULE_LIMITS.fireConcurrency,+ mcpPreflightConcurrency:+ config.mcpPreflightConcurrency ?? DEFAULT_SCHEDULE_LIMITS.mcpPreflightConcurrency,+ mcpPreflightTimeoutMs:+ config.mcpPreflightTimeoutMs ?? DEFAULT_SCHEDULE_LIMITS.mcpPreflightTimeoutMs,requireProject: config.requireProject === true || projectId != null,...(projectId != null && { projectId }),};@@ -427,6 +436,7 @@ export function createSchedulesService(}const engineDeps: ScheduleEngineDeps = {+ preflightMCP: deps.preflightMCP,methods,getLimits,// On the BASE deps, not only the engine's per-pass wrapper: fireScheduleNow@@ -757,6 +767,7 @@ export function createSchedulesService(async function fireScheduleNow(schedule: FireableSchedule,limits: ScheduleLimits,+ options?: { signal?: AbortSignal },): Promise<FireResult | null> {// The global stop means STOP: a manual run dispatches the same billed generation as// an automatic one, so gating only the engine tick would leave Run Now wide open.@@ -776,7 +787,10 @@ export function createSchedulesService(// Fire the FRESH leased row (post-image with the new claim token), not the// snapshot the route read before the lease — an edit that committed in the// window in between is reflected, so a stale prompt/agent is never dispatched.- return await fireSchedule(engineDeps, leased, limits, new Date(), { manual: true });+ return await fireSchedule(engineDeps, leased, limits, new Date(), {+ manual: true,+ signal: options?.signal,+ });} catch (err) {const released =claimToken != nulldiff --git a/packages/api/src/schedules/types.ts b/packages/api/src/schedules/types.tsindex e7182a80c0..6f3f29ba1c 100644--- a/packages/api/src/schedules/types.ts+++ b/packages/api/src/schedules/types.ts@@ -4,6 +4,7 @@ import type {AgentTriggerDeliveryStatus,AgentTriggerDeliveryFailure,} from '@librechat/data-schemas';+import type { ScheduleMCPOutcome } from 'librechat-data-provider';import type { Types } from 'mongoose';import type { AgentTriggerEnqueueOptions, AgentTriggerEnvelope } from '../agents/triggers';import type { SlotClaimResult } from './capacity';@@ -14,7 +15,13 @@ export interface ScheduleLimits {maxPerUser: number;minIntervalMinutes: number;autoDisableAfterFailures: number;+ /** Maximum claimed occurrences concurrently passing readiness admission per replica. */+ admissionConcurrency: number;fireConcurrency: number;+ /** Maximum MCP readiness probes active during one schedule admission. */+ mcpPreflightConcurrency: number;+ /** Maximum wall-clock time for one unattended MCP readiness admission. */+ mcpPreflightTimeoutMs: number;/** Every schedule must be filed under a chat project. A pinned `projectId`* implies this, so callers only ever have to read one flag. */requireProject: boolean;@@ -29,7 +36,10 @@ export const DEFAULT_SCHEDULE_LIMITS: ScheduleLimits = {maxPerUser: 10,minIntervalMinutes: 60,autoDisableAfterFailures: 5,+ admissionConcurrency: 20,fireConcurrency: 5,+ mcpPreflightConcurrency: 3,+ mcpPreflightTimeoutMs: 5 * 60_000,requireProject: false,};@@ -170,6 +180,7 @@ export interface ScheduleFileRef {}export interface ScheduleEngineDeps {+ preflightMCP: ScheduleMCPPreflight;methods: ScheduleMethods;/** Resolves interface.schedules limits, per-principal when a user is given. */getLimits: (user?: ScheduleUserContext) => Promise<ScheduleLimits>;@@ -292,6 +303,8 @@ export interface JobState {}export interface FireResult {+ mcp?: ScheduleMCPOutcome[];+ mcpPreflightUnavailable?: boolean;fired: boolean;conversationId?: string;skipped?:@@ -312,3 +325,9 @@ export interface FireResult {}export type FireableSchedule = ISchedule;++export type ScheduleMCPPreflight = (+ agentId: string,+ user: ScheduleUserContext,+ options: { concurrency: number; signal?: AbortSignal; deadlineMs?: number },+) => Promise<ScheduleMCPOutcome[]>;diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.tsindex 72dafeb6c3..bd9f964b07 100644--- a/packages/data-provider/src/config.spec.ts+++ b/packages/data-provider/src/config.spec.ts@@ -20,6 +20,59 @@ const endpointsConfig: TEndpointsConfig = {Gemini: { type: EModelEndpoint.custom, userProvide: false, order: 9999 },};+describe('scheduled MCP preflight config', () => {+ it('bounds the separate readiness admission pool', () => {+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, admissionConcurrency: 100 } },+ }).success,+ ).toBe(true);+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, admissionConcurrency: 101 } },+ }).success,+ ).toBe(false);+ });++ it('caps per-admission connection concurrency', () => {+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, mcpPreflightConcurrency: 10 } },+ }).success,+ ).toBe(true);+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, mcpPreflightConcurrency: 11 } },+ }).success,+ ).toBe(false);+ });++ it('bounds the aggregate readiness timeout', () => {+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, mcpPreflightTimeoutMs: 600000 } },+ }).success,+ ).toBe(true);+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, mcpPreflightTimeoutMs: 600001 } },+ }).success,+ ).toBe(false);+ expect(+ configSchema.safeParse({+ version: '1.2.1',+ interface: { schedules: { use: true, mcpPreflightTimeoutMs: 999 } },+ }).success,+ ).toBe(false);+ });+});+describe('excludedKeys', () => {it.each(['_id',diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex c860446f08..4a6fa293b7 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -1959,7 +1959,10 @@ export const interfaceSchema = zmaxPerUser: z.number().int().min(0).optional(),minIntervalMinutes: z.number().int().min(1).optional(),autoDisableAfterFailures: z.number().int().min(1).optional(),+ admissionConcurrency: z.number().int().min(1).max(100).optional(),fireConcurrency: z.number().int().min(1).optional(),+ mcpPreflightConcurrency: z.number().int().min(1).max(10).optional(),+ mcpPreflightTimeoutMs: z.number().int().min(1000).max(600000).optional(),/** Refuse schedules that are not filed under a chat project. Enforced on* create/update AND at every fire, so raising it later stops schedules* that predate the policy instead of grandfathering them. */diff --git a/packages/data-provider/src/types/schedules.ts b/packages/data-provider/src/types/schedules.tsindex cc0989fbf2..1575c21e30 100644--- a/packages/data-provider/src/types/schedules.ts+++ b/packages/data-provider/src/types/schedules.ts@@ -15,6 +15,9 @@ export const scheduleTargets = ['new'] as const;export type ScheduleTarget = (typeof scheduleTargets)[number];export type ScheduleDisabledReason =+ | 'mcp_reauth_required'+ | 'mcp_configuration_missing'+ | 'mcp_permission_denied'| 'too_many_failures'| 'agent_deleted'| 'invalid_schedule'@@ -117,6 +120,7 @@ export type TScheduleLastRun = {conversationId?: string;status: ScheduleRunStatus;error?: string;+ mcp?: ScheduleMCPOutcome[];firedAt: string;};@@ -152,6 +156,7 @@ export type TSchedule = {};export type TScheduleRun = {+ mcp?: ScheduleMCPOutcome[];scheduleId: string;scheduledFor: string;firedAt?: string;@@ -187,3 +192,46 @@ export type TScheduleRunNowResponse = {conversationId: string;status: 'started';};++/** Only structured schedule preflight failures may request immediate suspension. */+export function getScheduleMCPDisabledReason(+ outcomes?: ScheduleMCPOutcome[],+): 'mcp_reauth_required' | 'mcp_configuration_missing' | 'mcp_permission_denied' | undefined {+ const statuses = new Set(outcomes?.map((outcome) => outcome.status));+ if (statuses.has('mcp_permission_denied')) return 'mcp_permission_denied';+ if (statuses.has('mcp_configuration_missing')) return 'mcp_configuration_missing';+ if (statuses.has('mcp_reauth_required')) return 'mcp_reauth_required';+ return undefined;+}++export const scheduleMCPOutcomeSchema = z.object({+ server: z.string(),+ /** Agent whose selected tool requires this server. Used to open the correct+ * recovery chat when the requirement belongs to a handoff or subagent. */+ agentId: z.string().optional(),+ status: z.enum([+ 'ready',+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied',+ 'mcp_unavailable',+ ]),+});+export type ScheduleMCPOutcome = z.infer<typeof scheduleMCPOutcomeSchema>;+export type ScheduleMCPStatus = ScheduleMCPOutcome['status'];++export function readScheduleMCPOutcomes(error?: string): ScheduleMCPOutcome[] {+ if (+ !error ||+ !/^mcp_(reauth_required|configuration_missing|permission_denied|unavailable): \[/.test(error)+ )+ return [];+ try {+ const result = scheduleMCPOutcomeSchema+ .array()+ .safeParse(JSON.parse(error.slice(error.indexOf(': ') + 2)));+ return result.success ? result.data : [];+ } catch {+ return [];+ }+}diff --git a/packages/data-schemas/src/methods/agent.spec.ts b/packages/data-schemas/src/methods/agent.spec.tsindex be07f8f2e9..89ec4fd6d7 100644--- a/packages/data-schemas/src/methods/agent.spec.ts+++ b/packages/data-schemas/src/methods/agent.spec.ts@@ -94,12 +94,16 @@ beforeAll(async () => {};const aclEntryMethods = createAclEntryMethods(mongoose);- const { getSoleOwnedResourceIds } = aclEntryMethods;+ const { getSoleOwnedResourceIds, findAccessibleResources } = aclEntryMethods;methods = createAgentMethods(mongoose, {removeAllPermissions,getActions,getSoleOwnedResourceIds,+ getUserPrincipals: async ({ userId }) => [+ { principalType: 'user', principalId: new mongoose.Types.ObjectId(userId) },+ ],+ findAccessibleResources,isExternalSkillId: (id) => externalSkillIds.has(id),});createAgent = methods.createAgent;@@ -560,6 +564,44 @@ describe('Agent Methods', () => {expect(newAgent.mcpServerNames).toEqual(['authorizedServer']);});+ test('loads ACL-visible graph nodes by logical ID without exposing storage IDs', async () => {+ const { agentId, authorId } = createTestIds();+ const visible = await createAgent({+ id: agentId,+ name: 'Visible graph agent',+ provider: 'test',+ model: 'test-model',+ author: authorId,+ tools: [`search${Constants.mcp_delimiter}docs`],+ });+ const privateAgent = await createAgent({+ id: `private-${agentId}`,+ name: 'Private graph agent',+ provider: 'test',+ model: 'test-model',+ author: authorId,+ });+ await AclEntry.create({+ principalType: PrincipalType.USER,+ principalId: authorId,+ principalModel: PrincipalModel.USER,+ resourceType: ResourceType.AGENT,+ resourceId: visible._id,+ permBits: PermissionBits.VIEW,+ grantedBy: authorId,+ });++ const access = await methods.resolveAgentGraphAccess({+ userId: authorId.toString(),+ });+ const nodes = await methods.getAgentGraphNodes([visible.id, privateAgent.id], access);++ expect(nodes).toEqual([+ expect.objectContaining({ id: visible.id, mcpServerNames: ['docs'] }),+ ]);+ expect(nodes[0]).not.toHaveProperty('_id');+ });+describe('MCP server name candidate lookups', () => {test('getAgentsWithMCPServerNames returns only agents with a non-empty list, projected', async () => {const { agentId, authorId } = createTestIds();diff --git a/packages/data-schemas/src/methods/agent.ts b/packages/data-schemas/src/methods/agent.tsindex a11ba807ad..885202e828 100644--- a/packages/data-schemas/src/methods/agent.ts+++ b/packages/data-schemas/src/methods/agent.ts@@ -2,6 +2,7 @@ import crypto from 'node:crypto';import {Constants,EToolResources,+ PermissionBits,ResourceType,SkillsScope,actionDelimiter,@@ -162,10 +163,45 @@ export interface AgentDeps {userObjectId: Types.ObjectId,resourceTypes: string | string[],) => Promise<Types.ObjectId[]>;+ /** Resolves ACL principals. Kept inside data-schemas so callers pass plain identity. */+ getUserPrincipals: (params: {+ userId: string | Types.ObjectId;+ role?: string | null;+ idOnTheSource?: string | null;+ }) => Promise<Array<{ principalType: string; principalId?: string | Types.ObjectId }>>;+ /** Resolves ACL-visible resources. Kept inside data-schemas so callers use logical IDs. */+ findAccessibleResources: (+ principals: Array<{ principalType: string; principalId?: string | Types.ObjectId }>,+ resourceType: string,+ requiredPermissions: number,+ resourceIds?: Types.ObjectId[],+ ) => Promise<Types.ObjectId[]>;/** Recognizes skill IDs supplied by an external, non-database registry. */isExternalSkillId?: (id: string) => boolean;}+/** Plain projection used to discover runnable agent graphs without exposing Mongoose. */+export interface AgentGraphNode {+ id: string;+ provider: string;+ model: string;+ tools?: string[];+ mcpServerNames?: string[];+ agent_ids?: string[];+ edges?: IAgent['edges'];+ subagents?: IAgent['subagents'];+}++export interface AgentGraphAccess {+ userId: string;+ role?: string | null;+ idOnTheSource?: string | null;+}++declare const agentGraphAccessContext: unique symbol;+/** Opaque resolved ACL context. Only data-schemas creates or consumes its contents. */+export type AgentGraphAccessContext = { readonly [agentGraphAccessContext]: true };+/*** Extracts unique MCP server names from tools array.* Tools format: "toolName_mcp_serverName" or "sys__server__sys_mcp_serverName"@@ -527,6 +563,11 @@ export function createAgentMethods(searchParameter: FilterQuery<IAgent>,select?: string | Record<string, number>,) => Promise<IAgent[]>;+ resolveAgentGraphAccess: (access: AgentGraphAccess) => Promise<AgentGraphAccessContext>;+ getAgentGraphNodes: (+ ids: string[],+ access?: AgentGraphAccessContext,+ ) => Promise<AgentGraphNode[]>;createAgent: (agentData: Record<string, unknown>) => Promise<IAgent>;getAgentIdsByMCPServerName: (serverName: string) => Promise<Types.ObjectId[]>;getAgentsWithMCPServerNames: () => Promise<Array<Pick<IAgent, '_id' | 'mcpServerNames'>>>;@@ -743,6 +784,82 @@ export function createAgentMethods(return await Agent.find(searchParameter, select).lean<IAgent[]>();}+ /**+ * Loads a bounded graph frontier by logical agent ID and optionally applies VIEW ACLs.+ * Storage IDs are used only inside this method and never cross the package boundary.+ */+ async function resolveAgentGraphAccess(+ access: AgentGraphAccess,+ ): Promise<AgentGraphAccessContext> {+ return (await deps.getUserPrincipals(access)) as unknown as AgentGraphAccessContext;+ }++ async function getAgentGraphNodes(+ ids: string[],+ access?: AgentGraphAccessContext,+ ): Promise<AgentGraphNode[]> {+ if (ids.length === 0) {+ return [];+ }+ const Agent = mongoose.models.Agent as Model<IAgent>;+ const agents = await Agent.find(+ { id: { $in: ids } },+ {+ _id: 1,+ id: 1,+ provider: 1,+ model: 1,+ tools: 1,+ mcpServerNames: 1,+ agent_ids: 1,+ edges: 1,+ subagents: 1,+ },+ ).lean<+ Array<+ Pick<+ IAgent,+ | '_id'+ | 'id'+ | 'provider'+ | 'model'+ | 'tools'+ | 'mcpServerNames'+ | 'agent_ids'+ | 'edges'+ | 'subagents'+ >+ >+ >();+ let visible = agents;+ if (access != null) {+ const principals = access as unknown as Array<{+ principalType: string;+ principalId?: string | Types.ObjectId;+ }>;+ const resourceIds = await deps.findAccessibleResources(+ principals,+ ResourceType.AGENT,+ PermissionBits.VIEW,+ agents.map((agent) => agent._id),+ );+ const allowed = new Set(resourceIds.map(String));+ visible = agents.filter((agent) => allowed.has(String(agent._id)));+ }+ return visible.map(+ ({ id, provider, model, tools, mcpServerNames, agent_ids, edges, subagents }) => ({+ id,+ provider,+ model,+ tools,+ mcpServerNames,+ agent_ids,+ edges,+ subagents,+ }),+ );+ }+/** Returns the ids of every agent referencing `serverName`, the candidate set* for agent-mediated MCP access checks. Index-covered by `mcpServerNames`. */async function getAgentIdsByMCPServerName(serverName: string): Promise<Types.ObjectId[]> {@@ -1539,6 +1656,8 @@ export function createAgentMethods(getAgentVersions,getAgentWithVersionCount,getAgents,+ resolveAgentGraphAccess,+ getAgentGraphNodes,createAgent,getAgentIdsByMCPServerName,getAgentsWithMCPServerNames,diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.tsindex 1bf484ed40..942e6a7d0c 100644--- a/packages/data-schemas/src/methods/index.ts+++ b/packages/data-schemas/src/methods/index.ts@@ -148,7 +148,14 @@ import type {UpsertSkillSyncCredentialInput,} from './skillSync';/* Tier 5 — Agent */-import { createAgentMethods, type AgentMethods, type AgentDeps } from './agent';+import {+ createAgentMethods,+ type AgentMethods,+ type AgentDeps,+ type AgentGraphNode,+ type AgentGraphAccess,+ type AgentGraphAccessContext,+} from './agent';/* Config */import { createConfigMethods, type ConfigMethods } from './config';import {@@ -422,6 +429,8 @@ export function createMethods(removeAllPermissions,getActions: actionMethods.getActions,getSoleOwnedResourceIds: aclEntryMethods.getSoleOwnedResourceIds,+ getUserPrincipals: userGroupMethods.getUserPrincipals,+ findAccessibleResources: aclEntryMethods.findAccessibleResources,isExternalSkillId: deps.isExternalSkillId,};const agentMethods = createAgentMethods(mongoose, agentDeps);@@ -547,6 +556,9 @@ export type {AgentEventActorReceiptStorageMetrics,ScheduleMethods,AgentMethods,+ AgentGraphNode,+ AgentGraphAccess,+ AgentGraphAccessContext,ConfigMethods,MCPAuthorityMethods,MCPAuthorityMethodHooks,diff --git a/packages/data-schemas/src/methods/schedule.methods.spec.ts b/packages/data-schemas/src/methods/schedule.methods.spec.tsindex 8e46dc0db1..4f3f012637 100644--- a/packages/data-schemas/src/methods/schedule.methods.spec.ts+++ b/packages/data-schemas/src/methods/schedule.methods.spec.ts@@ -523,16 +523,19 @@ describe('recordRunOutcome', () => {it('error increments failureCount without disabling below the threshold', async () => {const schedule = await methods.createSchedule(scheduleData());await methods.insertScheduleRun(runData(schedule, { scheduledFor }));+ const mcp = [{ server: 'Notion', status: 'mcp_unavailable' as const }];await methods.recordRunOutcome({scheduleId: schedule.id,scheduledFor,status: 'error',error: 'provider exploded',+ mcp,autoDisableAfterFailures: 3,});const run = await getRun(schedule.id, scheduledFor);expect(run.status).toBe('error');expect(run.error).toBe('provider exploded');+ expect(run.mcp).toEqual(mcp);const updated = await getSchedule(schedule.id);expect(updated.failureCount).toBe(1);expect(updated.runCount).toBe(0);@@ -872,6 +875,31 @@ describe('countActiveRuns', () => {});});+describe('getCapacityOccupancy', () => {+ it('excludes admission-only failures that never dispatched a generation', async () => {+ const admission = await methods.createSchedule(scheduleData());+ const legacy = await methods.createSchedule(scheduleData());+ const slotted = await methods.createSchedule(scheduleData());+ await methods.reserveStartedRun(+ runData(admission, {+ scheduledFor: new Date('2026-07-20T12:00:00Z'),+ admissionOnly: true,+ }),+ );+ await methods.reserveStartedRun(+ runData(legacy, { scheduledFor: new Date('2026-07-20T13:00:00Z') }),+ );+ await methods.reserveStartedRun(+ runData(slotted, { scheduledFor: new Date('2026-07-20T14:00:00Z'), capacitySlot: 2 }),+ );++ await expect(methods.getCapacityOccupancy()).resolves.toEqual({+ takenSlots: [2],+ unslotted: 1,+ });+ });+});+describe('recordRunOutcome — reconciled completions and no-match guard', () => {const scheduledFor = new Date('2026-07-20T12:00:00Z');@@ -3013,3 +3041,98 @@ describe('erasure sweep rotation and idempotency-key lookup', () => {).rejects.toThrow(/hour/);});});++describe('scheduled MCP failure policy', () => {+ it.each([+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied',+ 'mcp_unavailable',+ ])('records %s and disables immediately only for user action', async (reason) => {+ const schedule = await methods.createSchedule(scheduleData());+ const scheduledFor = new Date('2026-09-09T12:00:00Z');+ await methods.insertScheduleRun(runData(schedule, { scheduledFor }));+ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor,+ status: 'error',+ error: `${reason}: [{"server":"Notion","status":"${reason}"}]`,+ mcp: [{ server: 'Notion', agentId: 'research-agent', status: reason as never }],+ autoDisableAfterFailures: 5,+ });+ const updated = await getSchedule(schedule.id);+ expect(updated.failureCount).toBe(1);+ expect(updated.enabled).toBe(reason === 'mcp_unavailable');+ expect(updated.disabledReason).toBe(reason === 'mcp_unavailable' ? undefined : reason);+ expect(updated.lastRun?.mcp?.[0]).toMatchObject({+ server: 'Notion',+ agentId: 'research-agent',+ status: reason,+ });+ });++ it('does not infer MCP disablement from an ordinary provider error prefix', async () => {+ const schedule = await methods.createSchedule(scheduleData());+ const scheduledFor = new Date('2026-09-09T12:30:00Z');+ await methods.insertScheduleRun(runData(schedule, { scheduledFor }));++ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor,+ status: 'error',+ error: 'mcp_configuration_missing: provider returned this text',+ autoDisableAfterFailures: 5,+ });++ const updated = await getSchedule(schedule.id);+ expect(updated.failureCount).toBe(1);+ expect(updated.enabled).toBe(true);+ expect(updated.disabledReason).toBeUndefined();+ });++ it('uses admission response precedence for mixed MCP failures', async () => {+ const schedule = await methods.createSchedule(scheduleData());+ const scheduledFor = new Date('2026-09-09T12:45:00Z');+ await methods.insertScheduleRun(runData(schedule, { scheduledFor }));++ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor,+ status: 'error',+ error: 'mixed MCP failure',+ mcp: [+ { server: 'OAuth', status: 'mcp_reauth_required' },+ { server: 'Private', status: 'mcp_permission_denied' },+ ],+ autoDisableAfterFailures: 5,+ });++ const updated = await getSchedule(schedule.id);+ expect(updated.enabled).toBe(false);+ expect(updated.disabledReason).toBe('mcp_permission_denied');+ });+});++it('does not apply a late MCP disable after a newer successful occurrence', async () => {+ const schedule = await methods.createSchedule(scheduleData());+ const older = new Date('2026-09-09T12:00:00Z');+ const newer = new Date('2026-09-09T13:00:00Z');+ await methods.insertScheduleRun(+ runData(schedule, { scheduledFor: older, status: 'requires_action' }),+ );+ await methods.insertScheduleRun(runData(schedule, { scheduledFor: newer }));+ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor: newer,+ status: 'success',+ autoDisableAfterFailures: 5,+ });+ await methods.recordRunOutcome({+ scheduleId: schedule.id,+ scheduledFor: older,+ status: 'error',+ error: 'mcp_reauth_required: [{"server":"Notion","status":"mcp_reauth_required"}]',+ autoDisableAfterFailures: 5,+ });+ expect((await getSchedule(schedule.id)).enabled).toBe(true);+});diff --git a/packages/data-schemas/src/methods/schedule.ts b/packages/data-schemas/src/methods/schedule.tsindex 19499281a5..1da3f7c2c7 100644--- a/packages/data-schemas/src/methods/schedule.ts+++ b/packages/data-schemas/src/methods/schedule.ts@@ -1,4 +1,5 @@import { randomUUID } from 'node:crypto';+import { getScheduleMCPDisabledReason } from 'librechat-data-provider';import type { ScheduleRunStatus, ScheduleDisabledReason } from 'librechat-data-provider';import type { Model, Types, AnyBulkWriteOperation } from 'mongoose';import type {@@ -126,6 +127,8 @@ export interface RecordRunOutcomeParams {* recovery replay that reads the row would otherwise project a dead link. */clearConversationId?: boolean;error?: string;+ /** Sanitized per-server MCP readiness outcomes for this occurrence. */+ mcp?: IScheduleRun['mcp'];durationMs?: number;autoDisableAfterFailures: number;/** Consecutive-balance-skip auto-disable threshold; required to settle a run as@@ -279,7 +282,7 @@ export type ScheduleMethods = {setRunFireDetails: (scheduleId: string,scheduledFor: Date,- details: { conversationId: string; droppedFileIds?: string[] },+ details: { conversationId: string; droppedFileIds?: string[]; mcp?: IScheduleRun['mcp'] },) => Promise<void>;countActiveRuns: () => Promise<number>;deleteScheduleRun: (@@ -927,12 +930,13 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Sche}}- /** Capacity-slot occupancy for the allocator: which slots are held by `started`+ /** Capacity-slot occupancy for the allocator: which slots are held by generation* runs, plus how many legacy rows hold no slot (they shrink the effective cap so- * the bound stays conservative during rollout rather than transiently overshooting). */+ * the bound stays conservative during rollout rather than transiently overshooting).+ * Admission-only rows never dispatched and are excluded even if settlement crashed. */async function getCapacityOccupancy(): Promise<{ takenSlots: number[]; unslotted: number }> {const rows = await ScheduleRun()- .find({ status: 'started' })+ .find({ status: 'started', admissionOnly: { $ne: true } }).select('capacitySlot').lean<Array<{ capacitySlot?: number }>>();const takenSlots: number[] = [];@@ -1179,6 +1183,7 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): ScheconversationId: params.conversationId,status: params.status,error: params.error,+ mcp: params.mcp,firedAt: params.firedAt,};const isFailure = params.status === 'error';@@ -1254,17 +1259,22 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Sche// reconciler's replay still disables. Reads current state after the count.if (isFailure) {const schedule = await Schedule().findOne({ id: params.scheduleId }).lean<ISchedule>();- if (schedule?.enabled && schedule.failureCount >= params.autoDisableAfterFailures) {+ const mcpReason = getScheduleMCPDisabledReason(params.mcp);+ const threshold = mcpReason ? 1 : params.autoDisableAfterFailures;+ if (schedule?.enabled && schedule.failureCount >= threshold) {// Carry the COUNT this decision was made on, not just the revision. The read// above and this write are separate statements, and a concurrent success resets// the failure streak to zero — a revision-only fence would still let this stale// decision disable a schedule whose streak had just been cleared.await disableSchedule(params.scheduleId,- 'too_many_failures',+ mcpReason ?? 'too_many_failures',undefined,params.expectConfigRevision,- { failureCount: { $gte: params.autoDisableAfterFailures } },+ {+ failureCount: { $gte: threshold },+ ...(mcpReason ? { countersAsOf: params.scheduledFor } : {}),+ },);}}@@ -1469,12 +1479,17 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Sche? { conversationId: params.conversationId }: {}),...(params.error ? { error: params.error } : {}),+ ...(params.mcp ? { mcp: params.mcp } : {}),...(params.durationMs != null ? { durationMs: params.durationMs } : {}),},// SETTLEMENT: a terminal outcome is the generation owner confirming the run// actually stopped, so this is the ONLY place the global capacity slot is// released. An abort request alone does not free it (see requestRunAbort).- $unset: { capacitySlot: 1, ...(params.clearConversationId ? { conversationId: 1 } : {}) },+ $unset: {+ capacitySlot: 1,+ admissionOnly: 1,+ ...(params.clearConversationId ? { conversationId: 1 } : {}),+ },},{ new: false },)@@ -1579,13 +1594,14 @@ export function createScheduleMethods(mongoose: typeof import('mongoose')): Scheasync function setRunFireDetails(scheduleId: string,scheduledFor: Date,- details: { conversationId: string; droppedFileIds?: string[] },+ details: { conversationId: string; droppedFileIds?: string[]; mcp?: IScheduleRun['mcp'] },): Promise<void> {await ScheduleRun().updateOne({ scheduleId, scheduledFor },{$set: {conversationId: details.conversationId,+ ...(details.mcp ? { mcp: details.mcp } : {}),...(details.droppedFileIds?.length ? { droppedFileIds: details.droppedFileIds } : {}),},},diff --git a/packages/data-schemas/src/schema/schedule.ts b/packages/data-schemas/src/schema/schedule.tsindex 75235cb5a9..0990cad5b9 100644--- a/packages/data-schemas/src/schema/schedule.ts+++ b/packages/data-schemas/src/schema/schedule.ts@@ -115,6 +115,9 @@ const scheduleSchema: Schema<IScheduleDocument> = new Schema(disabledReason: {type: String,enum: [+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied','too_many_failures','agent_deleted','invalid_schedule',@@ -223,6 +226,27 @@ const scheduleSchema: Schema<IScheduleDocument> = new Schema(conversationId: { type: String },status: { type: String, required: true },error: { type: String },+ mcp: {+ type: [+ {+ _id: false,+ server: { type: String, required: true },+ agentId: { type: String },+ status: {+ type: String,+ required: true,+ enum: [+ 'ready',+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied',+ 'mcp_unavailable',+ ],+ },+ },+ ],+ default: undefined,+ },firedAt: { type: Date, required: true },scheduledFor: { type: Date },},diff --git a/packages/data-schemas/src/schema/scheduleRun.ts b/packages/data-schemas/src/schema/scheduleRun.tsindex 18ad668e7f..b51a105a60 100644--- a/packages/data-schemas/src/schema/scheduleRun.ts+++ b/packages/data-schemas/src/schema/scheduleRun.ts@@ -65,6 +65,27 @@ const scheduleRunSchema: Schema<IScheduleRunDocument> = new Schema(type: String,maxlength: 2048,},+ mcp: {+ type: [+ {+ _id: false,+ server: { type: String, required: true },+ agentId: { type: String },+ status: {+ type: String,+ required: true,+ enum: [+ 'ready',+ 'mcp_reauth_required',+ 'mcp_configuration_missing',+ 'mcp_permission_denied',+ 'mcp_unavailable',+ ],+ },+ },+ ],+ default: undefined,+ },droppedFileIds: {type: [String],default: undefined,@@ -88,6 +109,11 @@ const scheduleRunSchema: Schema<IScheduleRunDocument> = new Schema(type: Number,min: 0,},+ /** Marks a transient started row that exists only to settle an admission failure.+ * It never owns generation capacity, including if settlement must be reconciled. */+ admissionOnly: {+ type: Boolean,+ },/** When an abort was requested. The run keeps holding its capacity slot until the* generation owner confirms settlement, so capacity is never freed early. */abortRequestedAt: {diff --git a/packages/data-schemas/src/types/schedule.ts b/packages/data-schemas/src/types/schedule.tsindex 69c06a6173..52be372a35 100644--- a/packages/data-schemas/src/types/schedule.ts+++ b/packages/data-schemas/src/types/schedule.ts@@ -3,6 +3,7 @@ import type {ScheduleDisabledReason,TScheduleCadence,} from 'librechat-data-provider';+import type { ScheduleMCPOutcome } from 'librechat-data-provider';import type { Document, Types } from 'mongoose';export interface ISchedule {@@ -57,6 +58,7 @@ export interface ISchedule {conversationId?: string;status: ScheduleRunStatus;error?: string;+ mcp?: ScheduleMCPOutcome[];firedAt: Date;/** The OCCURRENCE this projection came from; orders the card against delayed* outcomes (a resumed pause, a reconciler replay) arriving after a newer run. */@@ -77,6 +79,7 @@ export interface IScheduleDocument extends Omit<ISchedule, 'id' | '_id'>, Docume}export interface IScheduleRun {+ mcp?: ScheduleMCPOutcome[];_id?: Types.ObjectId;scheduleId: string;user: Types.ObjectId;@@ -108,6 +111,9 @@ export interface IScheduleRun {settledAt?: Date;/** Global concurrency slot held while `started`. */capacitySlot?: number;+ /** A started row used only to durably settle admission failure bookkeeping. It+ * never dispatched generation work and therefore does not consume capacity. */+ admissionOnly?: boolean;/** When an abort was requested; capacity is held until settlement is confirmed. */abortRequestedAt?: Date;/** Who requested the abort: the interactive Stop route ('stop', which persists a