From a0f17e55811da055d1cf0393d2423e20dcc0905d Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Wed, 18 Nov 2026 12:18:15 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=99=8B=20feat:=20Let=20a=20Schedule's=20O?= =?UTF-8?q?wner=20Approve=20a=20Tool=20Before=20Each=20Use=20(#18277)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ๐Ÿ™‹ feat: Let a Schedule's Owner Approve a Tool Before Each Use * ๐Ÿงช test: Drive a Real Run Through a Schedule's Approval Pause and Resume * ๐Ÿ™‹ fix: Keep a Stored Ask-First Choice When a Run Can No Longer Pause Where pausing became unavailable, the dialog hid the ask-first boxes and renewed the grant without them, so a tool the owner approved each time started running unattended. The dialog now starts from the stored choice either way and always sends it. Where a run cannot pause it shows only the stored questions, with a note that those tools are refused for now, and the owner can keep or drop them but add none. The server keeps the stored questions for tools still allowed when a confirmation says nothing about asking, and refuses only a new question where a run cannot pause. * ๐Ÿ™‹ fix: Say Why a Schedule Asks for Approval in the Reader's Language The approval card showed an English sentence sent by the server as the request's description. The server now sends a code, and the card maps it to a localized string. Any other description is shown as sent. * ๐Ÿ™‹ fix: Never Offer Always Allow for a Tool a Schedule Asks About Each Use Where the endpoint enables Always allow, a schedule's approval card offered it for a tool the owner approves on each use. Choosing it stored a conversation allow the schedule still overrode at the next use. The offer and the recheck at resume now take a predicate for anything beyond the policy that asks on every use, and the schedule's grant supplies it, so such a tool is neither offered nor stored. * ๐Ÿ™‹ fix: Let the Owner Ask First About as Many Tools as They Can Allow The confirmation accepted up to 25,600 allowed tools per server but only 256 to ask about, so a large grant could not be confirmed with every tool set to ask first. * ๐Ÿ™‹ fix: Keep a Tool Asking First When the Owner Allows Its Changed Definition The dialog derived the ask-first boxes from the ticked tools. A tool whose definition changed starts unticked, so its stored question was dropped, and ticking the tool again confirmed it as unattended. The ask-first selection is now kept apart from the ticks, starts from the stored grant, and is narrowed to the ticked tools only when the confirmation is sent. The owner's edits to it hold only for the grant they were made against, so a question added to a grant confirmed elsewhere is not dropped unseen. --- .../agents/__tests__/resume.spec.js | 2 + api/server/controllers/agents/client.js | 6 + api/server/controllers/agents/resume.js | 4 + .../services/Endpoints/agents/initialize.js | 1 + .../Endpoints/agents/initialize.spec.js | 20 ++ api/server/services/Schedules/consent.js | 12 +- .../Chat/Messages/Content/ToolApproval.tsx | 12 +- .../Content/__tests__/ToolApproval.test.tsx | 22 ++ .../SidePanel/Schedules/Consent.tsx | 90 +++++++ .../Schedules/__tests__/Consent.spec.tsx | 185 ++++++++++++++ client/src/locales/en/translation.json | 7 +- packages/api/src/agents/hitl/allow.spec.ts | 37 +++ packages/api/src/agents/hitl/allow.ts | 36 ++- packages/api/src/agents/hitl/policy.spec.ts | 20 ++ packages/api/src/agents/hitl/policy.ts | 8 +- packages/api/src/agents/run.ts | 1 + packages/api/src/mcp/MCPManager.ts | 3 +- .../api/src/mcp/__tests__/MCPManager.test.ts | 27 +- packages/api/src/schedules/README.md | 23 ++ .../approval.integration.spec.ts | 233 ++++++++++++++++++ .../src/schedules/authorization/contract.ts | 2 + .../authorization/execution.helper.ts | 19 +- .../schedules/authorization/execution.spec.ts | 130 +++++++++- .../src/schedules/authorization/execution.ts | 93 ++++++- .../src/schedules/authorization/host.spec.ts | 68 +++++ .../api/src/schedules/authorization/host.ts | 33 ++- .../api/src/schedules/authorization/run.ts | 15 +- .../schedules/authorization/runtime.spec.ts | 67 +++++ .../src/schedules/authorization/runtime.ts | 4 + .../schedules/authorization/service.spec.ts | 108 +++++++- .../src/schedules/authorization/service.ts | 73 +++++- packages/api/src/schedules/mcp.ts | 1 + packages/api/src/tools/approval.ts | 5 + .../src/types/scheduleConsent.spec.ts | 31 +++ .../src/types/scheduleConsent.ts | 20 ++ 35 files changed, 1383 insertions(+), 35 deletions(-) create mode 100644 packages/api/src/schedules/authorization/approval.integration.spec.ts create mode 100644 packages/api/src/schedules/authorization/host.spec.ts 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. */