🔌 refactor: Support Host-Provided Approval Submission (#17612)

* 🔌 refactor: Support Host-Provided Approval Submission

* fix: Keep Host Approval Submission In Shared Lifecycle
This commit is contained in:
Dustin Healy 2026-11-10 21:04:03 -08:00 • committed by GitHub
parent 8596615d1d
commit bb62fe4cd5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 383 additions and 82 deletions

View file

@ -25,6 +25,17 @@ import {
import { useChatSettings } from '~/Providers/ChatSettingsContext';
import { ChatContext } from '~/Providers/ChatContext';
export interface ResumeSubmitTransport {
submitToolApproval: (
actionId: string,
decisions: Agents.ToolApprovalResolution[],
) => Promise<void>;
submitAskAnswer: (actionId: string, resolution: string | Record<string, string>) => Promise<void>;
}
/** Host-owned I/O; the shared hook owns selected payloads, submission locks and status. */
export const ResumeSubmitContext = createContext<ResumeSubmitTransport | null>(null);
/** Shared read/write for the ask-answer submit status. */
export function useAskSubmitStatus(): {
getAskStatus: (actionId: string) => AskAnswerStatus;
@ -150,14 +161,14 @@ const isExpiredError = (error: unknown): boolean => {
* React Query. Message content renders in places without those providers (shared /
* exported views, tests), so the provider must be safe to mount anywhere. The
* context-dependent submit lives in {@link useResumeSubmit}, which the cards call —
* and the cards only render inside a live chat view where those providers exist.
* which chooses the ordinary chat transport or an explicitly supplied host transport.
*/
export default function ApprovalProvider({
children,
pendingAction,
}: {
children: React.ReactNode;
pendingAction?: Agents.PendingAction | null;
pendingAction?: Pick<Agents.PendingAction, 'actionId' | 'payload'> | null;
}) {
/** Content slices keep their historical local provider so exported/read-only
* renderers remain self-contained. Inside a live chat, reuse the provider
@ -174,7 +185,7 @@ function ApprovalStateProvider({
pendingAction,
}: {
children: React.ReactNode;
pendingAction?: Agents.PendingAction | null;
pendingAction?: Pick<Agents.PendingAction, 'actionId' | 'payload'> | null;
}) {
/** actionId → (tool_call_id → resolution). Mutable refs so reads are
* synchronous for `isReady`/submit; `version` is threaded into the context
@ -413,6 +424,18 @@ function ApprovalStateProvider({
return <ApprovalContext.Provider value={value}>{children}</ApprovalContext.Provider>;
}
/** A host may reject asynchronously or throw before returning its request promise. */
function submitHost(
submit: () => Promise<void>,
callbacks: { onSuccess: () => void; onError: (error: unknown) => void },
): void {
try {
void submit().then(callbacks.onSuccess, callbacks.onError);
} catch (error) {
callbacks.onError(error);
}
}
/**
* Submit hook for the approval cards. Sources the resume body's agent/endpoint
* fields from the active conversation (so the route's shared `buildEndpointOption`
@ -423,10 +446,11 @@ function ApprovalStateProvider({
* live chat views but ALSO from contexts without a `ChatContext.Provider` (e.g. a
* subagent tool paused inside an isolated activity surface, or a search/citation render that
* passes chat context as a prop), so it reads the context non-throwingly: with no
* conversation, `buildResumeFields` returns null and the controls are inert rather
* than crashing.
* conversation, the ordinary transport stays inert. An explicit host supplies only
* I/O; payload readiness, synchronous locks and submission status stay shared.
*/
export function useResumeSubmit() {
const transport = useContext(ResumeSubmitContext);
const jotaiStore = useStore();
const chatContext = useContext(ChatContext);
const conversation = chatContext?.conversation;
@ -435,7 +459,6 @@ export function useResumeSubmit() {
const askMutation = useSubmitAskAnswerMutation();
const { getDecisions, isReady, setStatus, beginToolSubmission, endToolSubmission } =
useApprovalContext();
const submittingAskActionIdsRef = useRef(new Set<string>());
/** Ask status lives in Jotai so it works from the composer (outside the
* provider); tool-approval status stays on the context. */
const { setAskStatus } = useAskSubmitStatus();
@ -469,35 +492,29 @@ export function useResumeSubmit() {
const submitToolApproval = useCallback(
(actionId: string) => {
const fields = buildResumeFields();
const fields = transport ? null : buildResumeFields();
const decisions = getDecisions(actionId);
if (!fields || decisions.length === 0 || !isReady(actionId)) {
return;
}
if (!beginToolSubmission(actionId)) {
return;
}
if ((!transport && !fields) || decisions.length === 0 || !isReady(actionId)) return;
if (!beginToolSubmission(actionId)) return;
setStatus(actionId, 'submitting');
approvalMutation.mutate(
{ ...fields, actionId, decisions },
{
onSuccess: () => {
setStatus(actionId, 'submitted');
const pendingAtom = pendingApprovalActionFamily(fields.conversationId);
if (jotaiStore.get(pendingAtom)?.actionId === actionId) {
jotaiStore.set(pendingAtom, null);
}
},
onError: (error) => {
const expired = isExpiredError(error);
if (!expired) {
// Network/validation failures are retryable; a 409 is terminal.
endToolSubmission(actionId);
}
setStatus(actionId, expired ? 'expired' : 'error');
},
const callbacks = {
onSuccess: () => {
setStatus(actionId, 'submitted');
if (!fields) return;
const pendingAtom = pendingApprovalActionFamily(fields.conversationId);
if (jotaiStore.get(pendingAtom)?.actionId === actionId) jotaiStore.set(pendingAtom, null);
},
);
onError: (error: unknown) => {
const expired = isExpiredError(error);
if (!expired) endToolSubmission(actionId);
setStatus(actionId, expired ? 'expired' : 'error');
},
};
if (transport) {
submitHost(() => transport.submitToolApproval(actionId, decisions), callbacks);
} else if (fields) {
approvalMutation.mutate({ ...fields, actionId, decisions }, callbacks);
}
},
[
approvalMutation,
@ -508,6 +525,7 @@ export function useResumeSubmit() {
isReady,
jotaiStore,
setStatus,
transport,
],
);
@ -517,67 +535,48 @@ export function useResumeSubmit() {
resolution: string | Record<string, string>,
opts?: { onSuccess?: () => void },
) => {
const fields = buildResumeFields();
const fields = transport ? null : buildResumeFields();
const isBatch = typeof resolution !== 'string';
const hasAnswer = isBatch ? Object.keys(resolution).length > 0 : resolution.length > 0;
if (!fields || !hasAnswer) {
return;
}
if (submittingAskActionIdsRef.current.has(actionId)) {
return;
}
submittingAskActionIdsRef.current.add(actionId);
if ((!transport && !fields) || !hasAnswer) return;
// Read the shared Jotai store synchronously: two rendered surfaces must
// not both enter before React publishes their next render.
const status = jotaiStore.get(askSubmitStatusAtom)[actionId];
if (status === 'submitting' || status === 'submitted' || status === 'expired') return;
setAskStatus(actionId, 'submitting');
askMutation.mutate(
{
...fields,
actionId,
...(isBatch ? { answers: resolution } : { answer: resolution }),
},
{
onSuccess: () => {
setAskStatus(actionId, 'submitted');
/**
* Drop the synthetic question part now that the run is resuming: the
* server streams the resumed segment at ABSOLUTE content indices
* continuing after the pre-pause parts — the exact slot this appended
* part occupies. Left in place it blocks that index and the resumed
* output doesn't render until finalize. The Q&A's durable record is
* the ask_user_question tool call itself.
*/
const callbacks = {
onSuccess: () => {
setAskStatus(actionId, 'submitted');
if (!transport) {
// Only the ordinary chat transport owns synthetic timeline question parts.
const messages = chatContext?.getMessages?.();
if (messages && chatContext?.setMessages) {
let changed = false;
const next = messages.map((message) => {
const resolved = resolveAskUserQuestionPart(message, actionId, resolution);
if (resolved !== message) {
changed = true;
}
if (resolved !== message) changed = true;
return resolved;
});
if (changed) {
chatContext.setMessages(next);
}
if (changed) chatContext.setMessages(next);
}
/**
* Caller cleanup (clearing the composer / selection) runs ONLY on
* success: the composer is the user's sole copy of a free-form
* answer, so a failed resume (400 on the answer cap, expiry, a
* network error) must leave it intact for the user to trim/retry.
*/
opts?.onSuccess?.();
},
onError: (error) => {
const expired = isExpiredError(error);
if (!expired) {
submittingAskActionIdsRef.current.delete(actionId);
}
setAskStatus(actionId, expired ? 'expired' : 'error');
},
}
// A failed request must retain the caller's only copy of the answer.
opts?.onSuccess?.();
},
);
onError: (error: unknown) => {
setAskStatus(actionId, isExpiredError(error) ? 'expired' : 'error');
},
};
if (transport) {
submitHost(() => transport.submitAskAnswer(actionId, resolution), callbacks);
} else if (fields) {
askMutation.mutate(
{ ...fields, actionId, ...(isBatch ? { answers: resolution } : { answer: resolution }) },
callbacks,
);
}
},
[askMutation, buildResumeFields, setAskStatus, chatContext],
[askMutation, buildResumeFields, setAskStatus, chatContext, jotaiStore, transport],
);
return { submitToolApproval, submitAskAnswer };

View file

@ -3,7 +3,13 @@ import { RecoilRoot } from 'recoil';
import { act, renderHook } from '@testing-library/react';
import { Provider as JotaiProvider, createStore } from 'jotai';
import { activeGenerationCreatedAtByConvoId } from '@librechat/chat/react';
import ApprovalProvider, { useApprovalContext, useResumeSubmit } from '../ApprovalContext';
import type { ResumeSubmitTransport } from '../ApprovalContext';
import ApprovalProvider, {
ResumeSubmitContext,
useApprovalContext,
useAskSubmitStatus,
useResumeSubmit,
} from '../ApprovalContext';
import { ChatContext } from '~/Providers/ChatContext';
const mockApprovalMutate = jest.fn();
@ -78,6 +84,246 @@ describe('useResumeSubmit', () => {
jest.clearAllMocks();
});
test('passes full selected batches and answers through a host while owning submission state outside chat', async () => {
const pending = Promise.withResolvers<void>();
const transport: ResumeSubmitTransport = {
submitToolApproval: jest.fn(() => pending.promise),
submitAskAnswer: jest.fn(async () => {}),
};
const onSuccess = jest.fn();
const hostWrapper = ({ children }: { children: React.ReactNode }) => (
<JotaiProvider>
<ResumeSubmitContext.Provider value={transport}>
<ApprovalProvider>{children}</ApprovalProvider>
</ResumeSubmitContext.Provider>
</JotaiProvider>
);
const { result } = renderHook(
() => ({
approval: useApprovalContext(),
first: useResumeSubmit(),
second: useResumeSubmit(),
}),
{ wrapper: hostWrapper },
);
const decisions: import('librechat-data-provider').Agents.ToolApprovalResolution[] = [
{ tool_call_id: 'approve', decision: 'approve', scope: 'session' },
{
tool_call_id: 'edit',
decision: 'edit',
editedArguments: { path: 'new.ts', nested: { enabled: true } },
},
{ tool_call_id: 'respond', decision: 'respond', responseText: 'Use the existing file.' },
{ tool_call_id: 'reject', decision: 'reject', reason: 'Do not run this command.' },
];
act(() => {
for (const decision of decisions) {
result.current.approval.registerToolCall('approval-action', decision.tool_call_id);
result.current.approval.setDecision('approval-action', decision.tool_call_id, decision);
}
result.current.first.submitToolApproval('approval-action');
result.current.second.submitToolApproval('approval-action');
});
expect(transport.submitToolApproval).toHaveBeenCalledTimes(1);
expect(transport.submitToolApproval).toHaveBeenCalledWith('approval-action', decisions);
expect(result.current.approval.getStatus('approval-action')).toBe('submitting');
await act(async () => {
pending.resolve();
});
expect(result.current.approval.getStatus('approval-action')).toBe('submitted');
await act(async () => {
result.current.first.submitAskAnswer('single-action', 'answer', { onSuccess });
result.current.first.submitAskAnswer('batch-action', { first: 'yes', second: 'no' });
});
expect(transport.submitAskAnswer).toHaveBeenNthCalledWith(1, 'single-action', 'answer');
expect(transport.submitAskAnswer).toHaveBeenNthCalledWith(2, 'batch-action', {
first: 'yes',
second: 'no',
});
expect(onSuccess).toHaveBeenCalledTimes(1);
expect(mockApprovalMutate).not.toHaveBeenCalled();
expect(mockAskMutate).not.toHaveBeenCalled();
});
test('switches host transports without changing hook order and restores ordinary chat submission', async () => {
const first: ResumeSubmitTransport = {
submitToolApproval: jest.fn(async () => {}),
submitAskAnswer: jest.fn(async () => {}),
};
const second: ResumeSubmitTransport = {
submitToolApproval: jest.fn(async () => {}),
submitAskAnswer: jest.fn(async () => {}),
};
let transport: ResumeSubmitTransport | null = null;
const ChatWrapper = createWrapper(1000);
const hostWrapper = ({ children }: { children: React.ReactNode }) => (
<ChatWrapper>
<ResumeSubmitContext.Provider value={transport}>{children}</ResumeSubmitContext.Provider>
</ChatWrapper>
);
const { result, rerender } = renderHook(() => useResumeSubmit(), { wrapper: hostWrapper });
transport = first;
rerender();
await act(async () => result.current.submitAskAnswer('host-first', 'first'));
expect(first.submitAskAnswer).toHaveBeenCalledWith('host-first', 'first');
transport = second;
rerender();
await act(async () => result.current.submitAskAnswer('host-second', 'second'));
expect(second.submitAskAnswer).toHaveBeenCalledWith('host-second', 'second');
expect(mockAskMutate).not.toHaveBeenCalled();
transport = null;
rerender();
act(() => result.current.submitAskAnswer('chat-action', 'ordinary'));
expect(mockAskMutate).toHaveBeenCalledTimes(1);
expect(mockAskMutate).toHaveBeenCalledWith(
expect.objectContaining({
conversationId: 'conversation-1',
actionId: 'chat-action',
answer: 'ordinary',
}),
expect.any(Object),
);
});
test.each(['tool', 'ask'] as const)(
'owns pending, retryable failure and success for %s host submissions across hook instances',
async (kind) => {
const first = Promise.withResolvers<void>();
const retry = Promise.withResolvers<void>();
const send = jest
.fn()
.mockImplementationOnce(() => first.promise)
.mockImplementationOnce(() => retry.promise);
const transport: ResumeSubmitTransport = { submitToolApproval: send, submitAskAnswer: send };
const hostWrapper = ({ children }: { children: React.ReactNode }) => (
<JotaiProvider>
<ApprovalProvider>
<ResumeSubmitContext.Provider value={transport}>
{children}
</ResumeSubmitContext.Provider>
</ApprovalProvider>
</JotaiProvider>
);
const { result } = renderHook(
() => ({
approval: useApprovalContext(),
ask: useAskSubmitStatus(),
first: useResumeSubmit(),
second: useResumeSubmit(),
}),
{ wrapper: hostWrapper },
);
const onSuccess = jest.fn();
const submit = (surface: 'first' | 'second') =>
kind === 'tool'
? result.current[surface].submitToolApproval('action')
: result.current[surface].submitAskAnswer('action', 'answer', { onSuccess });
const status = () =>
kind === 'tool'
? result.current.approval.getStatus('action')
: result.current.ask.getAskStatus('action');
act(() => {
result.current.approval.registerToolCall('action', 'tool');
result.current.approval.setDecision('action', 'tool', {
tool_call_id: 'tool',
decision: 'approve',
});
submit('first');
submit('second');
});
expect(send).toHaveBeenCalledTimes(1);
expect(status()).toBe('submitting');
await act(async () => {
first.reject(new Error('temporary'));
});
expect(status()).toBe('error');
expect(onSuccess).not.toHaveBeenCalled();
act(() => {
submit('second');
submit('first');
});
expect(send).toHaveBeenCalledTimes(2);
expect(status()).toBe('submitting');
await act(async () => {
retry.resolve();
});
expect(status()).toBe('submitted');
act(() => {
submit('first');
submit('second');
});
expect(send).toHaveBeenCalledTimes(2);
expect(onSuccess).toHaveBeenCalledTimes(kind === 'ask' ? 1 : 0);
},
);
test.each(['tool', 'ask'] as const)(
'keeps expired %s host submissions terminal and catches synchronous transport errors',
async (kind) => {
const send = jest
.fn<Promise<void>, []>()
.mockImplementationOnce(() => {
throw new Error('synchronous failure');
})
.mockRejectedValueOnce({ response: { status: 409 } });
const transport: ResumeSubmitTransport = { submitToolApproval: send, submitAskAnswer: send };
const hostWrapper = ({ children }: { children: React.ReactNode }) => (
<JotaiProvider>
<ApprovalProvider>
<ResumeSubmitContext.Provider value={transport}>
{children}
</ResumeSubmitContext.Provider>
</ApprovalProvider>
</JotaiProvider>
);
const { result } = renderHook(
() => ({
approval: useApprovalContext(),
ask: useAskSubmitStatus(),
submit: useResumeSubmit(),
}),
{ wrapper: hostWrapper },
);
const submit = () =>
kind === 'tool'
? result.current.submit.submitToolApproval('action')
: result.current.submit.submitAskAnswer('action', 'answer');
const status = () =>
kind === 'tool'
? result.current.approval.getStatus('action')
: result.current.ask.getAskStatus('action');
act(() => {
result.current.approval.registerToolCall('action', 'tool');
result.current.approval.setDecision('action', 'tool', {
tool_call_id: 'tool',
decision: 'approve',
});
});
await act(async () => submit());
expect(status()).toBe('error');
await act(async () => submit());
expect(status()).toBe('expired');
act(() => submit());
expect(send).toHaveBeenCalledTimes(2);
},
);
test('accepts only action identity and payload without requiring chat stream metadata', () => {
const hostWrapper = ({ children }: { children: React.ReactNode }) => (
<JotaiProvider>
<ApprovalProvider
pendingAction={{ actionId: pendingAction.actionId, payload: pendingAction.payload }}
>
{children}
</ApprovalProvider>
</JotaiProvider>
);
const { result } = renderHook(() => useApprovalContext(), { wrapper: hostWrapper });
expect(result.current.getRegisteredCount('action-1')).toBe(2);
expect(result.current.getLeadToolCallId('action-1')).toBe('call-1');
expect(result.current.isReady('action-1')).toBe(false);
});
test('synchronously deduplicates tool approval submissions and unlocks a retryable error', () => {
const { result } = renderHook(
() => ({

View file

@ -10,7 +10,7 @@ import {
} from '@librechat/chat/react';
import type { ShortcutBinding } from '@librechat/chat';
import type { Agents } from 'librechat-data-provider';
import ApprovalProvider, { useApprovalContext } from '../ApprovalContext';
import ApprovalProvider, { ResumeSubmitContext, useApprovalContext } from '../ApprovalContext';
import { ChatContext } from '~/Providers/ChatContext';
import ToolApproval from '../ToolApproval';
@ -204,6 +204,62 @@ describe('ToolApproval', () => {
expect(submit).toBeEnabled();
});
test('hosted cards submit the selected batch and keep decisions locked through acknowledgement', async () => {
const first = Promise.withResolvers<void>();
const retry = Promise.withResolvers<void>();
const send = jest
.fn()
.mockImplementationOnce(() => first.promise)
.mockImplementationOnce(() => retry.promise);
render(
<RecoilRoot>
<Provider>
<ApprovalProvider>
<ResumeSubmitContext.Provider
value={{ submitToolApproval: send, submitAskAnswer: async () => {} }}
>
<ToolApproval
approval={approval(['edit'])}
toolCallId="call-1"
args={{ old: true }}
/>
<ToolApproval approval={approval(['reject'])} toolCallId="call-2" args={{}} />
</ResumeSubmitContext.Provider>
</ApprovalProvider>
</Provider>
</RecoilRoot>,
);
fireEvent.click(screen.getByRole('button', { name: 'Edit' }));
const editor = screen.getByRole('textbox', { name: 'Edit' });
fireEvent.change(editor, { target: { value: '{"path":"new.ts"}' } });
fireEvent.click(screen.getByRole('button', { name: 'Reject' }));
const reason = screen.getByRole('textbox', { name: 'Reject' });
fireEvent.change(reason, { target: { value: 'Keep the existing file.' } });
fireEvent.click(screen.getByRole('button', { name: 'Submit 2 decisions' }));
expect(send).toHaveBeenCalledTimes(1);
expect(send).toHaveBeenCalledWith('action-1', [
{ tool_call_id: 'call-1', decision: 'edit', editedArguments: { path: 'new.ts' } },
{ tool_call_id: 'call-2', decision: 'reject', reason: 'Keep the existing file.' },
]);
expect(editor).toBeDisabled();
expect(reason).toBeDisabled();
expect(screen.getByRole('button', { name: 'Edit' })).toBeDisabled();
expect(screen.getByRole('button', { name: 'Reject' })).toBeDisabled();
await act(async () => {
first.reject(new Error('temporary'));
});
expect(editor).toBeEnabled();
expect(reason).toHaveValue('Keep the existing file.');
fireEvent.click(screen.getByRole('button', { name: 'Submit 2 decisions' }));
expect(send).toHaveBeenCalledTimes(2);
await act(async () => {
retry.resolve();
});
expect(editor).toBeDisabled();
expect(reason).toBeDisabled();
expect(mockMutate).not.toHaveBeenCalled();
});
test('duplicated review surfaces show and submit the same decision state', () => {
renderCards(
<>