diff --git a/api/server/controllers/agents/__tests__/resume.spec.js b/api/server/controllers/agents/__tests__/resume.spec.js index 884585c1e7..625714dbcb 100644 --- a/api/server/controllers/agents/__tests__/resume.spec.js +++ b/api/server/controllers/agents/__tests__/resume.spec.js @@ -1399,6 +1399,8 @@ describe('ResumeAgentController (POST /agents/chat/resume)', () => { source: { type: 'schedule', id: 'schedule-1', manual: false, resumed: true }, unattended: false, }); + // The owner's validated decisions, not the request body, name what may now run. + expect(mockInitializeClient.mock.calls[0][0].approvedToolCalls).toEqual(['tc1']); expect(mockClaimScheduleResume).toHaveBeenCalledWith('schedule-1', scheduledFor, { expectedConfigRevision: 4, diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index 5bcee0ea42..36c4689dce 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -28,6 +28,7 @@ const { recordCollectedUsage, resolveRunUsageContext, getScheduleMCPExecution, + scheduleAsksEveryUse, createScheduledMCPPolicyRecorder, recordFallbackTokenUsage, getAgentPromptTokenEstimate, @@ -70,6 +71,7 @@ const { collectAttachedCodeApprovalPolicies, collectAttachedCodeRoutePolicies, buildAttachedCodeEnvironmentAdmissionHooks, + buildScheduledApprovalAdmissionHooks, resolveAttachedCodeApprovalMode, resolvePersistedCodeApprovalMode, getCodeApprovalPreservedFields, @@ -4462,6 +4464,7 @@ class AgentClient extends BaseClient { appConfig, }, pluginHookSource: getPluginHookSource(), + asksEveryUse: scheduleAsksEveryUse(this.options.req), }, ) : interrupt.payload; @@ -4609,9 +4612,11 @@ class AgentClient extends BaseClient { collectAttachedCodeApprovalPolicies(topLevelAgents), agentsEConfig?.toolApproval?.enabled !== false, ); + const scheduledMCPExecution = getScheduleMCPExecution(getMCPRequestContext(this.options.req)); const effectiveToolApprovalPolicy = resolveToolApprovalPolicy({ endpoint: agentsEConfig?.toolApproval, attachedCodeEnvironment: attachedCodeEnvironmentAgentIds.size > 0, + ownerApproval: scheduledMCPExecution?.mayAsk === true, }); const resolvedToolApprovalHooks = isHITLEnabled(effectiveToolApprovalPolicy) ? buildToolApprovalHooks({ @@ -4629,6 +4634,7 @@ class AgentClient extends BaseClient { codeApprovalMode, collectAttachedCodeRoutePolicies(topLevelAgents), ), + ...buildScheduledApprovalAdmissionHooks(scheduledMCPExecution), ]; const askUserQuestionAdminDisabled = isAskUserQuestionAdminDisabled(appConfig); const runCanPause = canAgentGraphPause({ diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.js index 430e54c057..803dc57133 100644 --- a/api/server/controllers/agents/resume.js +++ b/api/server/controllers/agents/resume.js @@ -53,6 +53,8 @@ const { PROJECT_CONTEXT_CHANGED_REASON, PROJECT_CONTEXT_CHANGED_RESPONSE, restoreExecutionContext, + collectApprovedToolCalls, + scheduleAsksEveryUse, recoverTurnMessageReference, applyForcedRetention, applyForcedTemporaryRequest, @@ -1955,6 +1957,7 @@ const ResumeAgentController = async (req, res, next, initializeClient, addTitle) const result = await initializeClient({ executionContext: restoreExecutionContext(req, job.metadata), scheduleJobIdentity: job.metadata, + approvedToolCalls: collectApprovedToolCalls(mapped.resumeValue), req, res, endpointOption: req.body.endpointOption, @@ -2040,6 +2043,7 @@ const ResumeAgentController = async (req, res, next, initializeClient, addTitle) appConfig: req.config, }, pluginHookSource: getPluginHookSource(), + asksEveryUse: scheduleAsksEveryUse(req), request: req, addConvoToolApprovalAllows, }); diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js index 45360b8832..a013efb10d 100644 --- a/api/server/services/Endpoints/agents/initialize.js +++ b/api/server/services/Endpoints/agents/initialize.js @@ -2172,6 +2172,7 @@ function createInitializeClient(dependencies = {}) { ), executionContext: params.executionContext, restoredJob: params.scheduleJobIdentity, + approvedToolCalls: params.approvedToolCalls, }, () => require('~/server/services/Schedules/consent'), () => diff --git a/api/server/services/Endpoints/agents/initialize.spec.js b/api/server/services/Endpoints/agents/initialize.spec.js index e51435ac87..fb6dff18b1 100644 --- a/api/server/services/Endpoints/agents/initialize.spec.js +++ b/api/server/services/Endpoints/agents/initialize.spec.js @@ -449,6 +449,26 @@ describe('initializeClient — processAgent ACL gate', () => { } }); + it('hands the approved tool calls of a resumed request to scheduled preparation', async () => { + const req = makeReq(); + req._isScheduledFire = true; + const host = require('~/server/services/Schedules/consent'); + const prepare = jest.spyOn(host, 'prepare').mockResolvedValue(undefined); + mockInitializeAgent.mockImplementationOnce(async () => makePrimaryConfig([])); + try { + await initializeClient({ + req, + res: {}, + endpointOption: makeEndpointOption(), + signal: new AbortController().signal, + approvedToolCalls: ['tc1'], + }); + expect(prepare).toHaveBeenCalledWith(expect.objectContaining({ approvedToolCalls: ['tc1'] })); + } finally { + prepare.mockRestore(); + } + }); + it('preserves the owning cancellation before scheduled preparation begins', async () => { const req = makeReq(); req._isScheduledFire = true; diff --git a/api/server/services/Schedules/consent.js b/api/server/services/Schedules/consent.js index a0c573f118..a48bc6d330 100644 --- a/api/server/services/Schedules/consent.js +++ b/api/server/services/Schedules/consent.js @@ -1,4 +1,9 @@ -const { createScheduleMCPRuntimeHost } = require('@librechat/api'); +const { + getAgentCheckpointer, + GenerationJobManager, + createScheduledPauseCheck, + createScheduleMCPRuntimeHost, +} = require('@librechat/api'); const { getMCPServersRegistry } = require('~/config'); const { getAppConfig } = require('~/server/services/Config/app'); const { getModelsConfig } = require('~/server/controllers/ModelController'); @@ -11,6 +16,11 @@ module.exports = createScheduleMCPRuntimeHost({ findUser: (id) => methods.findUser({ _id: id }), getRoleByName: methods.getRoleByName, canViewAgent: async (agentId, user) => (await resolveAgentFireAccess(agentId, user)) === 'ok', + canPauseRuns: createScheduledPauseCheck({ + isSharedStore: () => GenerationJobManager.isRedis, + getCheckpointer: getAgentCheckpointer, + getAppConfig, + }), enrollment: { canUseRoot: async (agentId, user) => (await resolveAgentFireAccess(agentId, user)) === 'ok', findUser: (id) => methods.findUser({ _id: id }), diff --git a/client/src/components/Chat/Messages/Content/ToolApproval.tsx b/client/src/components/Chat/Messages/Content/ToolApproval.tsx index 0309be42cb..3fc09cfdf1 100644 --- a/client/src/components/Chat/Messages/Content/ToolApproval.tsx +++ b/client/src/components/Chat/Messages/Content/ToolApproval.tsx @@ -1,5 +1,6 @@ import { useId, useContext, useEffect, useMemo } from 'react'; import { Button, TextareaAutosize } from '@librechat/client'; +import { SCHEDULE_APPROVAL_REASON } from 'librechat-data-provider'; import { useComposerPresentsApproval, useOptionalChatSurface } from '@librechat/chat/react'; import { X, @@ -84,6 +85,11 @@ function seedArgs(args: string | Record | undefined): string { } } +/** Explanations the server sends as a code, said here in the reader's language. */ +const descriptionKeys = new Map([ + [SCHEDULE_APPROVAL_REASON, 'com_ui_approval_schedule_owner'], +]); + /** * Renders approve / reject / edit / respond controls for a paused tool call, * scoped to the decisions the server allows. Records its decision in the @@ -174,8 +180,10 @@ export default function ToolApproval({ const status = getStatus(actionId); const locked = status === 'submitting' || status === 'submitted' || status === 'expired'; - const safeDescription = - description == null ? undefined : boundApprovalLabel(description, 1024).label; + const descriptionKey = description == null ? undefined : descriptionKeys.get(description); + let safeDescription: string | undefined; + if (descriptionKey != null) safeDescription = localize(descriptionKey); + else if (description != null) safeDescription = boundApprovalLabel(description, 1024).label; /** Recompute and store this card's decision whenever inputs change. A null * resolution (e.g. invalid edit JSON) clears it so submit stays disabled. */ diff --git a/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx index b9091a8c2a..50abc694ea 100644 --- a/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx +++ b/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx @@ -1,6 +1,7 @@ import React from 'react'; import { RecoilRoot } from 'recoil'; import { Provider, createStore } from 'jotai'; +import { SCHEDULE_APPROVAL_REASON } from 'librechat-data-provider'; import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react'; import { approvalPanelOpenFamily, @@ -78,6 +79,27 @@ function DecisionProbe() { const decisions = () => JSON.parse(screen.getByTestId('decisions').textContent ?? '[]'); describe('ToolApproval', () => { + test("says a coded explanation in the reader's language and shows any other as sent", () => { + renderCards( + , + ); + expect(screen.getByText('com_ui_approval_schedule_owner')).toBeInTheDocument(); + expect(screen.queryByText(SCHEDULE_APPROVAL_REASON)).not.toBeInTheDocument(); + cleanup(); + renderCards( + , + ); + expect(screen.getByText('Deletes a file')).toBeInTheDocument(); + }); + test('hides Always allow unless the server offered it', () => { renderCards(); expect(screen.queryByRole('button', { name: 'Always allow' })).not.toBeInTheDocument(); diff --git a/client/src/components/SidePanel/Schedules/Consent.tsx b/client/src/components/SidePanel/Schedules/Consent.tsx index 01abb1dc66..2aa497ec10 100644 --- a/client/src/components/SidePanel/Schedules/Consent.tsx +++ b/client/src/components/SidePanel/Schedules/Consent.tsx @@ -119,12 +119,44 @@ export default function Consent({ const choosing = canConfirm && data?.offer != null; const choice = data ? currentChoice(data, edited) : {}; const chosenCount = Object.values(choice).reduce((count, tools) => count + tools.length, 0); + /** Null until the owner changes an "ask me first" box, with the grant it was changed against. */ + const [editedAsking, setEditedAsking] = useState<{ + revision: string | null; + tools: Record; + } | null>(null); + const canAsk = data?.approval === true; + /** + * Kept apart from the ticks. Starts from the stored grant, even where a run cannot pause + * and for a tool that is not ticked right now: one that changed starts unticked, and + * ticking it again must not turn a tool the owner approves each time into an unattended one. + * The owner's edits hold only for the grant they were made against: a question added to a + * grant confirmed elsewhere is not theirs to drop unseen. + */ + const asking = + (editedAsking?.revision === data?.revision ? editedAsking?.tools : undefined) ?? + data?.asking ?? + {}; + const noteId = useId(); const setTools = (serverName: string, tools: string[]) => setEdited({ choice: { ...choice, [serverName]: tools }, revision: data?.revision ?? null, changed: data?.changed ?? {}, }); + const setAsking = (serverName: string, tools: string[]) => + setEditedAsking({ + revision: data?.revision ?? null, + tools: { ...asking, [serverName]: tools }, + }); + /** Sent with the confirmation: of the tools ticked now, the ones the owner asks about. */ + const ask = Object.fromEntries( + Object.entries(asking) + .map(([serverName, tools]): [string, string[]] => [ + serverName, + tools.filter((tool) => (choice[serverName] ?? []).includes(tool)), + ]) + .filter(([, tools]) => tools.length > 0), + ); const commit = () => { if (!data?.offer || chosenCount === 0) return; setMessage(null); @@ -134,10 +166,13 @@ export default function Consent({ expectedRevision: data.revision, lifetimeHours: hours, allow: choice, + // Always sent: left out, the server keeps what the stored grant asks about. + ask, }, { onSuccess: () => { setEdited(null); + setEditedAsking(null); setMessage('success'); }, onError: () => setMessage('error'), @@ -194,6 +229,11 @@ export default function Consent({ })}

)} + {choosing && !canAsk && Object.keys(ask).length > 0 && ( +

+ {localize('com_ui_schedule_consent_ask_unavailable')} +

+ )}
    {data.targets.map((target) => (
  • @@ -229,8 +269,16 @@ export default function Consent({ offered={offeredTools(target)} chosen={choice[target.resource.serverName] ?? []} changed={data.changed[target.resource.serverName] ?? []} + asking={asking[target.resource.serverName] ?? []} + askable={ + canAsk + ? offeredTools(target) + : (data.asking[target.resource.serverName] ?? []) + } + askNoteId={canAsk ? undefined : noteId} disabled={busy} onChange={(tools) => setTools(target.resource.serverName, tools)} + onAskingChange={(tools) => setAsking(target.resource.serverName, tools)} /> ) : ( <> @@ -239,6 +287,13 @@ export default function Consent({ tools: (data.allowed[target.resource.serverName] ?? []).join(', '), })}

    + {(data.asking[target.resource.serverName] ?? []).length > 0 && ( +

    + {localize('com_ui_schedule_consent_asking', { + tools: data.asking[target.resource.serverName].join(', '), + })} +

    + )} {(data.changed[target.resource.serverName] ?? []).length > 0 && (

    {localize('com_ui_schedule_consent_changed_tools', { @@ -307,16 +362,30 @@ function ToolChoice({ offered, chosen, changed, + asking, + askable, + askNoteId, disabled, onChange, + onAskingChange, }: { serverName: string; offered: string[]; chosen: string[]; /** Tools the server changed since they were allowed. Refused until confirmed again. */ changed: string[]; + /** Allowed tools the owner approves call by call. */ + asking: string[]; + /** + * Tools that get an "ask me first" box. Where a scheduled run cannot pause, only the ones + * the stored grant already asks about, so the owner can keep or drop them but add none. + */ + askable: string[]; + /** The note explaining that a run cannot pause here, when it is shown. */ + askNoteId?: string; disabled: boolean; onChange: (tools: string[]) => void; + onAskingChange: (tools: string[]) => void; }) { const localize = useLocalize(); const groupId = useId(); @@ -361,6 +430,27 @@ function ToolChoice({ > {tool} + {askable.includes(tool) && chosen.includes(tool) && ( + + + onAskingChange( + checked === true + ? [...asking, tool] + : asking.filter((name) => name !== tool), + ) + } + /> + + + )} {changed.includes(tool) && (

    diff --git a/client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx b/client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx index 2704333da2..d7f9e1af63 100644 --- a/client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx +++ b/client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx @@ -46,6 +46,8 @@ const view: ScheduleMCPConsentView = { ], allowed: {}, changed: {}, + asking: {}, + approval: false, required: false, requireAfterMs: null, offer: { digest: 'a'.repeat(64), maxLifetimeHours: 24 }, @@ -103,6 +105,7 @@ it('confirms the offer reference, lifetime and only the tools the owner ticked, expectedRevision: null, lifetimeHours: 1, allow: { warehouse: ['query'] }, + ask: {}, }), ); expect(await screen.findByText('com_ui_schedule_consent_active')).toBeVisible(); @@ -308,6 +311,188 @@ it('tells the owner the schedule is refused MCP tools until they confirm', async expect(await screen.findByText('com_ui_schedule_consent_required')).toBeVisible(); expect(screen.queryByText('com_ui_schedule_consent_required_after')).not.toBeInTheDocument(); }); +it('offers no way to ask first where a scheduled run cannot pause', async () => { + display(); + await userEvent.click(await screen.findByRole('checkbox', { name: 'query' })); + expect( + screen.queryByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' }), + ).not.toBeInTheDocument(); +}); +it('lets the owner ask first for an allowed tool, and sends only those', async () => { + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ ...view, approval: true }); + jest.mocked(dataService.confirmScheduleMCPConsent).mockResolvedValue(view); + display(); + // Nothing to ask about until a tool is allowed. + await screen.findByRole('checkbox', { name: 'query' }); + expect(screen.queryAllByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' })).toEqual( + [], + ); + await userEvent.click(screen.getByRole('checkbox', { name: 'query' })); + await userEvent.click(screen.getByRole('checkbox', { name: 'export' })); + const boxes = screen.getAllByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' }); + expect(boxes).toHaveLength(2); + // Tools are listed in order: export, then query. + await userEvent.click(boxes[0]); + await userEvent.click(boxes[1]); + // Disallowing a tool drops its question with it. + await userEvent.click(screen.getByRole('checkbox', { name: 'export' })); + await userEvent.click(screen.getByRole('button', { name: 'com_ui_schedule_consent_confirm' })); + await waitFor(() => + expect(dataService.confirmScheduleMCPConsent).toHaveBeenCalledWith( + 'schedule', + expect.objectContaining({ allow: { warehouse: ['query'] }, ask: { warehouse: ['query'] } }), + ), + ); +}); +it('starts from what the stored grant asks about, and sends no question once cleared', async () => { + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ + ...view, + state: 'active', + revision: 'grant', + expiresAtMs: Date.now() + 60_000, + approval: true, + allowed: { warehouse: ['export', 'query'] }, + asking: { warehouse: ['query'] }, + }); + jest.mocked(dataService.confirmScheduleMCPConsent).mockResolvedValue(view); + display(); + await screen.findByRole('checkbox', { name: 'query' }); + const [exportAsk, queryAsk] = screen.getAllByRole('checkbox', { + name: 'com_ui_schedule_consent_ask_tool', + }); + expect(exportAsk).not.toBeChecked(); + expect(queryAsk).toBeChecked(); + await userEvent.click(queryAsk); + await userEvent.click(screen.getByRole('button', { name: 'com_ui_schedule_consent_confirm' })); + await waitFor(() => expect(dataService.confirmScheduleMCPConsent).toHaveBeenCalled()); + // Sent empty, not left out: the server keeps the stored questions when told nothing. + expect(jest.mocked(dataService.confirmScheduleMCPConsent).mock.calls[0][1]).toMatchObject({ + ask: {}, + }); +}); +it('keeps a changed tool asking first when the owner allows its new definition', async () => { + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ + ...view, + state: 'changed', + revision: 'grant', + expiresAtMs: Date.now() + 60_000, + approval: true, + allowed: { warehouse: ['export', 'query'] }, + asking: { warehouse: ['query'] }, + changed: { warehouse: ['query'] }, + }); + jest.mocked(dataService.confirmScheduleMCPConsent).mockResolvedValue(view); + display(); + // Changed, so it starts unticked, and an unticked tool shows no question. + const query = await screen.findByRole('checkbox', { name: 'query' }); + expect(query).not.toBeChecked(); + expect( + screen.getAllByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' }), + ).toHaveLength(1); + await userEvent.click(query); + // Allowed again, it still asks: accepting the new definition is not dropping the question. + const [, queryAsk] = screen.getAllByRole('checkbox', { + name: 'com_ui_schedule_consent_ask_tool', + }); + expect(queryAsk).toBeChecked(); + await userEvent.click(screen.getByRole('button', { name: 'com_ui_schedule_consent_confirm' })); + await waitFor(() => + expect(dataService.confirmScheduleMCPConsent).toHaveBeenCalledWith( + 'schedule', + expect.objectContaining({ + allow: { warehouse: ['export', 'query'] }, + ask: { warehouse: ['query'] }, + }), + ), + ); +}); +it('takes up a question added to a grant confirmed elsewhere, over an earlier edit of its own', async () => { + const granted = { + ...view, + state: 'active' as const, + revision: 'grant-1', + expiresAtMs: Date.now() + 60_000, + approval: true, + allowed: { warehouse: ['export', 'query'] }, + asking: { warehouse: ['query'] }, + }; + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue(granted); + jest.mocked(dataService.confirmScheduleMCPConsent).mockResolvedValue(view); + const client = display(); + await screen.findByRole('checkbox', { name: 'query' }); + const asks = () => screen.getAllByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' }); + // The owner clears the question on `query` here, then the grant is replaced in another tab + // by one that also asks about `export`. + await userEvent.click(asks()[1]); + expect(asks()[1]).not.toBeChecked(); + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ + ...granted, + revision: 'grant-2', + asking: { warehouse: ['export', 'query'] }, + offer: { digest: 'e'.repeat(64), maxLifetimeHours: 24 }, + }); + await client.invalidateQueries(); + await waitFor(() => expect(asks()[0]).toBeChecked()); + expect(asks()[1]).toBeChecked(); + await userEvent.click(screen.getByRole('button', { name: 'com_ui_schedule_consent_confirm' })); + await waitFor(() => + expect(dataService.confirmScheduleMCPConsent).toHaveBeenCalledWith( + 'schedule', + expect.objectContaining({ + expectedRevision: 'grant-2', + ask: { warehouse: ['export', 'query'] }, + }), + ), + ); +}); +it('keeps what the stored grant asks about where a run cannot pause, and offers no new question', async () => { + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ + ...view, + state: 'active', + revision: 'grant', + expiresAtMs: Date.now() + 60_000, + approval: false, + allowed: { warehouse: ['export', 'query'] }, + asking: { warehouse: ['query'] }, + }); + jest.mocked(dataService.confirmScheduleMCPConsent).mockResolvedValue(view); + display(); + await screen.findByRole('checkbox', { name: 'query' }); + // Only the stored question has a box, and it says why the tool is refused for now. + const stored = screen.getByRole('checkbox', { + name: 'com_ui_schedule_consent_ask_tool', + description: 'com_ui_schedule_consent_ask_unavailable', + }); + expect(stored).toBeChecked(); + expect(screen.getAllByRole('checkbox', { name: 'com_ui_schedule_consent_ask_tool' })).toEqual([ + stored, + ]); + await userEvent.click(screen.getByRole('button', { name: 'com_ui_schedule_consent_confirm' })); + await waitFor(() => + expect(dataService.confirmScheduleMCPConsent).toHaveBeenCalledWith( + 'schedule', + expect.objectContaining({ + allow: { warehouse: ['export', 'query'] }, + ask: { warehouse: ['query'] }, + }), + ), + ); + // Dropping it is the owner's to choose; the note goes with the last question. + await userEvent.click(stored); + expect(screen.queryByText('com_ui_schedule_consent_ask_unavailable')).not.toBeInTheDocument(); +}); +it('names the tools a stored grant asks about when there is nothing to confirm', async () => { + jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ + ...view, + state: 'revoked', + revision: 'revoked', + allowed: { warehouse: ['query'] }, + asking: { warehouse: ['query'] }, + offer: null, + }); + display(); + expect(await screen.findByText('com_ui_schedule_consent_asking')).toBeVisible(); +}); it('lists the allowed tools without boxes when there is nothing to confirm', async () => { jest.mocked(dataService.getScheduleMCPConsent).mockResolvedValue({ ...view, diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json index ac37f79656..c9d188b558 100644 --- a/client/src/locales/en/translation.json +++ b/client/src/locales/en/translation.json @@ -1471,6 +1471,7 @@ "com_ui_api_keys_load_error": "Failed to load API keys", "com_ui_approval_error": "Something went wrong submitting your decision. Please try again.", "com_ui_approval_expired": "This request expired or was already handled.", + "com_ui_approval_schedule_owner": "You asked to approve each use of this tool when this schedule runs.", "com_ui_approval_review_in_composer": "Review this request in the panel above the message box.", "com_ui_approve": "Approve", "com_ui_approve_always": "Always allow", @@ -3902,7 +3903,7 @@ "com_nav_mobile_drawer_strip": "Show chat beside the sidebar on mobile", "com_nav_mobile_drawer_strip_info": "The sidebar stops short of the edge so a strip of the conversation stays visible. Tapping it closes the sidebar.", "com_ui_schedule_consent_title": "Scheduled MCP authorization", - "com_ui_schedule_consent_boundary": "Choose which servers and tools this schedule may use while you are away, until the fixed deadline. Anything left unchecked is refused. This does not reconnect a provider or enable the schedule.", + "com_ui_schedule_consent_boundary": "Choose which servers and tools this schedule may use while you are away, until the fixed deadline. Anything left unchecked is refused. A tool set to ask me first pauses the run until you approve that use. This does not reconnect a provider or enable the schedule.", "com_ui_schedule_consent_missing": "Authorization required", "com_ui_schedule_consent_required": "This schedule's MCP tools are refused until you confirm.", "com_ui_schedule_consent_required_after": "Without authorization, this schedule's MCP tools stop working on {{time}}.", @@ -3923,6 +3924,10 @@ "com_ui_schedule_consent_allow_server": "Allow all tools on {{server}}", "com_ui_schedule_consent_allowed": "Allowed tools: {{tools}}", "com_ui_schedule_consent_none_selected": "Choose at least one tool to confirm.", + "com_ui_schedule_consent_ask_first": "Ask me first", + "com_ui_schedule_consent_ask_tool": "Ask me before each use of {{tool}}", + "com_ui_schedule_consent_asking": "Asks you before each use: {{tools}}", + "com_ui_schedule_consent_ask_unavailable": "Scheduled runs cannot pause for your approval here right now. A tool set to ask me first is refused until they can. Clear its box to let it run without asking.", "com_ui_schedule_consent_tool_changed": "Changed since you allowed it. Check it to allow the new version.", "com_ui_schedule_consent_changed_tools": "Changed since allowed, now refused: {{tools}}", "com_ui_code_checkout_mode": "Checkout mode", diff --git a/packages/api/src/agents/hitl/allow.spec.ts b/packages/api/src/agents/hitl/allow.spec.ts index 9f2de3278a..e53ed40ce8 100644 --- a/packages/api/src/agents/hitl/allow.spec.ts +++ b/packages/api/src/agents/hitl/allow.spec.ts @@ -131,6 +131,20 @@ describe('markToolApprovalAllowAlways', () => { expect(markToolApprovalAllowAlways(payload, { policy, agents: [{}], aliases })).toBe(payload); }); + it('does not offer the choice for a tool something else asks about on every use', () => { + const payload = payloadFor(GITHUB_SEARCH, GITLAB_SEARCH); + const asksEveryUse = jest.fn((names: readonly string[]) => + names.includes('legacy_search_mcp_github'), + ); + const marked = markToolApprovalAllowAlways(payload, { + policy: enabled(), + aliases: [{ name: GITHUB_SEARCH, aliasName: 'legacy_search_mcp_github' }], + asksEveryUse, + }); + // Asked by its other spelling: the tool is matched under every name the run knows it by. + expect(marked.review_configs.map((config) => config.allow_always)).toEqual([undefined, true]); + }); + it('stops offering new tools once the configured cap is reached', () => { const payload = payloadFor(GITHUB_SEARCH, GITLAB_SEARCH, GITHUB_SEARCH); const policy = enabled({ allowAlwaysMaxTools: 2 }); @@ -294,6 +308,29 @@ describe('recordToolApprovalAllows', () => { expect(request.resolvedConversation.toolApprovalAllows).toEqual(['other_tool', GITHUB_SEARCH]); }); + it('approves once a tool that is asked about on every use by the time of the resume', async () => { + const addConvoToolApprovalAllows = jest.fn().mockResolvedValue(true); + const input = { + userId: 'u1', + conversationId: 'c1', + policy: enabled(), + pendingAction: { payload: offered }, + resolutions, + request: {}, + addConvoToolApprovalAllows, + }; + expect( + await recordToolApprovalAllows({ + ...input, + asksEveryUse: (names) => names.includes(GITHUB_SEARCH), + }), + ).toEqual([]); + expect(addConvoToolApprovalAllows).not.toHaveBeenCalled(); + expect(await recordToolApprovalAllows({ ...input, asksEveryUse: () => false })).toEqual([ + GITHUB_SEARCH, + ]); + }); + it('passes the configured cap to storage and rechecks against healed rules', async () => { const addConvoToolApprovalAllows = jest.fn().mockResolvedValue(true); await recordToolApprovalAllows({ diff --git a/packages/api/src/agents/hitl/allow.ts b/packages/api/src/agents/hitl/allow.ts index 1547b01ebe..d726027ef3 100644 --- a/packages/api/src/agents/hitl/allow.ts +++ b/packages/api/src/agents/hitl/allow.ts @@ -160,6 +160,11 @@ export interface MarkToolApprovalAllowAlwaysOptions { hookContext?: ToolApprovalHookContext; /** Deployment plugin hooks the run registers after the policy hooks. */ pluginHookSource?: PluginHookSource; + /** + * Whether something beyond the policy and its hooks asks about any of these spellings on + * every use, such as a schedule whose owner approves the tool call by call. + */ + asksEveryUse?: (toolNames: readonly string[]) => boolean; } /** @@ -178,6 +183,7 @@ export function markToolApprovalAllowAlways( storedTools = [], hookContext = {}, pluginHookSource, + asksEveryUse, }: MarkToolApprovalAllowAlwaysOptions, ): Agents.ToolApprovalInterruptPayload { if (!isToolAllowAlwaysEnabled(policy)) { @@ -198,8 +204,14 @@ export function markToolApprovalAllowAlways( const name = nameByToolCallId.get(config.tool_call_id); if ( !config.allowed_decisions.includes('approve') || - !isToolAllowAlwaysGroupEligible(effective, name, aliases) || - toolApprovalHookCanApply(getEquivalentToolNames(name, aliases), hookContext, pluginHookSource) + !isToolAllowAlwaysGroupEligible(effective, name, aliases) + ) { + return config; + } + const spellings = getEquivalentToolNames(name, aliases); + if ( + toolApprovalHookCanApply(spellings, hookContext, pluginHookSource) || + asksEveryUse?.(spellings) === true ) { return config; } @@ -369,6 +381,8 @@ export interface RecordToolApprovalAllowsInput { hookContext?: ToolApprovalHookContext; /** Deployment plugin hooks the rebuilt run registers after the policy hooks. */ pluginHookSource?: PluginHookSource; + /** As on the offer: something beyond the policy asks about the tool on every use. */ + asksEveryUse?: (toolNames: readonly string[]) => boolean; /** Request-scoped conversation reused by the resumed run's initialization. */ request: { resolvedConversation?: { conversationId?: string; toolApprovalAllows?: unknown } | null; @@ -398,6 +412,7 @@ export async function recordToolApprovalAllows({ agents, hookContext = {}, pluginHookSource, + asksEveryUse, request, addConvoToolApprovalAllows, }: RecordToolApprovalAllowsInput): Promise { @@ -416,17 +431,16 @@ export async function recordToolApprovalAllows({ buildEffectiveToolApprovalPolicy(policy, aliases), aliases, ); - const toolNames = eligible.filter( - (name) => - !toolApprovalHookCanApply( - getEquivalentToolNames(name, aliases), - hookContext, - pluginHookSource, - ), - ); + const toolNames = eligible.filter((name) => { + const spellings = getEquivalentToolNames(name, aliases); + return ( + !toolApprovalHookCanApply(spellings, hookContext, pluginHookSource) && + asksEveryUse?.(spellings) !== true + ); + }); if (toolNames.length < eligible.length) { logger.info( - '[recordToolApprovalAllows] An approval hook now applies to a remembered tool; approved once', + '[recordToolApprovalAllows] A remembered tool is still asked about on each use; approved once', ); } if (toolNames.length === 0) { diff --git a/packages/api/src/agents/hitl/policy.spec.ts b/packages/api/src/agents/hitl/policy.spec.ts index b0122218fc..b12578d70c 100644 --- a/packages/api/src/agents/hitl/policy.spec.ts +++ b/packages/api/src/agents/hitl/policy.spec.ts @@ -92,6 +92,26 @@ describe('resolveToolApprovalPolicy', () => { }); }); + test('lets a grant whose owner approves tools call by call pause a run on its own', () => { + expect(resolveToolApprovalPolicy({ ownerApproval: true })).toEqual({ + enabled: true, + mode: 'bypass', + }); + expect(resolveToolApprovalPolicy({ endpoint: { deny: ['rm'] }, ownerApproval: true })).toEqual({ + enabled: true, + mode: 'bypass', + deny: ['rm'], + }); + expect(resolveToolApprovalPolicy({ ownerApproval: false })).toBeUndefined(); + }); + + test('keeps the administrator in charge of a run whose owner approves tools', () => { + const off: TToolApprovalPolicy = { enabled: false }; + expect(resolveToolApprovalPolicy({ endpoint: off, ownerApproval: true })).toBe(off); + const on: TToolApprovalPolicy = { enabled: true, mode: 'default' }; + expect(resolveToolApprovalPolicy({ endpoint: on, ownerApproval: true })).toBe(on); + }); + test.each(['default', 'dontAsk', 'bypass'] as const)( 'preserves an enabled endpoint %s policy when BYOM is active', (mode) => { diff --git a/packages/api/src/agents/hitl/policy.ts b/packages/api/src/agents/hitl/policy.ts index 9114c1dfa3..29bf2f4894 100644 --- a/packages/api/src/agents/hitl/policy.ts +++ b/packages/api/src/agents/hitl/policy.ts @@ -42,6 +42,12 @@ export interface ToolApprovalPolicyLayers { * an administrator to opt the whole endpoint into prompts. */ attachedCodeEnvironment?: boolean; + /** + * The run acts under a grant whose owner approves some tools call by call (a scheduled + * chat). The owner's choice pauses the run without an administrator opting the whole + * endpoint into prompts; a hook supplies the decisions. + */ + ownerApproval?: boolean; } /** @@ -64,7 +70,7 @@ export function resolveToolApprovalPolicy( layers: ToolApprovalPolicyLayers, ): TToolApprovalPolicy | undefined { if ( - layers.attachedCodeEnvironment === true && + (layers.attachedCodeEnvironment === true || layers.ownerApproval === true) && layers.endpoint?.enabled !== true && layers.endpoint?.enabled !== false ) { diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts index aadb3159ae..aeecc4b836 100644 --- a/packages/api/src/agents/run.ts +++ b/packages/api/src/agents/run.ts @@ -2971,6 +2971,7 @@ export async function createRun({ const toolApprovalPolicy = resolveToolApprovalPolicy({ endpoint: agentsEndpointConfig?.toolApproval, attachedCodeEnvironment: attachedCodeEnvironmentAgentIds.size > 0, + ownerApproval: scheduledMCPExecution?.mayAsk === true, }); // Every caller needs the policy hooks, including API-key ingresses. Only // AgentClient supports pause/resume; the SDK blocks `ask` without HITL enabled. diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.ts index 1923817da4..3b040a9d8d 100644 --- a/packages/api/src/mcp/MCPManager.ts +++ b/packages/api/src/mcp/MCPManager.ts @@ -60,6 +60,7 @@ import { type MCPAppBindingSubject, type MCPAppRuntimeTarget, } from './apps/binding'; +import { assertToolApprovalTransportEpoch, getToolApprovalTransportCallId } from '~/tools/approval'; import { getMCPAppToolsPublicationGeneration, getMCPToolsChangedGeneration } from './toolsChanged'; import { mcpOptionsContainGraphTokenPlaceholder, preProcessGraphTokens } from '~/utils/graph'; import { resolveDirectOpenIDBearerConfig, usesDirectOpenIDBearerRecovery } from './openid'; @@ -70,7 +71,6 @@ import { formatToolContent, selectResolvedAppResource } from './parsers'; import { MCPServersInitializer } from './registry/MCPServersInitializer'; import { OboTokenResolutionError, resolveOboToken } from '~/mcp/oauth'; import { MCPServerCatalogRecoveryTracker } from './catalog/recovery'; -import { assertToolApprovalTransportEpoch } from '~/tools/approval'; import { getToolUiResourceUri, isToolHiddenFromApp } from './apps'; import { MCPServerInspector } from './registry/MCPServerInspector'; import { MCPServersRegistry } from './registry/MCPServersRegistry'; @@ -2021,6 +2021,7 @@ Please follow these instructions when using tools from the respective MCP server toolName, loadTools: () => connection!.fetchToolsSnapshot(undefined, options?.signal), signal: options?.signal, + toolCallId: getToolApprovalTransportCallId(), }); options?.signal?.throwIfAborted(); await assertToolApprovalTransportEpoch( diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.ts index 2e4968839c..e7e7f12262 100644 --- a/packages/api/src/mcp/__tests__/MCPManager.test.ts +++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts @@ -936,8 +936,11 @@ describe('MCPManager', () => { }); describe('callTool - scheduled authority boundary', () => { - async function setupScheduled(stage: 'invoke' | 'resume' = 'invoke') { - const fixture = await executionFixture(stage); + async function setupScheduled( + stage: 'invoke' | 'resume' = 'invoke', + choice?: Parameters[3], + ) { + const fixture = await executionFixture(stage, undefined, undefined, choice); const request = jest.fn().mockResolvedValue({ content: [{ type: 'text', text: 'read' }] }); const snapshot = jest.fn().mockResolvedValue({ tools: [readTool], complete: true }); const connection = { @@ -1017,6 +1020,26 @@ describe('MCPManager', () => { expect(request.mock.calls.filter(([input]) => input.method === 'tools/call')).toHaveLength(1); }); + it('dispatches a tool the owner approves call by call only for the approved call', async () => { + const { request, call } = await setupScheduled('resume', { + ask: ['query'], + approvedToolCalls: ['approved-call'], + }); + const within = (id: string) => + withToolApprovalExecution({ validateExecution: async () => {} }, () => + withToolApprovalTransport({ toolCall: { id }, metadata: { agentId: 'root' } }, () => + call(), + ), + ); + const refused = { failure: { reason: 'approval_required', automaticReplay: false } }; + await expect(within('other-call')).rejects.toMatchObject(refused); + // No approval session at all: nothing could have asked the owner. + await expect(call()).rejects.toMatchObject(refused); + expect(request).not.toHaveBeenCalled(); + await within('approved-call'); + expect(request.mock.calls.filter(([input]) => input.method === 'tools/call')).toHaveLength(1); + }); + it('fences consent revoked during live tools/list immediately before dispatch', async () => { const { fixture, request, snapshot, call } = await setupScheduled(); snapshot.mockImplementation(async () => { diff --git a/packages/api/src/schedules/README.md b/packages/api/src/schedules/README.md index 2e7ec6713c..a883dc6748 100644 --- a/packages/api/src/schedules/README.md +++ b/packages/api/src/schedules/README.md @@ -69,6 +69,29 @@ agent still selects it. Anything else is refused with `tool_policy_denied`. The operator-declared `mcpConsent.readOnlyPolicy` list is retired. The loader warns when the key is still present and ignores it. +### A tool the owner approves call by call + +Beside allowing a tool, the owner can set it to "ask me first". The grant stores those tools +(`askTools`), always a subset of the allowed ones. + +- **In a run**, the schedule's `PreToolUse` hook answers `ask` for such a tool. The run pauses + like any tool approval: the schedule shows "Needs approval" and links to the conversation, + where the owner approves, edits or rejects that use. +- **At the MCP call**, `ScheduledMCPInvocation.authorize` refuses the tool with + `approval_required` unless the call's id is one the owner approved in the request that + resumed the run. A hook that times out contributes nothing, so this check, not the hook, + is what keeps an unapproved call from running. +- **Approvals do not carry over.** They come from the validated decisions of one resume + request and name tool calls, not tools. The next use asks again. +- **The readiness check** calls nothing and is not asked. + +A paused scheduled run needs a shared generation store (Redis streams) and a durable +checkpointer, and `endpoints.agents.toolApproval.enabled` must not be `false`. Where that +holds, a grant that asks turns the approval machinery on for its runs in `bypass` mode, so no +other tool starts prompting. Where it does not, the consent view reports `approval: false`, +the dialog offers no "ask me first", and confirming with `ask` is rejected: a tool nobody can +approve would only ever be refused. + ### A schedule its owner never authorized A schedule with no grant keeps using its MCP tools unrestricted, as it did before consent diff --git a/packages/api/src/schedules/authorization/approval.integration.spec.ts b/packages/api/src/schedules/authorization/approval.integration.spec.ts new file mode 100644 index 0000000000..4c8648b0ff --- /dev/null +++ b/packages/api/src/schedules/authorization/approval.integration.spec.ts @@ -0,0 +1,233 @@ +import { z } from 'zod'; +import { MemorySaver } from '@langchain/langgraph'; +import { SCHEDULE_APPROVAL_REASON } from 'librechat-data-provider'; +import { HumanMessage } from '@librechat/agents/langchain/messages'; +import { Run, Providers, HookRegistry, FakeChatModel } from '@librechat/agents'; +import type { TToolApprovalPolicy } from 'librechat-data-provider'; +import type { ToolApprovalDecisionMap } from '@librechat/agents'; +import type { ScheduleMCPExecution } from './execution'; +import { createAgentToolApprovalSession, bindRunToolApprovalSession } from '~/agents/hitl/modes'; +import { buildHITLRunWiring, buildToolApprovalExecutionConfig } from '~/agents/hitl/runtime'; +import { getToolApprovalTransportCallId } from '~/tools/approval'; +import { resolveToolApprovalPolicy } from '~/agents/hitl/policy'; +import { executionFixture, readTool } from './execution.helper'; +import { createToolExecuteHandler } from '~/agents/handlers'; +import { collectApprovedToolCalls } from './execution'; +import { createMCPStructuredTool } from '~/mcp/tools'; +import { createScheduledMCPRunPolicy } from './run'; +import { formatToolContent } from '~/mcp/parsers'; + +/** + * A real SDK run with a scripted model, the real approval session, the real schedule hook and + * the real consent service. The tool body stands in for `MCPManager.callTool`: it asks the + * schedule's authority with the call id the approval layer holds, then counts as dispatched. + */ +const name = 'query_mcp_warehouse'; +const schema = z.object({ text: z.string() }); +const chat = 'scheduled-chat'; +const config = { + configurable: { + thread_id: chat, + user_id: 'owner', + ...buildToolApprovalExecutionConfig(`response-${chat}`, 1), + }, + streamMode: 'values' as const, + version: 'v2' as const, +}; + +async function scenario(choice: Parameters[3] = { ask: ['query'] }) { + const fixture = await executionFixture('invoke', readTool, undefined, choice); + const saver = new MemorySaver(); + const dispatched: string[] = []; + const refusals: unknown[] = []; + + async function build({ + execution = fixture.execution, + endpoint, + scheduleHook = true, + callId = 'call-1', + }: { + execution?: ScheduleMCPExecution; + endpoint?: TToolApprovalPolicy; + /** False stands for a hook the SDK discarded: it timed out, so it said nothing. */ + scheduleHook?: boolean; + callId?: string; + } = {}) { + const tool = Object.assign( + createMCPStructuredTool( + async (input) => { + const { text } = schema.parse(input); + try { + await execution.bind('root', 'query').authorize({ + user: fixture.user, + serverName: 'warehouse', + serverConfig: fixture.config, + toolName: 'query', + loadTools: async () => ({ tools: [readTool], complete: true }), + toolCallId: getToolApprovalTransportCallId(), + }); + } catch (error) { + refusals.push(error); + throw error; + } + dispatched.push(text); + return formatToolContent({ content: [{ type: 'text' as const, text }] }, 'openai'); + }, + { + name, + description: 'Scripted scheduled MCP tool', + schema, + responseFormat: 'content_and_artifact', + }, + ), + { schema }, + ); + const agent = { + id: 'root', + toolDefinitions: [{ name, toolType: 'mcp', serverName: 'warehouse' }], + }; + const session = createAgentToolApprovalSession({ agents: [{ id: 'root' }] }); + // As `createRun` does: the schedule's grant may turn approval on for this run. + const wiring = buildHITLRunWiring( + resolveToolApprovalPolicy({ endpoint, ownerApproval: execution.mayAsk }), + {}, + [], + [{ hook: session.hook }], + ); + const policy = createScheduledMCPRunPolicy(execution, [agent]); + // Also as `createRun` does: with no approval wiring the schedule hook gets its own registry. + const hooks = wiring?.hooks ?? new HookRegistry(); + if (scheduleHook) hooks.register('PreToolUse', { hooks: [policy.hook, policy.receipt] }); + const llmConfig = { + provider: Providers.OPENAI, + model: 'gpt-4o-mini', + apiKey: 'test-placeholder', + streaming: true, + streamUsage: false, + }; + const run = await Run.create({ + runId: `run-${chat}`, + graphConfig: { + type: 'standard', + llmConfig, + agents: [ + { + agentId: 'root', + provider: Providers.OPENAI, + endpoint: Providers.OPENAI, + clientOptions: llmConfig, + instructions: 'Use the scripted tool.', + tools: [tool], + }, + ], + compileOptions: { checkpointer: saver }, + }, + returnContent: true, + customHandlers: { + on_tool_execute: createToolExecuteHandler({ + loadTools: async () => ({ loadedTools: [tool] }), + }), + }, + tokenCounter: (text) => String(text ?? '').length, + indexTokenCountMap: {}, + ...(wiring && { humanInTheLoop: wiring.humanInTheLoop }), + hooks, + }); + if (!run.Graph) throw new Error('The test run did not initialize its graph.'); + run.Graph.overrideModel = new FakeChatModel({ + responses: ['Done.'], + toolCalls: [{ name, args: { text: 'hello' }, id: callId, type: 'tool_call' }], + }); + if (wiring) bindRunToolApprovalSession(run, session); + return run; + } + + /** What the resume controller does with the owner's validated decisions. */ + const resumedExecution = async (decisions: ToolApprovalDecisionMap) => + (await fixture.factory.resolve(fixture.identity, 'resume', { + approvedToolCalls: collectApprovedToolCalls(decisions), + }))!; + + return { fixture, build, resumedExecution, dispatched, refusals }; +} +const start = { messages: [new HumanMessage('run')] }; + +it('pauses a scheduled run before a tool its owner approves call by call', async () => { + const s = await scenario(); + const run = await s.build(); + await run.processStream(start, config); + const interrupt = run.getInterrupt(); + expect(interrupt?.payload).toMatchObject({ + type: 'tool_approval', + action_requests: [{ tool_call_id: 'call-1', name, description: SCHEDULE_APPROVAL_REASON }], + }); + expect(s.dispatched).toEqual([]); + expect(s.refusals).toEqual([]); +}); + +it('runs the call once the owner approves it on resume', async () => { + const s = await scenario(); + await (await s.build()).processStream(start, config); + const decisions: ToolApprovalDecisionMap = { 'call-1': { type: 'approve' } }; + const resumed = await s.build({ execution: await s.resumedExecution(decisions) }); + await resumed.resume(decisions, config); + expect(resumed.getInterrupt()).toBeUndefined(); + expect(s.dispatched).toEqual(['hello']); + expect(s.refusals).toEqual([]); +}); + +it('does not run the call the owner rejects', async () => { + const s = await scenario(); + await (await s.build()).processStream(start, config); + const decisions: ToolApprovalDecisionMap = { 'call-1': { type: 'reject', reason: 'not today' } }; + const resumed = await s.build({ execution: await s.resumedExecution(decisions) }); + await resumed.resume(decisions, config); + expect(s.dispatched).toEqual([]); +}); + +it('refuses the call at the tool when the hook that should have paused the run said nothing', async () => { + const s = await scenario(); + const run = await s.build({ scheduleHook: false }); + await run.processStream(start, config); + expect(run.getInterrupt()).toBeUndefined(); + expect(s.dispatched).toEqual([]); + expect(s.refusals).toHaveLength(1); + expect(s.refusals[0]).toMatchObject({ failure: { reason: 'approval_required' } }); +}); + +it('refuses a resumed call the owner approved under a different call id', async () => { + const s = await scenario(); + await (await s.build()).processStream(start, config); + const resumed = await s.build({ + execution: await s.resumedExecution({ 'call-9': { type: 'approve' } }), + }); + await resumed.resume({ 'call-1': { type: 'approve' } }, config); + expect(s.dispatched).toEqual([]); + expect(s.refusals[0]).toMatchObject({ failure: { reason: 'approval_required' } }); +}); + +it('blocks the tool without pausing where the administrator turned approval off', async () => { + const s = await scenario(); + const run = await s.build({ endpoint: { enabled: false } }); + await run.processStream(start, config); + expect(run.getInterrupt()).toBeUndefined(); + // The SDK blocks an `ask` nobody can answer before the tool is reached. + expect(s.dispatched).toEqual([]); + expect(s.refusals).toEqual([]); +}); + +it('still refuses at the tool there if the hook said nothing', async () => { + const s = await scenario(); + const run = await s.build({ endpoint: { enabled: false }, scheduleHook: false }); + await run.processStream(start, config); + expect(s.dispatched).toEqual([]); + expect(s.refusals[0]).toMatchObject({ failure: { reason: 'approval_required' } }); +}); + +it('neither pauses nor refuses a tool the owner simply allowed', async () => { + const s = await scenario({}); + const run = await s.build(); + await run.processStream(start, config); + expect(run.getInterrupt()).toBeUndefined(); + expect(s.dispatched).toEqual(['hello']); +}); diff --git a/packages/api/src/schedules/authorization/contract.ts b/packages/api/src/schedules/authorization/contract.ts index d5f893bb39..87efd630cc 100644 --- a/packages/api/src/schedules/authorization/contract.ts +++ b/packages/api/src/schedules/authorization/contract.ts @@ -51,6 +51,8 @@ export type ScheduledMCPAuthorizationResult = readonly consentRevision: string; readonly policyRevision: string; readonly validUntilMs: number; + /** The owner approves each use of this tool. The caller must hold that approval. */ + readonly approvalRequired?: true; } | { readonly state: 'denied'; readonly failure: ScheduledMCPFailure } | { readonly state: 'cancelled' }; diff --git a/packages/api/src/schedules/authorization/execution.helper.ts b/packages/api/src/schedules/authorization/execution.helper.ts index 1b5a181da2..0960c8c43c 100644 --- a/packages/api/src/schedules/authorization/execution.helper.ts +++ b/packages/api/src/schedules/authorization/execution.helper.ts @@ -94,8 +94,17 @@ export async function executionFixture( stage: 'activation' | 'invoke' | 'resume' = 'invoke', tool: Tool = readTool, url = 'https://resource.example/mcp', - /** `offered` adds tools the agents select; `allow` is what the owner picks (default: `tool`). */ - choice: { offered?: string[]; allow?: string[] } = {}, + /** + * `offered` adds tools the agents select; `allow` is what the owner picks (default: `tool`); + * `ask` are the allowed tools the owner approves call by call; `approvedToolCalls` are the + * calls the owner approved in the request that resumed the run. + */ + choice: { + offered?: string[]; + allow?: string[]; + ask?: string[]; + approvedToolCalls?: string[]; + } = {}, ) { let time = 1000; let allowed = true; @@ -168,6 +177,7 @@ export async function executionFixture( resolveEnrollment, getLimits: async () => ({ enabled: true, maxLifetimeHours: 24 }), canUse: async () => allowed, + canPause: async () => true, now: () => time, }); const offer = await service.view(identity); @@ -176,10 +186,13 @@ export async function executionFixture( expectedRevision: null, lifetimeHours: 1, allow: { warehouse: choice.allow ?? [tool.name] }, + ...(choice.ask && { ask: { warehouse: choice.ask } }), }); const loadAuthorization = jest.fn(async () => ({ authority: service.authority })); const factory = createScheduleMCPExecution({ storage, loadAuthorization }); - const execution = (await factory.resolve(identity, stage))!; + const execution = (await factory.resolve(identity, stage, { + approvedToolCalls: choice.approvedToolCalls, + }))!; return { identity, config, diff --git a/packages/api/src/schedules/authorization/execution.spec.ts b/packages/api/src/schedules/authorization/execution.spec.ts index 2a031288c9..e7ba5e4374 100644 --- a/packages/api/src/schedules/authorization/execution.spec.ts +++ b/packages/api/src/schedules/authorization/execution.spec.ts @@ -1,6 +1,12 @@ import { Constants } from '@librechat/agents'; +import { SCHEDULE_APPROVAL_REASON } from 'librechat-data-provider'; import type { Tool } from '@modelcontextprotocol/sdk/types.js'; -import { bindScheduledMCPInvocation, narrowScheduledMCPTools } from './execution'; +import { + scheduleAsksEveryUse, + narrowScheduledMCPTools, + collectApprovedToolCalls, + bindScheduledMCPInvocation, +} from './execution'; import { createScheduledMCPRunPolicy, SCHEDULE_TOOL_NOT_ALLOWED } from './run'; import { createMCPRequestContext, getMCPRequestContext } from '~/mcp/request'; import { executionFixture, readTool } from './execution.helper'; @@ -541,3 +547,125 @@ describe('the tools a run loads under a grant', () => { expect(narrowScheduledMCPTools({}, 'root', keys)).toBe(keys); }); }); + +describe('a tool the owner approves call by call', () => { + const use = ( + fixture: Awaited>, + extra: { toolCallId?: string; readiness?: true } = {}, + agentId = 'root', + ) => + fixture.invocation(agentId).authorize({ + user: fixture.user, + serverName: 'warehouse', + serverConfig: fixture.config, + toolName: 'query', + loadTools: async () => catalog(), + ...extra, + }); + const refused = { failure: { reason: 'approval_required', automaticReplay: false } }; + + it('is refused when the call carries no approval, whatever the run hook did', async () => { + const fixture = await executionFixture('invoke', readTool, undefined, { ask: ['query'] }); + await expect(use(fixture)).rejects.toMatchObject(refused); + await expect(use(fixture, { toolCallId: 'call-1' })).rejects.toMatchObject(refused); + }); + + it('tells an approval card that the tool is asked about on every use', async () => { + const fixture = await executionFixture('invoke', readTool, undefined, { + offered: ['export'], + allow: ['export', 'query'], + ask: ['query'], + }); + const req = {}; + const asks = scheduleAsksEveryUse(req); + // Built before the grant is attached, as on a resume, and false for any other request. + expect(asks(['query_mcp_warehouse'])).toBe(false); + await fixture.factory.attach(getMCPRequestContext(req)!, fixture.identity, 'invoke'); + expect(asks(['query_mcp_warehouse'])).toBe(true); + expect(asks(['other_name', 'query_mcp_warehouse'])).toBe(true); + expect(asks(['export_mcp_warehouse'])).toBe(false); + expect(scheduleAsksEveryUse(undefined)(['query_mcp_warehouse'])).toBe(false); + }); + + it('runs the call the owner approved, and only that call', async () => { + const fixture = await executionFixture('resume', readTool, undefined, { + ask: ['query'], + approvedToolCalls: ['call-1'], + }); + await expect(use(fixture, { toolCallId: 'call-1' })).resolves.toBeUndefined(); + await expect(use(fixture, { toolCallId: 'call-1' }, 'child')).resolves.toBeUndefined(); + await expect(use(fixture, { toolCallId: 'call-2' })).rejects.toMatchObject(refused); + await expect(use(fixture)).rejects.toMatchObject(refused); + }); + + it('passes a readiness check, which calls nothing', async () => { + const fixture = await executionFixture('activation', readTool, undefined, { ask: ['query'] }); + await expect(use(fixture, { readiness: true })).resolves.toBeUndefined(); + }); + + it('leaves a tool the owner simply allowed alone', async () => { + const fixture = await executionFixture('invoke', readTool, undefined, { + offered: ['list'], + allow: ['list', 'query'], + ask: ['list'], + }); + await expect(use(fixture)).resolves.toBeUndefined(); + }); + + it('tells the run which tools to pause for, by either spelling of the server', async () => { + const fixture = await executionFixture('invoke', readTool, undefined, { + offered: ['list'], + allow: ['list', 'query'], + ask: ['query'], + }); + expect(fixture.execution.mayAsk).toBe(true); + expect(fixture.execution.asksAbout('root', 'query_mcp_warehouse')).toBe(true); + expect(fixture.execution.asksAbout('child', 'query_mcp_warehouse')).toBe(true); + expect(fixture.execution.asksAbout('root', 'list_mcp_warehouse')).toBe(false); + expect(fixture.execution.asksAbout('other', 'query_mcp_warehouse')).toBe(false); + expect((await executionFixture()).execution.mayAsk).toBe(false); + }); + + it('pauses the run for it and for nothing else', async () => { + const fixture = await executionFixture('invoke', readTool, undefined, { + offered: ['list'], + allow: ['list', 'query'], + ask: ['query'], + }); + const agent = { + id: 'root', + toolDefinitions: ['query', 'list', 'write'].map((name) => ({ + name: `${name}_mcp_warehouse`, + toolType: 'mcp', + serverName: 'warehouse', + })), + }; + const policy = createScheduledMCPRunPolicy(fixture.execution, [agent]); + const decide = (toolName: string, executingAgentId = 'root') => + policy.hook( + { toolName, toolInput: {}, executingAgentId } as Parameters[0], + new AbortController().signal, + ); + expect(await decide('query_mcp_warehouse')).toEqual({ + decision: 'ask', + reason: SCHEDULE_APPROVAL_REASON, + }); + expect(await decide('list_mcp_warehouse')).toEqual({}); + expect(await decide('execute_code')).toMatchObject({ decision: 'deny' }); + }); +}); + +it('reads approvals only from a validated resume value', () => { + expect( + collectApprovedToolCalls({ + a: { type: 'approve' }, + b: { type: 'edit', updatedInput: {} }, + c: { type: 'reject' }, + d: { type: 'respond', responseText: 'no' }, + e: null, + f: 'approve', + }), + ).toEqual(['a', 'b']); + for (const value of [undefined, null, 'approve', [{ type: 'approve' }], { answers: {} }]) + expect(collectApprovedToolCalls(value)).toEqual([]); +}); diff --git a/packages/api/src/schedules/authorization/execution.ts b/packages/api/src/schedules/authorization/execution.ts index 3b56b45753..a80a947102 100644 --- a/packages/api/src/schedules/authorization/execution.ts +++ b/packages/api/src/schedules/authorization/execution.ts @@ -10,6 +10,7 @@ import type { ScheduleMCPConsentStorage } from '@librechat/data-schemas'; import type { ScheduledMCPIdentity } from 'librechat-data-provider'; import type { Tool } from '@modelcontextprotocol/sdk/types.js'; import type { ParsedServerConfig, RequestScopedMCPConnectionStore } from '~/mcp/types'; +import type { ResolvedToolApprovalHook } from '~/agents/hitl/hooks'; import type { MCPToolsSnapshot } from '~/mcp/connection'; import type { ScheduledMCPAuthority } from './contract'; import type { ScheduledTokenContext } from '../context'; @@ -33,6 +34,10 @@ export interface ScheduledMCPInvocation { toolName: string; loadTools: () => Promise; signal?: AbortSignal; + /** The call being made, as the approval layer knows it. Absent when nothing can approve. */ + toolCallId?: string; + /** A readiness check, which calls nothing. Anything else must hold the owner's approval. */ + readiness?: true; }) => Promise; } @@ -54,6 +59,12 @@ export interface ScheduleMCPExecution { * tools the grant lists for the agent. A run that has no grant keeps them all. */ readonly narrow: (agentId: string, toolKeys: readonly string[]) => string[]; + /** Whether the grant asks the owner about any tool, so this run may pause. */ + readonly mayAsk: boolean; + /** Whether the owner approves each use of this tool, by the name the run calls it. */ + readonly asksAbout: (agentId: string, toolKey: string) => boolean; + /** Whether the owner approves each use of any of these names, whichever agent calls it. */ + readonly asksAboutAny: (toolKeys: readonly string[]) => boolean; readonly bind: (agentId: string | undefined, selectionName: string) => ScheduledMCPInvocation; } @@ -82,6 +93,21 @@ export function narrowScheduledMCPTools( return (context && executions.get(context)?.narrow(agentId, toolKeys)) ?? toolKeys; } +/** + * For "Always allow" on an approval card. A tool the schedule's owner approves on each use + * is asked about again at its next use whatever the conversation remembers, so it is neither + * offered nor stored. Reads the grant when asked: on a resume it is attached after this is + * built. False for a request that runs no schedule. + */ +export function scheduleAsksEveryUse( + req: object | undefined, +): (toolNames: readonly string[]) => boolean { + return (toolNames) => { + const context = findMCPRequestContext(req); + return (context && executions.get(context)?.asksAboutAny(toolNames)) ?? false; + }; +} + export function getScheduleMCPExecution( context?: RequestScopedMCPConnectionStore, ): ScheduleMCPExecution | undefined { @@ -98,24 +124,31 @@ export interface ScheduleMCPExecutionDeps { requiresGrant?: (identity: ScheduledMCPIdentity) => Promise; } +export interface ScheduleMCPExecutionOptions { + manual?: boolean; + legacy?: boolean; + /** Tool calls the owner approved in the request that resumed this run. */ + approvedToolCalls?: readonly string[]; +} + export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { resolve: ( identity: ScheduledMCPIdentity, stage: ScheduleMCPExecution['stage'], - options?: { manual?: boolean; legacy?: boolean }, + options?: ScheduleMCPExecutionOptions, ) => Promise; attach: ( context: RequestScopedMCPConnectionStore, identity: ScheduledMCPIdentity, stage: ScheduleMCPExecution['stage'], requireEnrollment?: boolean, - options?: { manual?: boolean; legacy?: boolean }, + options?: ScheduleMCPExecutionOptions, ) => Promise; } { async function resolve( identity: ScheduledMCPIdentity, stage: ScheduleMCPExecution['stage'], - options: { manual?: boolean; legacy?: boolean } = {}, + options: ScheduleMCPExecutionOptions = {}, ): Promise { const snapshot = await deps.storage.readScheduleMCPConsent(identity); if (snapshot?.compatible === false) throw new ScheduledMCPPolicyError('binding_mismatch', ''); @@ -154,6 +187,21 @@ export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { if (!tools || selectionName === Constants.mcp_all) return false; return selectionName === Constants.mcp_server ? tools.size > 0 : tools.has(selectionName); }; + const approved = new Set(options.approvedToolCalls ?? []); + /** Every spelling a run may call an ask tool by, per agent. A miss is refused, not run. */ + const asking = new Map>(); + for (const consent of snapshot.enrollment?.consents ?? []) { + const { serverName } = consent.resource; + for (const { agentId, tools } of consent.permittedTools) { + const keys = asking.get(agentId) ?? new Set(); + for (const tool of tools) { + if (!consent.askTools?.includes(tool)) continue; + keys.add(`${tool}${Constants.mcp_delimiter}${serverName}`); + keys.add(`${tool}${Constants.mcp_delimiter}${normalizeServerName(serverName)}`); + } + if (keys.size > 0) asking.set(agentId, keys); + } + } let fenced = false; /** Asked at the first MCP call, so a run that uses none pays nothing. Kept for the run. */ let required: Promise | undefined; @@ -198,6 +246,10 @@ export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { (key) => !key.includes(Constants.mcp_delimiter) || isGrantedKey(agentId, key), ) : [...toolKeys], + mayAsk: asking.size > 0, + asksAbout: (agentId: string, toolKey: string) => asking.get(agentId)?.has(toolKey) === true, + asksAboutAny: (toolKeys: readonly string[]) => + toolKeys.some((key) => [...asking.values()].some((keys) => keys.has(key))), bind(agentId: string | undefined, selectionName: string): ScheduledMCPInvocation { return Object.freeze({ identity: capturedIdentity, @@ -210,6 +262,8 @@ export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { toolName, loadTools, signal, + toolCallId, + readiness, }: Parameters[0]): Promise { signal?.throwIfAborted(); const deny = ( @@ -284,6 +338,14 @@ export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { signal?.throwIfAborted(); deny('dependency_unavailable'); } + // The pause is a hook, and a hook that times out says nothing. This is the gate. + if ( + authorization.state === 'authorized' && + authorization.approvalRequired && + readiness !== true && + !(toolCallId != null && approved.has(toolCallId)) + ) + deny('approval_required'); signal?.throwIfAborted(); } catch (error) { if ( @@ -310,6 +372,31 @@ export function createScheduleMCPExecution(deps: ScheduleMCPExecutionDeps): { }; } +/** + * Tells run admission that this schedule's grant can pause the run, so the requirements of + * a paused scheduled run are checked before any provider work. Never asked for a decision. + */ +export function buildScheduledApprovalAdmissionHooks( + execution?: Pick, +): ResolvedToolApprovalHook[] { + return execution?.mayAsk === true ? [{ hook: async () => ({}) }] : []; +} + +/** The tool calls the owner let through, as proposed or edited, in a validated resume value. */ +export function collectApprovedToolCalls(resumeValue: unknown): string[] { + if (resumeValue == null || typeof resumeValue !== 'object' || Array.isArray(resumeValue)) + return []; + return Object.entries(resumeValue) + .filter( + ([, decision]) => + decision != null && + typeof decision === 'object' && + 'type' in decision && + (decision.type === 'approve' || decision.type === 'edit'), + ) + .map(([toolCallId]) => toolCallId); +} + /** The trusted trigger/resume host owns the context. No body-provided schedule opt-in. */ export function scheduledMCPIdentity(context: ScheduledTokenContext): ScheduledMCPIdentity { return { diff --git a/packages/api/src/schedules/authorization/host.spec.ts b/packages/api/src/schedules/authorization/host.spec.ts new file mode 100644 index 0000000000..50cc117e63 --- /dev/null +++ b/packages/api/src/schedules/authorization/host.spec.ts @@ -0,0 +1,68 @@ +import type { AppConfig, IUser } from '@librechat/data-schemas'; +import { buildScheduledApprovalAdmissionHooks } from './execution'; +import { createScheduledPauseCheck } from './host'; + +describe('createScheduledPauseCheck', () => { + const user = { id: 'owner', tenantId: 'tenant', role: 'USER' } as IUser; + function check( + over: { + shared?: boolean; + checkpointer?: unknown; + toolApproval?: { enabled?: boolean }; + } = {}, + ) { + const getCheckpointer = jest.fn(async () => ('checkpointer' in over ? over.checkpointer : {})); + const getAppConfig = jest.fn( + async () => + ({ + endpoints: { + agents: { toolApproval: over.toolApproval, checkpointer: { type: 'mongo' } }, + }, + }) as unknown as AppConfig, + ); + const canPause = createScheduledPauseCheck({ + isSharedStore: () => over.shared !== false, + getCheckpointer, + getAppConfig, + }); + return { canPause, getCheckpointer, getAppConfig }; + } + + it('says yes with a shared store, a durable checkpointer and approval not turned off', async () => { + const { canPause, getCheckpointer, getAppConfig } = check(); + expect(await canPause(user)).toBe(true); + expect(getCheckpointer).toHaveBeenCalledWith({ type: 'mongo' }); + expect(getAppConfig).toHaveBeenCalledWith( + expect.objectContaining({ userId: 'owner', tenantId: 'tenant', role: 'USER' }), + ); + expect(await check({ toolApproval: { enabled: true } }).canPause(user)).toBe(true); + }); + + it('says no without a shared generation store, and reads nothing else', async () => { + const { canPause, getAppConfig } = check({ shared: false }); + expect(await canPause(user)).toBe(false); + expect(getAppConfig).not.toHaveBeenCalled(); + }); + + it('says no where the administrator turned approval off', async () => { + expect(await check({ toolApproval: { enabled: false } }).canPause(user)).toBe(false); + }); + + it('says no without a durable checkpointer', async () => { + expect(await check({ checkpointer: undefined }).canPause(user)).toBe(false); + }); +}); + +describe('buildScheduledApprovalAdmissionHooks', () => { + it('announces a possible pause only for a grant that asks', async () => { + expect(buildScheduledApprovalAdmissionHooks()).toEqual([]); + expect(buildScheduledApprovalAdmissionHooks({ mayAsk: false })).toEqual([]); + const [entry, ...rest] = buildScheduledApprovalAdmissionHooks({ mayAsk: true }); + expect(rest).toEqual([]); + // No matcher: admission treats every tool as one that may ask. It decides nothing itself. + expect(entry.matcher).toBeUndefined(); + expect( + await entry.hook({} as Parameters[0], new AbortController().signal), + ).toEqual({}); + }); +}); diff --git a/packages/api/src/schedules/authorization/host.ts b/packages/api/src/schedules/authorization/host.ts index 6e6994d828..3c3b22410c 100644 --- a/packages/api/src/schedules/authorization/host.ts +++ b/packages/api/src/schedules/authorization/host.ts @@ -1,19 +1,40 @@ import { Permissions, + EModelEndpoint, PermissionTypes, DEFAULT_SCHEDULE_MCP_CONSENT_LIFETIME_HOURS, } from 'librechat-data-provider'; -import type { ScheduleMCPConsentStorage } from '@librechat/data-schemas'; -import type { ScheduledMCPIdentity } from 'librechat-data-provider'; -import type { IUser } from '@librechat/data-schemas'; +import type { ScheduleMCPConsentStorage, AppConfig, IUser } from '@librechat/data-schemas'; +import type { ScheduledMCPIdentity, TCheckpointerConfig } from 'librechat-data-provider'; import type { ScheduleMCPEnrollmentResolver, ScheduleMCPConsentService } from './service'; import type { ScheduleMCPConsentHandlers } from './handlers'; import type { CheckAccessParams } from '~/middleware/access'; +import type { GetAppConfigOptions } from '~/app/service'; import type { SchedulesHandlersDeps } from '../handlers'; import { createScheduleMCPConsentHandlers } from './handlers'; import { createScheduleMCPConsentService } from './service'; +import { getAppConfigOptionsFromUser } from '~/app/service'; import { checkAccess } from '~/middleware/access'; +/** + * A scheduled run waits for its owner on another day and, often, another replica. That needs + * a shared generation store and a durable checkpointer, and an endpoint that has not turned + * approval off. + */ +export function createScheduledPauseCheck(deps: { + isSharedStore: () => boolean; + getCheckpointer: (config?: TCheckpointerConfig) => Promise; + getAppConfig: (options: GetAppConfigOptions) => Promise; +}): (user: IUser) => Promise { + return async (user) => { + if (!deps.isSharedStore()) return false; + const config = await deps.getAppConfig(getAppConfigOptionsFromUser(user)); + const agents = config?.endpoints?.[EModelEndpoint.agents]; + if (agents?.toolApproval?.enabled === false) return false; + return (await deps.getCheckpointer(agents?.checkpointer)) != null; + }; +} + export function createScheduleMCPConsentHost(deps: { methods: ScheduleMCPConsentStorage & Pick; getLimits: SchedulesHandlersDeps['getLimits']; @@ -21,6 +42,8 @@ export function createScheduleMCPConsentHost(deps: { getRoleByName: CheckAccessParams['getRoleByName']; canViewAgent: (agentId: string, user: IUser) => Promise; resolveEnrollment?: ScheduleMCPEnrollmentResolver; + /** Whether a scheduled run of this owner can pause for approval. Absent, it cannot. */ + canPauseRuns?: (user: IUser) => Promise; }): { service: ScheduleMCPConsentService; handlers: ScheduleMCPConsentHandlers } { const pendingPrincipals = new Map>(); const loadPrincipal = (identity: ScheduledMCPIdentity): Promise => { @@ -76,6 +99,10 @@ export function createScheduleMCPConsentHost(deps: { return permissions.every(Boolean) && (await deps.canViewAgent(identity.agentId, user)); }, resolveEnrollment: deps.resolveEnrollment, + canPause: async (identity) => { + const user = await loadPrincipal(identity); + return user != null && (await deps.canPauseRuns?.(user)) === true; + }, }); const handlers = createScheduleMCPConsentHandlers({ service, diff --git a/packages/api/src/schedules/authorization/run.ts b/packages/api/src/schedules/authorization/run.ts index 9a8f56ecb0..ac2728cb45 100644 --- a/packages/api/src/schedules/authorization/run.ts +++ b/packages/api/src/schedules/authorization/run.ts @@ -1,5 +1,9 @@ import { Constants } from '@librechat/agents'; -import { Constants as ProviderConstants, normalizeServerName } from 'librechat-data-provider'; +import { + normalizeServerName, + SCHEDULE_APPROVAL_REASON, + Constants as ProviderConstants, +} from 'librechat-data-provider'; import type { HookCallback } from '@librechat/agents'; import type { ScheduleMCPExecution } from './execution'; import { ASK_USER_QUESTION_TOOL_NAME } from '~/agents/hitl/askUserQuestionTool'; @@ -184,12 +188,15 @@ export function createScheduledMCPRunPolicy( hook: async (input) => { const error = await failure(input); if (error) return { decision: 'deny', reason: error.message }; + if (input.executingAgentId == null) return {}; // The owner left this tool out on purpose. The model is told and the run goes on: it is // not a failure of the schedule, so nothing is recorded against the run. Should this hook // be skipped, the call is still refused where it is made, and that refusal is recorded. - return input.executingAgentId != null && - leftOut.get(input.executingAgentId)?.has(input.toolName) === true - ? { decision: 'deny', reason: SCHEDULE_TOOL_NOT_ALLOWED } + if (leftOut.get(input.executingAgentId)?.has(input.toolName) === true) + return { decision: 'deny', reason: SCHEDULE_TOOL_NOT_ALLOWED }; + // Pauses the run where it can pause. The call itself is checked again when it is made. + return execution.asksAbout(input.executingAgentId, input.toolName) + ? { decision: 'ask', reason: SCHEDULE_APPROVAL_REASON } : {}; }, // Separate hook: a failed or timed-out receipt must never erase the immediate deny. diff --git a/packages/api/src/schedules/authorization/runtime.spec.ts b/packages/api/src/schedules/authorization/runtime.spec.ts index 474f04eef5..fca19a7f2a 100644 --- a/packages/api/src/schedules/authorization/runtime.spec.ts +++ b/packages/api/src/schedules/authorization/runtime.spec.ts @@ -83,7 +83,9 @@ async function setup() { identity: fixture.identity, enrolled: false, })); + let pausable = true; const host = createScheduleMCPRuntimeHost({ + canPauseRuns: async () => pausable, getScheduleMCPCompletionState, methods: { ...fixture.storage, getScheduleById }, findUser, @@ -165,6 +167,9 @@ async function setup() { setCandidates: (names: string[]) => { candidates = names; }, + cannotPause: () => { + pausable = false; + }, check: () => preflight('root', fixture.user, { scheduleId: 'schedule', @@ -890,3 +895,65 @@ describe('a schedule its owner never authorized', () => { await expect(use()).resolves.toBeUndefined(); }); }); + +describe('a tool the owner approves call by call', () => { + async function asking() { + const f = await setup(); + const offer = await f.host.consent.service.view(f.identity); + await f.host.consent.service.confirm(f.identity, { + offerDigest: offer.offer!.digest, + expectedRevision: offer.revision, + lifetimeHours: 1, + allow: allowOffered(offer.targets), + ask: { warehouse: ['query'] }, + }); + f.row.mcpConsent = f.snapshot.enrollment!; + const use = (context: ReturnType, toolCallId?: string) => + bindScheduledMCPInvocation(context, 'root', 'query')!.authorize({ + user: f.user, + serverName: 'warehouse', + serverConfig: f.serverConfig, + toolName: 'query', + loadTools: async () => ({ tools: [readTool], complete: true }), + toolCallId, + }); + return { ...f, use }; + } + const refused = { failure: { reason: 'approval_required' } }; + + it('takes approvals only from the request that resumes a run', async () => { + const f = await asking(); + const fresh = createMCPRequestContext(); + await f.host.prepare({ req: f.req, context: fresh, approvedToolCalls: ['call-1'] }); + expect(getScheduleMCPExecution(fresh)?.mayAsk).toBe(true); + await expect(f.use(fresh, 'call-1')).rejects.toMatchObject(refused); + + const req = { user: f.user, _isScheduledFire: true, body: {} }; + const resumed = createMCPRequestContext(); + await f.host.prepare({ + req, + context: resumed, + executionContext: restoreExecutionContext(req, { + userId: 'owner', + tenantId: 'tenant', + scheduleId: 'schedule', + agent_id: 'root', + }), + approvedToolCalls: ['call-1'], + }); + await expect(f.use(resumed, 'call-1')).resolves.toBeUndefined(); + await expect(f.use(resumed, 'call-2')).rejects.toMatchObject(refused); + }); + + it('does not fail the readiness check of a schedule that will ask', async () => { + const f = await asking(); + await expect(f.check()).resolves.toBeDefined(); + }); + + it('reports whether this deployment can pause a scheduled run', async () => { + const f = await setup(); + expect(await f.host.consent.service.view(f.identity)).toMatchObject({ approval: true }); + f.cannotPause(); + expect(await f.host.consent.service.view(f.identity)).toMatchObject({ approval: false }); + }); +}); diff --git a/packages/api/src/schedules/authorization/runtime.ts b/packages/api/src/schedules/authorization/runtime.ts index 235c0f0ea6..1dbc97ca1f 100644 --- a/packages/api/src/schedules/authorization/runtime.ts +++ b/packages/api/src/schedules/authorization/runtime.ts @@ -47,6 +47,8 @@ export function createScheduleMCPRuntimeHost( scheduleManual?: boolean; scheduleMCPCompletion?: ScheduledMCPIdentity; }; + /** Tool calls the owner approved in the request that resumes this run. */ + approvedToolCalls?: readonly string[]; }) => Promise; } { function createEvaluation(enrollment: ScheduleMCPEnrollmentDeps) { @@ -183,6 +185,8 @@ export function createScheduleMCPRuntimeHost( manual: restoredContext ? restoredJob?.scheduleId === scheduleId && restoredJob.scheduleManual === true : fresh?.manual === true, + // Only a resumed run can carry approvals: a fresh occurrence has asked nobody yet. + ...(restoredContext && { approvedToolCalls: input.approvedToolCalls }), }); }, input.signal), }; diff --git a/packages/api/src/schedules/authorization/service.spec.ts b/packages/api/src/schedules/authorization/service.spec.ts index 670348d392..229b4bdb5a 100644 --- a/packages/api/src/schedules/authorization/service.spec.ts +++ b/packages/api/src/schedules/authorization/service.spec.ts @@ -41,6 +41,7 @@ function setup() { }; let targets = [structuredClone(target)]; let allowed = true; + let pausable = true; const storage: ScheduleMCPConsentStorage = { readScheduleMCPConsent: jest.fn(async () => structuredClone(snapshot)), confirmScheduleMCPConsent: jest.fn(async (input) => { @@ -77,17 +78,22 @@ function setup() { const service = createScheduleMCPConsentService({ storage, canUse: async () => allowed, + canPause: async () => pausable, getLimits: async () => ({ enabled: true, maxLifetimeHours: 24 }), resolveEnrollment: async () => targets, now: () => time, }); - const enroll = async (allow: Record = { warehouse: ['query'] }) => { + const enroll = async ( + allow: Record = { warehouse: ['query'] }, + ask?: Record, + ) => { const view = await service.view(identity); return service.confirm(identity, { offerDigest: view.offer!.digest, expectedRevision: view.revision, lifetimeHours: 1, allow, + ...(ask && { ask }), }); }; return { @@ -104,6 +110,9 @@ function setup() { deny: () => { allowed = false; }, + cannotPause: () => { + pausable = false; + }, }; } const request = (stage: 'activation' | 'mint' | 'invoke' | 'resume') => ({ @@ -646,3 +655,100 @@ it('requires a grant only from a schedule that has none', async () => { // The edit mark outlives the grant. Revoking it is then a refusal of its own, not this one. expect(await s.service.requiresGrant(identity)).toBe(false); }); + +describe('tools the owner approves call by call', () => { + const both = { ...target, permittedTools: [{ agentId: 'root', tools: ['list', 'query'] }] }; + const call = (tool: string) => ({ + ...request('invoke'), + selection: { agentId: 'root', tools: [tool] }, + definitions: { [tool]: 'a'.repeat(64) }, + }); + + it('stores them on the grant, reports them, and says so on each use', async () => { + const s = setup(); + s.changeTarget(both); + const view = await s.enroll({ warehouse: ['list', 'query'] }, { warehouse: ['query'] }); + expect(view).toMatchObject({ state: 'active', asking: { warehouse: ['query'] } }); + expect(s.snapshot.enrollment!.consents[0].askTools).toEqual(['query']); + expect(await s.service.authority.authorize(call('query'), {})).toMatchObject({ + state: 'authorized', + approvalRequired: true, + }); + const allowed = await s.service.authority.authorize(call('list'), {}); + expect(allowed).toMatchObject({ state: 'authorized' }); + expect(allowed).not.toHaveProperty('approvalRequired'); + // Minting a credential calls nothing, so nothing is asked. + expect( + await s.service.authority.authorize( + { ...request('mint'), selection: { agentId: 'root', tools: ['list', 'query'] } }, + {}, + ), + ).not.toHaveProperty('approvalRequired'); + }); + + it('stores nothing when the owner asks about no tool', async () => { + const s = setup(); + expect(await s.enroll({ warehouse: ['query'] }, { warehouse: [] })).toMatchObject({ + asking: {}, + }); + expect(s.snapshot.enrollment!.consents[0]).not.toHaveProperty('askTools'); + }); + + it.each([ + ['a tool that is not allowed', { warehouse: ['list'] }], + ['a server that is not in the grant', { other: ['query'] }], + ])('rejects asking about %s without writing', async (_case, ask) => { + const s = setup(); + s.changeTarget(both); + await expect(s.enroll({ warehouse: ['query'] }, ask)).rejects.toMatchObject({ + code: 'consent_invalid', + }); + expect(s.storage.confirmScheduleMCPConsent).not.toHaveBeenCalled(); + }); + + it('rejects it where a scheduled run cannot pause, and tells the dialog so', async () => { + const s = setup(); + s.cannotPause(); + expect(await s.service.view(identity)).toMatchObject({ approval: false }); + await expect( + s.enroll({ warehouse: ['query'] }, { warehouse: ['query'] }), + ).rejects.toMatchObject({ code: 'consent_invalid' }); + expect(s.storage.confirmScheduleMCPConsent).not.toHaveBeenCalled(); + expect(await s.enroll({ warehouse: ['query'] })).toMatchObject({ state: 'active' }); + }); + + it('keeps what the grant asks about when a confirmation does not say, and clears it when told to', async () => { + const s = setup(); + s.changeTarget(both); + await s.enroll({ warehouse: ['list', 'query'] }, { warehouse: ['list', 'query'] }); + // A client that does not send `ask` renews the grant; a tool it drops is no longer asked about. + expect(await s.enroll({ warehouse: ['query'] })).toMatchObject({ + asking: { warehouse: ['query'] }, + }); + expect(await s.enroll({ warehouse: ['query'] }, {})).toMatchObject({ asking: {} }); + expect(s.snapshot.enrollment!.consents[0]).not.toHaveProperty('askTools'); + }); + + it('keeps a stored question through a renewal where a run can no longer pause', async () => { + const s = setup(); + s.changeTarget(both); + await s.enroll({ warehouse: ['list', 'query'] }, { warehouse: ['query'] }); + s.cannotPause(); + // Renewed as it is, `query` still waits for the owner: it does not start running unattended. + for (const ask of [undefined, { warehouse: ['query'] }]) { + expect(await s.enroll({ warehouse: ['list', 'query'] }, ask)).toMatchObject({ + state: 'active', + asking: { warehouse: ['query'] }, + approval: false, + }); + expect(await s.service.authority.authorize(call('query'), {})).toMatchObject({ + approvalRequired: true, + }); + } + // A new question cannot be added here, and the owner can still drop the stored one. + await expect( + s.enroll({ warehouse: ['list', 'query'] }, { warehouse: ['list', 'query'] }), + ).rejects.toMatchObject({ code: 'consent_invalid' }); + expect(await s.enroll({ warehouse: ['list', 'query'] }, {})).toMatchObject({ asking: {} }); + }); +}); diff --git a/packages/api/src/schedules/authorization/service.ts b/packages/api/src/schedules/authorization/service.ts index 5dd5b898c3..94d7de497b 100644 --- a/packages/api/src/schedules/authorization/service.ts +++ b/packages/api/src/schedules/authorization/service.ts @@ -48,6 +48,8 @@ export interface ScheduleMCPConsentDeps { canUse: (identity: ScheduledMCPIdentity, options: { signal?: AbortSignal }) => Promise; /** What the owner can be offered now: reachable agents' selected tools, per declared server. */ resolveEnrollment?: ScheduleMCPEnrollmentResolver; + /** Whether a scheduled run can pause for the owner's approval here. Absent, it cannot. */ + canPause?: (identity: ScheduledMCPIdentity) => Promise; now?: () => number; } @@ -151,6 +153,38 @@ function selectAllowed( return canonicalTargets(chosen); } +/** + * Of the allowed tools, the ones the owner approves call by call. Each must be allowed on a + * server that made it into the grant. A confirmation that says nothing about asking keeps + * what the stored grant asks about, for the tools still allowed: only an explicit choice + * turns a tool the owner approves each time into one that runs unattended. + */ +function selectAsking( + chosen: readonly ScheduledMCPTarget[], + ask: ConfirmScheduleMCPConsent['ask'], + stored: Record, +): Record { + const allowed = allowedTools(chosen); + if (ask == null) + return Object.fromEntries( + Object.entries(stored) + .map(([serverName, tools]): [string, string[]] => [ + serverName, + tools.filter((tool) => allowed[serverName]?.includes(tool)), + ]) + .filter(([, tools]) => tools.length > 0), + ); + return Object.fromEntries( + Object.entries(ask) + .filter(([, tools]) => tools.length > 0) + .map(([serverName, tools]) => { + if (tools.some((tool) => !allowed[serverName]?.includes(tool))) + throw new ScheduleMCPConsentError('consent_invalid'); + return [serverName, [...new Set(tools)].sort()]; + }), + ); +} + /** Whether the grant still fits what is on offer: same recipients, and every allowed tool still selected. */ function coversGrant( offered: readonly ScheduledMCPTarget[], @@ -169,6 +203,15 @@ function coversGrant( }); } +/** Allowed tools the grant asks the owner about before each use, by server. */ +function askingTools(consents: readonly ScheduledMCPConsent[]): Record { + return Object.fromEntries( + consents + .filter((consent) => consent.askTools?.length) + .map((consent) => [consent.resource.serverName, [...consent.askTools!].sort()]), + ); +} + /** Allowed tools a run saw with a definition other than their pin, by server. */ function changedTools(consents: readonly ScheduledMCPConsent[]): Record { return Object.fromEntries( @@ -257,10 +300,11 @@ export function createScheduleMCPConsentService( options: { signal?: AbortSignal } = {}, ): Promise { options.signal?.throwIfAborted(); - const [snapshot, limits, allowed] = await Promise.all([ + const [snapshot, limits, allowed, approval] = await Promise.all([ deps.storage.readScheduleMCPConsent(identity), deps.getLimits(identity), deps.canUse(identity, options), + deps.canPause?.(identity) ?? false, ]); if (!snapshot) throw new ScheduleMCPConsentError('consent_not_found'); if (snapshot.agentId !== identity.agentId) throw new ScheduleMCPConsentError('consent_changed'); @@ -285,6 +329,7 @@ export function createScheduleMCPConsentService( })) ?? []; const allowedByServer = allowedTools(granted); const changedByServer = changedTools(enrollment?.consents ?? []); + const askingByServer = askingTools(enrollment?.consents ?? []); const required = !enrollment && requiresGrant(limits, snapshot, now()); const requireAfterMs = !enrollment && limits.enabled && !required ? (limits.requireAfterMs ?? null) : null; @@ -299,6 +344,8 @@ export function createScheduleMCPConsentService( targets: [], allowed: {}, changed: {}, + asking: {}, + approval, required: false, requireAfterMs: null, offer: null, @@ -317,6 +364,8 @@ export function createScheduleMCPConsentService( targets, allowed: allowedByServer, changed: changedByServer, + asking: askingByServer, + approval, required, requireAfterMs, offer: null, @@ -330,6 +379,8 @@ export function createScheduleMCPConsentService( targets, allowed: allowedByServer, changed: changedByServer, + asking: askingByServer, + approval, required, requireAfterMs, offer: null, @@ -347,6 +398,8 @@ export function createScheduleMCPConsentService( targets, allowed: allowedByServer, changed: changedByServer, + asking: askingByServer, + approval, required, requireAfterMs, offer, @@ -381,6 +434,18 @@ export function createScheduleMCPConsentService( ); if (digest !== input.offerDigest) throw new ScheduleMCPConsentError('consent_changed'); const chosen = selectAllowed(current.targets, input.allow); + const stored = askingTools(snapshot.enrollment?.consents ?? []); + const asking = selectAsking(chosen, input.ask, stored); + // A tool nobody can approve would only ever be refused. Say so now, not at 3 a.m. One the + // grant already asks about may stay: it is refused until pausing works again, and making + // it run unattended instead is for the owner to choose. + if ( + !current.approval && + Object.entries(asking).some(([serverName, tools]) => + tools.some((tool) => !stored[serverName]?.includes(tool)), + ) + ) + throw new ScheduleMCPConsentError('consent_invalid'); options.signal?.throwIfAborted(); const grantedAtMs = now(); const revision = randomUUID(); @@ -402,6 +467,9 @@ export function createScheduleMCPConsentService( grantedAtMs, absoluteExpiresAtMs: grantedAtMs + input.lifetimeHours * 3_600_000, revokedAtMs: null, + ...(asking[target.resource.serverName] && { + askTools: asking[target.resource.serverName], + }), })), }; const committed = await deps.storage.confirmScheduleMCPConsent({ @@ -570,6 +638,9 @@ export function createScheduleMCPConsentService( consentRevision: consent.revision, policyRevision: consent.policyRevision, validUntilMs: consent.absoluteExpiresAtMs, + ...(live.some(([tool]) => consent.askTools?.includes(tool)) && { + approvalRequired: true as const, + }), }; }, }; diff --git a/packages/api/src/schedules/mcp.ts b/packages/api/src/schedules/mcp.ts index 1c21e0d308..8e3901f1b6 100644 --- a/packages/api/src/schedules/mcp.ts +++ b/packages/api/src/schedules/mcp.ts @@ -512,6 +512,7 @@ export function createScheduleMCPPreflight(deps: ScheduleMCPDeps): ScheduleMCPPr toolName: definitions.length === 1 ? definitions[0].name : '', loadTools: async () => snapshot, signal, + readiness: true, }), ); } diff --git a/packages/api/src/tools/approval.ts b/packages/api/src/tools/approval.ts index ef794d3268..bce04997bc 100644 --- a/packages/api/src/tools/approval.ts +++ b/packages/api/src/tools/approval.ts @@ -143,6 +143,11 @@ export function withToolApprovalTransport( return execution ? transportContext.run({ execution, invocation }, invoke) : invoke(); } +/** The tool call a transport is being used for, when an approval session is running. */ +export function getToolApprovalTransportCallId(): string | undefined { + return transportContext.getStore()?.invocation.toolCallId; +} + /** Reconnect and SDK-internal retries cannot change the credential generation a call approved. */ export async function assertToolApprovalTransportEpoch( serverName: string, diff --git a/packages/data-provider/src/types/scheduleConsent.spec.ts b/packages/data-provider/src/types/scheduleConsent.spec.ts index e8f0f32200..43afaaee7c 100644 --- a/packages/data-provider/src/types/scheduleConsent.spec.ts +++ b/packages/data-provider/src/types/scheduleConsent.spec.ts @@ -36,6 +36,22 @@ it('takes the deadline for never-authorized schedules as an instant with an offs expect(parse(1798761600000)).toBe(false); }); +it('takes the tools to ask about as an optional choice beside the allowed ones', () => { + const parse = (ask?: unknown) => + confirmScheduleMCPConsentSchema.safeParse({ + offerDigest: 'a'.repeat(64), + expectedRevision: null, + lifetimeHours: 1, + allow: { warehouse: ['query'] }, + ...(ask !== undefined && { ask }), + }).success; + expect(parse()).toBe(true); + expect(parse({ warehouse: ['query'] })).toBe(true); + expect(parse({ warehouse: [] })).toBe(true); + expect(parse(['query'])).toBe(false); + expect(parse({ warehouse: 'query' })).toBe(false); +}); + it('requires an explicit tenant binding and delegated mode', () => { const identity = { scheduleId: 's', ownerId: 'u', agentId: 'a', invocationMode: 'delegated' }; expect(scheduledMCPIdentitySchema.safeParse(identity).success).toBe(false); @@ -165,6 +181,21 @@ it('lets the owner allow every tool a server can be offered with, across its age expect(parse(MAX_SCHEDULED_MCP_SERVER_TOOLS + 1)).toBe(false); }); +it('lets the owner ask first about as many tools as they can allow', () => { + const parse = (count: number) => { + const tools = Array.from({ length: count }, (_, index) => `tool-${index}`); + return confirmScheduleMCPConsentSchema.safeParse({ + offerDigest: 'a'.repeat(64), + expectedRevision: null, + lifetimeHours: 1, + allow: { warehouse: tools }, + ask: { warehouse: tools }, + }).success; + }; + expect(parse(300)).toBe(true); + expect(parse(MAX_SCHEDULED_MCP_SERVER_TOOLS + 1)).toBe(false); +}); + it('accepts a server the owner left with no tools beside one with a choice', () => { expect( confirmScheduleMCPConsentSchema.safeParse({ diff --git a/packages/data-provider/src/types/scheduleConsent.ts b/packages/data-provider/src/types/scheduleConsent.ts index fb7d74d3fc..4d60a671b8 100644 --- a/packages/data-provider/src/types/scheduleConsent.ts +++ b/packages/data-provider/src/types/scheduleConsent.ts @@ -2,6 +2,12 @@ import { z } from 'zod'; export const DEFAULT_SCHEDULE_MCP_CONSENT_LIFETIME_HOURS = 168; +/** + * Sent as the description of an approval request that a schedule's owner asked for. It is a + * code, not a sentence: the approval card shows its own wording in the reader's language. + */ +export const SCHEDULE_APPROVAL_REASON = 'schedule_owner_approval'; + const identifier = z.string().trim().min(1).max(256); const timestamp = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER); const safeUrl = z @@ -124,6 +130,8 @@ export const scheduledMCPConsentSchema = scheduledMCPTargetSchema definitions: z.array(scheduledMCPToolPinSchema).max(MAX_SCHEDULED_MCP_SERVER_TOOLS).optional(), /** Tools a run saw with a definition other than their pin. Refused until confirmed again. */ changedTools: z.array(identifier).max(MAX_SCHEDULED_MCP_SERVER_TOOLS).optional(), + /** Allowed tools the owner wants to approve call by call. A run pauses before each use. */ + askTools: z.array(identifier).max(MAX_SCHEDULED_MCP_SERVER_TOOLS).optional(), }) .strict() .refine((value) => value.absoluteExpiresAtMs > value.grantedAtMs); @@ -152,6 +160,14 @@ export const confirmScheduleMCPConsentSchema = z .record(identifier, z.array(identifier).max(MAX_SCHEDULED_MCP_SERVER_TOOLS)) .refine((value) => Object.keys(value).length <= 32) .refine((value) => Object.values(value).some((tools) => tools.length > 0)), + /** + * Of the allowed tools, the ones the owner wants to approve call by call, by server. + * Each must also be listed in `allow`. + */ + ask: z + .record(identifier, z.array(identifier).max(MAX_SCHEDULED_MCP_SERVER_TOOLS)) + .refine((value) => Object.keys(value).length <= 32) + .optional(), }) .strict(); export type ConfirmScheduleMCPConsent = z.infer; @@ -168,6 +184,10 @@ export interface ScheduleMCPConsentView { allowed: Record; /** Allowed tools whose definition changed since first use, by server. Refused until confirmed again. */ changed: Record; + /** Allowed tools the stored grant asks the owner about before each use, by server. */ + asking: Record; + /** Whether a scheduled run can pause for the owner's approval on this deployment. */ + approval: boolean; /** With no grant: whether the schedule's MCP tools are refused until the owner confirms. */ required: boolean; /** With no grant and not yet required: when the operator's deadline makes it so. */