Repository navigation
🙋 feat: Let a Schedule's Owner Approve a Tool Before Each Use - #18277
Conversation
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 81e8986378
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const canAsk = data?.approval === true; | ||
| const asking = editedAsking ?? (data && canAsk ? initialAsking(data, choice) : {}); |
There was a problem hiding this comment.
Preserve stored approval requirements when pausing is unavailable
If a grant already contains askTools and the deployment later disables tool approval, Redis streams, or durable checkpointing, the API returns approval: false while still offering renewal. This expression then discards the stored asking selections, and the dialog hides their controls. Confirming the otherwise unchanged grant sends allow without ask, which service.confirm persists as unconditional authorization. Renewing a grant can therefore silently turn fail-closed tools into unattended tools. Preserve the stored requirements and block renewal or require an explicit authorization change rather than clearing them implicitly.
AGENTS.md reference: AGENTS.md:L50-L52
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 0968673. The dialog now starts from the stored choice whether or not a run can pause, and always sends ask. Where a run cannot pause it shows only the stored questions, with a note that those tools are refused for now, so the owner can keep or drop them but add none. On the server, selectAsking keeps the stored questions for tools still allowed when ask is left out, and confirm rejects only a question the grant does not already hold where a run cannot pause. Renewing an unchanged grant therefore keeps the tool waiting for approval; making it run unattended takes an explicit untick.
Evidence: service.spec.ts › "keeps what the grant asks about when a confirmation does not say, and clears it when told to" and "keeps a stored question through a renewal where a run can no longer pause"; Consent.spec.tsx › "keeps what the stored grant asks about where a run cannot pause, and offers no new question". Five mutations (carry, the prior-ask rule, the pause check, the dialog's starting point, the boxes offered) each fail a test.
| export const SCHEDULE_APPROVAL_REASON = | ||
| 'You asked to approve each use of this tool when this schedule runs.'; |
There was a problem hiding this comment.
Localize the schedule approval explanation in the client
For users with a non-English locale, every schedule-generated approval card displays this English sentence: the hook passes it as reason, the interrupt exposes it as the action description, and ToolApproval.tsx renders that description directly. This bypasses the repository requirement to localize visible copy. Send a distinguishable schedule-approval reason that the client maps through useLocalize(), with its English translation in client/src/locales/en/translation.json.
AGENTS.md reference: AGENTS.md:L216-L217
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 317e7d0. The hook's reason is now a code, SCHEDULE_APPROVAL_REASON in librechat-data-provider. ToolApproval.tsx maps known codes to translation keys (descriptionKeys) and shows com_ui_approval_schedule_owner through useLocalize(); the English string is in client/src/locales/en/translation.json. Any other description is shown as sent.
Evidence: ToolApproval.test.tsx › "says a coded explanation in the reader's language and shows any other as sent". Removing the lookup makes it fail.
| return input.executingAgentId != null && | ||
| execution.asksAbout(input.executingAgentId, input.toolName) | ||
| ? { decision: 'ask', reason: SCHEDULE_APPROVAL_REASON } |
There was a problem hiding this comment.
Exclude scheduled per-use approvals from Always allow offers
When the endpoint enables toolApproval.allowAlways and does not explicitly list this tool under ask, this new hook can produce a schedule approval card that incorrectly offers “Always allow.” AgentClient.handleRunInterrupt calls markToolApprovalAllowAlways, but its eligibility check only inspects the static policy, registered programmatic hooks, and plugin hooks—not this separately installed schedule hook. Selecting the option persists a conversation allow, yet this hook still returns ask on the next use. Include the schedule's per-use requirement in both offer eligibility and the resume-time recheck so the UI does not promise an authorization mode the run cannot honor.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 8380f9c. markToolApprovalAllowAlways and recordToolApprovalAllows take an asksEveryUse predicate, checked against every spelling of the tool, for anything beyond the policy and its hooks that asks on each use. The schedule's grant supplies it through scheduleAsksEveryUse(req), passed from client.js (offer) and resume.js (recheck), so a tool the owner approves call by call is neither offered "Always allow" nor stored at resume.
Evidence: allow.spec.ts › "does not offer the choice for a tool something else asks about on every use" and "approves once a tool that is asked about on every use by the time of the resume"; execution.spec.ts › "tells an approval card that the tool is asked about on every use". The real /resume controller spec (hitlCheckpoint.e2e.spec.js) runs through both call sites.
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.
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.
… 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.
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.
81e8986 to
13c3599
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 13c3599a35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| setEditedAsking({ | ||
| ...asking, | ||
| [serverName]: (asking[serverName] ?? []).filter((tool) => tools.includes(tool)), |
There was a problem hiding this comment.
Preserve ask-first selections when reauthorizing changed tools
When a stored ask-first tool is marked as changed, initialChoice deliberately leaves it unchecked, so initialAsking(data, choice) also removes its stored approval requirement. Rechecking the tool then copies that empty asking selection here instead of restoring the stored requirement. Confirming sends allow with an empty ask, which service.confirm persists as unattended authorization—even though the owner only reauthorized the changed definition and never cleared its ask-first setting. Preserve stored asking selections independently of the temporary allow selection, filtering them only when constructing the confirmation payload.
AGENTS.md reference: AGENTS.md:L56-L59
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 968259a. The ask-first selection is no longer derived from the ticked tools. It starts from data.asking as stored, is kept as its own state, and is narrowed to the ticked tools only where the confirmation payload is built (ask in Consent.tsx). A changed tool that starts unticked therefore shows its question checked again as soon as the owner ticks it, and confirming sends it in ask.
Same class, read against the rule that a tool the grant asks about only stops asking when the owner clears its box: the owner's ask-first edits are now tied to the grant revision they were made against, so a question added to a grant confirmed in another tab is taken up instead of being dropped by an earlier edit here.
Evidence: Consent.spec.tsx › "keeps a changed tool asking first when the owner allows its new definition" (fails on the previous component) and "takes up a question added to a grant confirmed elsewhere, over an earlier edit of its own" (fails without the revision check).
…inition 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.
|
Codex Review: Didn't find any major issues. Can't wait for the next one! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
/quality risk scopes=api |
Quality reportGate: open. The selected checks completed. Scores and risk levels are advisory. Status: completed (success). Actions run, attempt 1.
Change riskTakeaway: 4 changed lines have no test. Highest CRAP among changed functions:
Changed lines with no test
|
| Function | Complexity | Coverage | CRAP | Location |
|---|---|---|---|---|
createRun |
170 | 92% | 183.2 | packages/api/src/agents/run.ts:2283 |
(anonymous) |
58 | 84% | 72.3 | packages/api/src/schedules/authorization/runtime.ts:105 |
authorize |
52 | 85% | 61.0 | packages/api/src/schedules/authorization/service.ts:515 |
view |
43 | 89% | 45.4 | packages/api/src/schedules/authorization/service.ts:298 |
authorize |
37 | 88% | 39.2 | packages/api/src/schedules/authorization/execution.ts:259 |
(anonymous) |
36 | 98% | 36.0 | packages/api/src/schedules/mcp.ts:449 |
resolve |
22 | 97% | 22.0 | packages/api/src/schedules/authorization/execution.ts:157 |
confirm |
19 | 86% | 20.1 | packages/api/src/schedules/authorization/service.ts:409 |
requestTool |
16 | 85% | 16.9 | packages/api/src/mcp/MCPManager.ts:1998 |
recordToolApprovalAllows |
11 | 91% | 11.1 | packages/api/src/agents/hitl/allow.ts:406 |
37 more functions below the threshold (or cut for size) are in report.md.
CRAP = complexity² × (1 − coverage)³ + complexity
Jobs (1)
| Check | Result |
|---|---|
| Change risk (api) | success |
All data (quality-report artifact) · Run page
The gate opens only when the workflow, source selection, tooling verification, and every report job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error, a job timeout, or an incomplete mutation report, including a mutation shard that reaches its execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk file marked incomplete or unavailable, for example by a failed api/ source-alias suite, does not close the gate.
Summary
A scheduled chat's owner can allow an MCP tool or leave it refused. There is nothing in between: a tool that is fine to list tables with but that the owner wants to look at before it exports one has to be either trusted completely or not used.
This PR adds the third state. Beside allowing a tool, the owner can set it to ask me first. When a scheduled run reaches that tool it pauses, the schedule shows "Needs approval" and links to the conversation, and the owner approves, edits or rejects that one use there. The next use asks again.
The pause is the existing tool-approval pause. What is new is that the owner's choice turns it on for that schedule's runs, without an administrator enabling approval for the whole endpoint, and that the MCP call itself refuses to run unless the owner approved that exact call.
Sixth step of the unattended-authority work, after #18058, #18255, #18260, #18273 and #18274. Related to #13824 and #16157.
How it works
The grant stores
askToolsper server. It is optional and additive.sequenceDiagram participant Run as Scheduled run participant Hook as Schedule PreToolUse hook participant Owner participant Gate as ScheduledMCPInvocation.authorize Run->>Hook: export_table (call tc1) Hook-->>Run: ask Run-->>Owner: paused, "Needs approval" Owner->>Run: resume, approve tc1 Note over Run: approved calls = [tc1], from the validated decisions Run->>Gate: export_table, call id tc1 Gate-->>Run: authorized (tc1 was approved) Run->>Gate: export_table, call id tc2 Gate-->>Run: approval_requiredTwo separate things happen, and only the second is a security boundary:
createScheduledMCPRunPolicy's hook answersaskfor a tool the grant asks about.resolveToolApprovalPolicygains anownerApprovallayer, modelled on the attached-code-environment one: when the endpoint policy is neither on nor off, the run gets{ enabled: true, mode: 'bypass' }, so the approval machinery is present and no other tool starts prompting. Run admission is told the run can pause, so the existing requirements of a paused scheduled run (shared generation store, durable checkpointer) are checked before any provider work.service.authorizenow reportsapprovalRequiredfor an ask tool, andScheduledMCPInvocation.authorizethen refuses withapproval_requiredunless the call's id is in the set the owner approved. The call id reachesMCPManager.callToolthrough the approval layer's existing async context. The approved set comes from the resume controller's validated decisions (approveoredit), is passed explicitly to schedule preparation, and is honoured only on a resumed run.The readiness check calls nothing, so it says so (
readiness: true) and is not asked. Anything that does not say so is gated.Where a run cannot pause.
createScheduledPauseCheckanswers whether this deployment can pause a scheduled run for this owner: Redis streams, a durable checkpointer, andendpoints.agents.toolApproval.enablednotfalse. Where it cannot, the view reportsapproval: false, the dialog offers "Ask me first" for no new tool, and confirming with a newaskis rejected. If the answer changes after a grant was made, the tool is refused, not run.In the dialog the ask-first selection is kept apart from the ticks. It starts from the stored grant and is narrowed to the ticked tools only when the confirmation is sent, so a tool whose definition changed (#18273), which starts unticked, still asks first once the owner ticks it again. The owner's edits to it hold only for the grant revision they were made against.
A question the grant already holds survives that change. The dialog starts from the stored choice whether or not a run can pause, and always sends
ask. Where a run cannot pause it shows only the stored questions, with a note that those tools are refused for now; the owner can keep or drop them. On the server, a confirmation that leavesaskout keeps the stored questions for the tools still allowed, so a client that does not know the field cannot turn an ask-first tool into an unattended one by renewing.The reason on the card. The hook's reason is a code (
SCHEDULE_APPROVAL_REASONinlibrechat-data-provider), not a sentence.ToolApproval.tsxmaps it to a localized string; any other description is shown as sent.Always allow. Where the endpoint enables it, the card offered "Always allow" for these tools, and choosing it stored a conversation allow the schedule overrode at the next use.
markToolApprovalAllowAlwaysandrecordToolApprovalAllowsnow take a predicate for anything beyond the policy that asks on every use, and the schedule's grant supplies it (scheduleAsksEveryUse(req)), so such a tool is neither offered nor stored.Type of change
Testing
Tested environments/configuration: WSL2, Node.js 24. No external services.
Automated tests:
packages/api/src/schedules/authorization/service.spec.ts(tools the owner approves call by call): stored, reported and flagged on each use; not flagged at mint; a tool that is not allowed, or a server not in the grant, is rejected without writing; rejected where a run cannot pause; a confirmation that leavesaskout keeps the stored questions and{}clears them; a stored question survives a renewal where a run can no longer pause, a new one is rejected there, and the owner can still drop it.packages/api/src/schedules/authorization/execution.spec.ts: refused without an approval, with or without a call id; the approved call runs and no other; a readiness check passes; an allowed tool is untouched; the run is told which tools to pause for; the hook answersaskfor those, nothing for an allowed tool, and still denies a tool outside the grant; an approval card's request is told the tool is asked about on every use, under either spelling, once the grant is attached.packages/api/src/agents/hitl/allow.spec.ts: such a tool is not offered "Always allow", matched under every name the run knows it by, and is approved once instead of stored at resume.client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx: a coded explanation is shown in the reader's language and any other as sent.packages/api/src/schedules/authorization/runtime.spec.ts: approvals are taken only from the request that resumes a run, not from a fresh occurrence; the readiness check of a schedule that asks passes; the view reports whether the deployment can pause.packages/api/src/mcp/__tests__/MCPManager.test.ts: at the manager boundary, the tool is dispatched only inside an approval session carrying the approved call id; another id, or no session, never reachestools/call.packages/api/src/schedules/authorization/host.spec.ts(new): each precondition of the pause check, and the admission entry.packages/api/src/agents/hitl/policy.spec.ts: the new layer turns approval on inbypass; an explicit endpointenabled: falseortrueis left as it is.api/server/controllers/agents/__tests__/resume.spec.js,api/server/services/Endpoints/agents/initialize.spec.js: the approved calls reach schedule preparation from the validated decisions.packages/data-provider/src/types/scheduleConsent.spec.ts: the confirm body'sask, bounded likeallow.client/src/components/SidePanel/Schedules/__tests__/Consent.spec.tsx: no control where a run cannot pause; the control appears only for an allowed tool, is dropped when the tool is disallowed, and only allowed tools are sent; a stored grant pre-fills it;ask: {}is sent once cleared; where a run cannot pause, only the stored question has a box, described by the note, and it is sent on renewal; a changed tool the owner allows again still asks first; a question added to a grant confirmed elsewhere replaces an earlier edit made in this dialog.Each new check was broken in turn and a test confirmed to fail.
npx tsc --noEmitis clean inpackages/api,packages/data-schemas,packages/data-providerandclient.Pause and resume, against a real run:
packages/api/src/schedules/authorization/approval.integration.spec.ts(new) builds an SDKRunwith a scripted model, the real approval session, the real schedule hook, the policy layer ascreateRunapplies it, and the real consent service. The tool body stands in forMCPManager.callTool: it asks the schedule's authority with the call id the approval layer holds. It shows the run interrupts with atool_approvalrequest carrying the schedule's reason and dispatches nothing; the approved call runs on resume; a rejected call does not; a call approved under another id is refused; with the hook removed (a hook the SDK discarded) the call is refused at the tool; with approval turned off by the administrator the SDK blocks the tool without pausing; a tool the owner simply allowed neither pauses nor is refused. Removing the hook'sask, the gate, the policy layer or the approval collection each fails it.Not verified: the same flow in a browser through the schedule engine, the pause persistence and the resume route. Those are the existing paths of any paused scheduled run and are not changed here, but no test in this PR runs them with a grant that asks. The mock e2e lane (
e2e/specs/mock/schedules-execution.spec.ts) on Redis is the place for it.Performance
Nothing is added to a run's per-call path beyond in-memory lookups: whether a tool asks is a set lookup built once when the grant is attached, and the approved call ids are a set built from the resume request. The pause check (
createScheduledPauseCheck) runs when the dialog reads or confirms a grant, in parallel with the readsviewalready made, and reuses the owner lookup the host coalesces. No database or network call is added to tool calls, run start or resume. I did not measure latency before and after.Screenshots / recordings
The real
Consentcomponent under the app's stylesheet in Chromium, fed fixed consent data in place of the API. "Before" is the component from #18274 with the same grant. The Cancel button shows its key because the capture does not initialise the shared package's i18n; the app does.The note shown where a run cannot pause and the grant holds a question was added after these captures and is not shown here.
When the owner cannot confirm (no offer), the tools that ask are listed:
Risk / compatibility
Approval turns on for runs of a grant that asks, without the administrator enabling it. It is
bypassmode, so only the tools the owner marked ask. An administrator's explicittoolApproval.enabled: falsewins: there the option is not offered and such a tool is refused.Runs of a grant that asks need Redis streams and a durable checkpointer. That is the existing requirement of any scheduled run that can pause. The option is not offered without them.
A run that both pauses and is denied another tool ends as an error.
recordRunOutcomealready turns a paused scheduled run with a recorded MCP denial into an error and aborts it. I left that as it is.Approving is per call. "Always allow" is not offered for these tools; the owner changes the tool to allowed in the dialog instead. A changed tool (#18273) is still refused until confirmed again; it does not fall back to asking, because the approval card cannot show what changed.
Remote API runs are untouched. Treating "ask" as refused for a foreground API run belongs with the API-key work.
Mixed versions: the stored grant gains one optional field and the stored schema is strict, so a replica without this change reads a grant that asks as incompatible and refuses its runs, as for #18273.
Schedule consent is off by default (
interface.schedules.mcpConsent.enabled).