🔱 feat: Simplify Steering Controls to Three Modes (#16759)

* 🔱 feat: Simplify Steering Controls to Three Modes

* Preserve Admitted Artifacts During Interrupts

* Preserve Result Admission Across Interrupts

* Gate Interrupt for Provider-Hosted Tools

* Match Interrupt Hints to Availability

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-10-05 06:46:59 -04:00 • committed by GitHub
parent 82cde522f2
commit d55dbc3bd8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
30 changed files with 1248 additions and 349 deletions

View file

@ -5,7 +5,6 @@ import type { ChatSettings } from '~/hooks/Chat/contract';
export const defaultChatSettings: ChatSettings = {
duringRunDefaultAction: 'steer',
setDuringRunDefaultAction: () => undefined,
steerInterruptsByDefault: false,
resetVisibleArtifacts: () => undefined,
saveDrafts: true,
isTemporary: false,

View file

@ -448,18 +448,16 @@ const ChatForm = memo(function ChatForm({
return () => publishRewake(null);
}, [publishRewake, steeringRewakeDrain]);
/** ⌘/Ctrl+Enter = the non-default during-run action, ⌥/Alt+Enter =
* interrupt & send (discards the answer), ⌘/Ctrl+Shift+Enter = interrupt &
* steer (keeps it): all counterparts of Enter's `submitDuringRun`. */
/** Ctrl/Cmd+Enter selects the alternate; both interrupt chords use the same mode. */
const handleDuringRunModifier = useCallback(
(kind: 'other' | 'interrupt' | 'preempt') => {
const text = methods.getValues('text');
let consumed = false;
if (kind === 'interrupt') {
consumed = steering.interruptAndSend(text);
consumed = steering.interruptSteer(text);
} else if (kind === 'preempt') {
consumed = steering.interruptSteer(text);
} else if (steering.effectiveAction === 'steer') {
} else if (steering.effectiveAction !== 'queue') {
consumed = steering.queueFromComposer(text);
} else {
consumed = steering.steerFromComposer(text);
@ -1052,7 +1050,6 @@ const ChatForm = memo(function ChatForm({
isSubmitting={isSubmitting}
duringRunActive={steering.duringRunActive}
canControlGeneration={steering.canControlGeneration}
steerInterruptsByDefault={steering.steerInterruptsByDefault}
duringRunAction={steering.effectiveAction}
/* A staged reasoning choice forces the message to queue, and the
send-now chord then queues too; do not advertise it. */

View file

@ -1,6 +1,6 @@
import React, { forwardRef, useMemo, useRef } from 'react';
import { useWatch } from 'react-hook-form';
import { Zap, Clock, OctagonPause, ZapOff } from 'lucide-react';
import { Zap, Clock, ZapOff } from 'lucide-react';
import { composerSubmitClasses, SendActions, SendIcon } from '@librechat/client';
import type { SendAction } from '@librechat/client';
import type { Control } from 'react-hook-form';
@ -14,6 +14,12 @@ import { useLocalize } from '~/hooks';
* surface that can submit more than one way — see `SendActions`. */
type ActionRow = SendAction;
const ACTION_LABELS = {
steer: 'com_ui_steer_send',
interrupt: 'com_ui_interrupt_steer',
queue: 'com_ui_queue_send',
} as const;
type DuringRunSendButtonProps = {
control: Control<{ text: string }>;
steering: SteeringControls;
@ -26,17 +32,7 @@ type DuringRunSendButtonProps = {
enterToSend: boolean;
};
/**
* The send button while a run is generating: it takes over the send/stop slot
* (and `submitButtonRef`, so Enter's synthetic click routes here) whenever the
* composer holds text: submitting steers or queues per the effective action.
* Hovering it reveals the full action list with its shortcuts: steer, queue
* (⌘/Ctrl+Enter routes to the non-default action), interrupt & steer
* (⌘/Ctrl+Shift+Enter — requests an earlier safe point when a conversation
* exists, otherwise stops and sends a new turn), and
* interrupt & send (⌥/Alt+Enter — discards the answer and starts over).
* Clearing the composer restores the Stop button.
*/
/** The active mode owns submission; the menu overrides it for one message. */
const DuringRunSendButton = React.memo(
forwardRef((props: DuringRunSendButtonProps, ref: React.ForwardedRef<HTMLButtonElement>) => {
const localize = useLocalize();
@ -44,7 +40,6 @@ const DuringRunSendButton = React.memo(
const { steering, enterToSend } = props;
const disabledRef = useRef(props.disabled);
disabledRef.current = props.disabled;
const { steerInterruptsByDefault } = steering;
const data = useWatch({ control: props.control });
const content = data?.text?.trim();
const primary = steering.effectiveAction;
@ -85,14 +80,6 @@ const DuringRunSendButton = React.memo(
};
}, [enterToSend, shortcutsEnabled, submitOverride, yieldedChords]);
/**
* With the preference on, plain Enter routes through `submitDuringRun`,
* which preempts. The hint has to follow it: leaving ⏎ on the ordinary
* Steer row would advertise a key that does something else, and that row
* deliberately stays non-preempting when CLICKED. No key reaches it in
* this mode, so it shows none.
*/
const enterInterrupts = primary === 'steer' && steerInterruptsByDefault;
/** The chord that submits the default action, if any still does. */
let submitHint: string | undefined;
if (verdicts.plainEnter === 'submit') {
@ -102,7 +89,7 @@ const DuringRunSendButton = React.memo(
}
const alternateHint = verdicts.modEnter === 'other' ? modEnter : undefined;
let interruptSteerKbd: string | undefined;
if (enterInterrupts && submitHint != null) {
if (primary === 'interrupt' && submitHint != null) {
interruptSteerKbd = submitHint;
} else if (verdicts.modShiftEnter === 'preempt') {
interruptSteerKbd = modShiftEnter;
@ -121,9 +108,9 @@ const DuringRunSendButton = React.memo(
}
};
let steerKbd: string | undefined = alternateHint;
let steerKbd: string | undefined = primary === 'queue' ? alternateHint : undefined;
if (primary === 'steer') {
steerKbd = enterInterrupts ? undefined : submitHint;
steerKbd = submitHint;
}
const steerRow: ActionRow = {
@ -143,34 +130,24 @@ const DuringRunSendButton = React.memo(
disabled: props.disabled,
onClick: () => runAction((text) => steering.queueFromComposer(text)),
};
/** When steering is available, keeps visible text; a new chat instead hard-stops. */
/** Interrupt never becomes a stop-and-send fallback. */
const interruptSteerRow: ActionRow = {
key: 'interrupt-steer',
label: localize(
props.isNewConversation ? 'com_ui_steer_first_turn_stop' : 'com_ui_interrupt_steer',
),
label: localize('com_ui_interrupt_steer'),
kbd: interruptSteerKbd,
icon: <ZapOff className="text-status-warning h-4 w-4" aria-hidden="true" />,
disabled:
props.disabled ||
steering.pausedOnApproval ||
!steering.canControlGeneration ||
!steering.canSteer ||
steering.pendingReasoningOverride != null,
onClick: () => runAction((text) => steering.interruptSteer(text)),
};
const interruptRow: ActionRow = {
key: 'interrupt',
label: localize('com_ui_interrupt_send'),
kbd: verdicts.altEnter === 'interrupt' ? altEnter : undefined,
icon: <OctagonPause className="text-status-error h-4 w-4" aria-hidden="true" />,
disabled: props.disabled || !steering.canControlGeneration,
onClick: () => runAction((text) => steering.interruptAndSend(text)),
};
const rows = primary === 'steer' ? [steerRow, queueRow] : [queueRow, steerRow];
rows.push(interruptSteerRow, interruptRow);
const label =
primary === 'steer' ? localize('com_ui_steer_send') : localize('com_ui_queue_send');
if (interruptSteerKbd == null && verdicts.altEnter === 'interrupt') {
interruptSteerRow.kbd = altEnter;
}
const rows = [steerRow, interruptSteerRow, queueRow];
const label = localize(ACTION_LABELS[primary]);
return (
<SendActions

View file

@ -41,18 +41,19 @@ const steeringStub = ({
canSteer = true,
canControlGeneration = true,
steerInterruptsByDefault = false,
}: StubOptions & { steerInterruptsByDefault?: boolean }) =>
({
effectiveAction: canSteer ? 'steer' : 'queue',
}: StubOptions & { steerInterruptsByDefault?: boolean }) => {
const preferredAction = steerInterruptsByDefault ? 'interrupt' : 'steer';
return {
effectiveAction: canSteer ? preferredAction : 'queue',
canSteer,
canControlGeneration,
pausedOnApproval,
steerInterruptsByDefault,
interruptSteer: mockInterruptSteer,
steerFromComposer: mockSteerFromComposer,
queueFromComposer: mockQueueFromComposer,
interruptAndSend: mockInterruptAndSend,
}) as unknown as SteeringControls;
} as unknown as SteeringControls;
};
function Harness({
steering,
@ -110,9 +111,7 @@ function openMenu(options: MenuOptions = {}) {
/>
</RecoilRoot>,
);
expect(
screen.getByText(isNewConversation ? 'com_ui_steer_first_turn_stop' : 'com_ui_interrupt_steer'),
).toBeInTheDocument();
expect(screen.getByText('com_ui_interrupt_steer')).toBeInTheDocument();
}
beforeEach(() => {
@ -128,12 +127,7 @@ describe('DuringRunSendButton — external hold', () => {
</RecoilRoot>
);
const view = render(frame(false));
const labels = [
'com_ui_steer',
'com_ui_queue',
'com_ui_interrupt_steer',
'com_ui_interrupt_send',
];
const labels = ['com_ui_steer', 'com_ui_queue', 'com_ui_interrupt_steer'];
view.rerender(frame(true));
expect(screen.getByTestId('during-run-send-button')).toBeDisabled();
for (const label of labels) {
@ -173,22 +167,13 @@ describe('DuringRunSendButton — Interrupt & steer availability', () => {
expect(mockOnConsumed).not.toHaveBeenCalled();
});
/**
* Guards the gate against being "simplified" to `!canSteer` like the steer
* row above it. `canSteer` is also false before a conversation exists, where
* `interruptSteer` deliberately falls back to interrupt & send — disabling
* the row there would make it dead for the whole first turn.
*/
test('labels the first-response fallback as stop and send without changing its action', () => {
openMenu({ pausedOnApproval: false, canSteer: false, isNewConversation: true });
expect(screen.queryByText('com_ui_interrupt_steer')).not.toBeInTheDocument();
const row = screen.getByText('com_ui_steer_first_turn_stop').closest('button');
expect(row).toHaveAttribute('aria-disabled', 'false');
test('keeps Interrupt disabled until the first conversation can be steered', () => {
openMenu({ canSteer: false, isNewConversation: true });
const row = screen.getByText('com_ui_interrupt_steer').closest('button');
expect(row).toHaveAttribute('aria-disabled', 'true');
fireEvent.click(row as HTMLButtonElement);
expect(mockInterruptSteer).toHaveBeenCalledWith(TEXT);
expect(mockOnConsumed).toHaveBeenCalled();
expect(mockInterruptSteer).not.toHaveBeenCalled();
expect(mockOnConsumed).not.toHaveBeenCalled();
});
test('the ordinary Steer row stays gated on canSteer', () => {
@ -212,10 +197,6 @@ describe('DuringRunSendButton — Interrupt & steer availability', () => {
'aria-disabled',
'true',
);
expect(screen.getByText('com_ui_interrupt_send').closest('button')).toHaveAttribute(
'aria-disabled',
'true',
);
const queue = screen.getByText('com_ui_queue').closest('button') as HTMLButtonElement;
expect(queue).toHaveAttribute('aria-disabled', 'false');
@ -280,7 +261,7 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
expect(kbdFor('com_ui_steer')).toBe('⏎');
expect(kbdFor('com_ui_queue')).toBe('Ctrl ⏎');
expect(kbdFor('com_ui_interrupt_steer')).toBe('Ctrl ⇧ ⏎');
expect(kbdFor('com_ui_interrupt_send')).toBe('Alt ⏎');
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
});
test('drops a hint whose chord is rebound to a global shortcut', () => {
@ -290,8 +271,8 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
focusSearch: { mac: 'Meta+Shift+Enter', other: 'Ctrl+Shift+Enter' },
},
});
expect(kbdFor('com_ui_interrupt_steer')).toBeNull();
expect(kbdFor('com_ui_interrupt_send')).toBe('Alt ⏎');
expect(kbdFor('com_ui_interrupt_steer')).toBe('Alt ⏎');
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
expect(kbdFor('com_ui_queue')).toBe('Ctrl ⏎');
});
@ -302,7 +283,7 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
submitMessage: { mac: 'Alt+Enter', other: 'Alt+Enter' },
},
});
expect(kbdFor('com_ui_interrupt_send')).toBeNull();
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
expect(kbdFor('com_ui_steer')).toBe('⏎');
expect(kbdFor('com_ui_interrupt_steer')).toBe('Ctrl ⇧ ⏎');
});
@ -313,7 +294,7 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
expect(kbdFor('com_ui_interrupt_steer')).toBeNull();
/** The disabled Steer row drops its alternate-action hint the same way. */
expect(kbdFor('com_ui_steer')).toBeNull();
expect(kbdFor('com_ui_interrupt_send')).toBe('Alt ⏎');
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
});
test('moves the default-action hint to Ctrl+Enter when Enter-to-send is off', () => {
@ -322,7 +303,7 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
expect(kbdFor('com_ui_steer')).toBe('Ctrl ⏎');
expect(kbdFor('com_ui_queue')).toBeNull();
expect(kbdFor('com_ui_interrupt_steer')).toBe('Ctrl ⇧ ⏎');
expect(kbdFor('com_ui_interrupt_send')).toBe('Alt ⏎');
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
});
test('keeps plain Enter but hides shortcut hints when shortcuts are disabled', () => {
@ -330,6 +311,18 @@ describe('DuringRunSendButton — hints follow the effective bindings', () => {
expect(kbdFor('com_ui_steer')).toBe('⏎');
expect(kbdFor('com_ui_queue')).toBeNull();
expect(kbdFor('com_ui_interrupt_steer')).toBeNull();
expect(kbdFor('com_ui_interrupt_send')).toBeNull();
expect(screen.queryByText('com_ui_interrupt_send')).not.toBeInTheDocument();
});
});
test('exposes exactly three modes in a stable order', () => {
openMenu();
const rows = screen
.getAllByRole('button')
.filter((button) => button.getAttribute('type') === 'button');
expect(rows.map((row) => row.textContent?.replace(/Ctrl.*|Alt.*|⏎.*/g, '').trim())).toEqual([
'com_ui_steer',
'com_ui_interrupt_steer',
'com_ui_queue',
]);
});

View file

@ -286,19 +286,6 @@ export const registry: SettingEntry[] = [
keywords: ['steer', 'queue', 'interrupt', 'generating'],
Component: DuringRunAction,
},
{
id: 'steerInterruptsByDefault',
tab: CHAT,
section: 'sending',
labelKey: 'com_ui_steer_interrupts_default',
keywords: ['steer', 'interrupt', 'preempt', 'generating', 'stop'],
Component: toggleControl({
stateAtom: store.steerInterruptsByDefault,
localizationKey: 'com_ui_steer_interrupts_default',
switchId: 'steerInterruptsByDefault',
hoverCardText: 'com_ui_steer_interrupts_default_info',
}),
},
{
id: 'saveDrafts',
tab: CHAT,

View file

@ -0,0 +1,28 @@
import { Provider, createStore } from 'jotai';
import { render, waitFor } from '@testing-library/react';
import { clickDropdown, flushDropdownEffects } from 'test/dropdown';
import { duringRunActionAtom } from '~/store/duringRun';
import DuringRunAction from './DuringRunAction';
jest.mock('~/hooks', () => ({ useLocalize: () => (key: string) => key }));
it('offers three defaults and persists Interrupt', async () => {
const store = createStore();
store.set(duringRunActionAtom, 'steer');
const { getByText, getByTestId, queryByRole } = render(
<Provider store={store}>
<DuringRunAction />
</Provider>,
);
const selector = getByTestId('duringRunAction');
expect(selector).toHaveTextContent('com_ui_steer');
await clickDropdown(selector);
expect(getByText('com_ui_queue')).toBeInTheDocument();
expect(queryByRole('switch')).not.toBeInTheDocument();
await clickDropdown(getByText('com_ui_interrupt_steer'));
await waitFor(() => expect(selector).toHaveTextContent('com_ui_interrupt_steer'));
expect(store.get(duringRunActionAtom)).toBe('interrupt');
expect(JSON.parse(localStorage.getItem('duringRunAction') ?? 'null')).toBe('interrupt');
await flushDropdownEffects();
localStorage.clear();
});

View file

@ -1,44 +1,34 @@
import React from 'react';
import { useRecoilState } from 'recoil';
import { Button, InfoHoverCard, ESide } from '@librechat/client';
import { useAtom } from 'jotai';
import { Dropdown, InfoHoverCard, ESide } from '@librechat/client';
import { duringRunActionAtom } from '~/store/duringRun';
import { useLocalize } from '~/hooks';
import store from '~/store';
/**
* Toggles what Enter does while a run is generating: steer (inject the
* message into the live run at the next tool boundary) or queue (send it as a
* normal follow-up once the run finishes). The composer's during-run menu can
* still override per send.
*/
const DuringRunAction = () => {
const [action, setAction] = useRecoilState(store.duringRunDefaultAction);
export default function DuringRunAction() {
const [action, setAction] = useAtom(duringRunActionAtom);
const localize = useLocalize();
const toggle = () => {
setAction((prev) => (prev === 'steer' ? 'queue' : 'steer'));
};
const label =
action === 'steer'
? localize('com_nav_during_run_action_steer')
: localize('com_nav_during_run_action_queue');
const labelId = 'during-run-action-label';
return (
<div className="flex items-center justify-between">
<div className="flex flex-wrap items-center justify-between gap-2">
<div className="flex items-center space-x-2">
<span id="during-run-action-label">{localize('com_nav_during_run_action')}</span>
<span id={labelId}>{localize('com_nav_during_run_action')}</span>
<InfoHoverCard side={ESide.Bottom} text={localize('com_nav_info_during_run_action')} />
</div>
<Button
variant="outline"
aria-labelledby="during-run-action-label"
onClick={toggle}
data-testid="duringRunAction"
>
{label}
</Button>
<Dropdown
value={action}
options={[
{ value: 'steer', label: localize('com_ui_steer') },
{ value: 'interrupt', label: localize('com_ui_interrupt_steer') },
{ value: 'queue', label: localize('com_ui_queue') },
]}
onChange={(value) => {
if (value === 'steer' || value === 'interrupt' || value === 'queue') setAction(value);
}}
className="z-50"
sizeClasses="z-50"
testId="duringRunAction"
aria-labelledby={labelId}
/>
</div>
);
};
export default DuringRunAction;
}

View file

@ -38,7 +38,9 @@ import { recoveryDispositionsFamily } from '~/components/Chat/Steering/recovery'
import { claimQueuedIntent, releaseQueuedIntent } from '~/utils/queueIntent';
import useUpdateFiles from '~/hooks/Files/useUpdateFiles';
import ChatSettingsProvider from '~/routes/ChatSettings';
import { duringRunActionAtom } from '~/store/duringRun';
import { applyPendingAction } from '~/utils/approval';
import English from '~/locales/en/translation.json';
import useQueueDrain from '../useQueueDrain';
import store from '~/store';
@ -204,6 +206,7 @@ beforeEach(() => resetQueueFamilies());
describe('useSteering', () => {
beforeEach(() => {
getDefaultStore().set(duringRunActionAtom, 'steer');
getDefaultStore().set(recoveryDispositionsFamily(CONVO_ID), {});
jest.clearAllMocks();
mockApprovalMode = undefined;
@ -479,8 +482,8 @@ describe('useSteering', () => {
});
it('honors the queue preference while keeping the steer override available', () => {
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'queue');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'queue');
});
expect(result.current.effectiveAction).toBe('queue');
// The per-send menu can still override to steer: availability is
@ -490,8 +493,8 @@ describe('useSteering', () => {
it('degrades to queue without a real conversation id', () => {
// Explicitly request steer so this verifies the missing-id fallback to queue.
const { result } = setup({ conversationId: Constants.NEW_CONVO as string }, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setup({ conversationId: Constants.NEW_CONVO as string }, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
expect(result.current.effectiveAction).toBe('queue');
});
@ -515,8 +518,8 @@ describe('useSteering', () => {
} as unknown as TMessage,
];
// Explicitly request steer so this verifies the pause fallback to queue.
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
expect(result.current.pausedOnApproval).toBe(true);
expect(result.current.effectiveAction).toBe('queue');
@ -2184,8 +2187,8 @@ describe('useSteering', () => {
describe('submitDuringRun', () => {
it('routes to the steer POST with an optimistic sending chip', () => {
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
let consumed = false;
act(() => {
@ -2203,8 +2206,8 @@ describe('useSteering', () => {
});
it('routes to the client queue when the preference is queue', () => {
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'queue');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'queue');
});
act(() => {
result.current.submitDuringRun('after the run');
@ -2214,8 +2217,8 @@ describe('useSteering', () => {
it('ignores empty submissions', () => {
// Explicitly request steer so blank-text validation exercises the steer path.
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
let consumed = true;
act(() => {
@ -2339,7 +2342,7 @@ describe('useSteering', () => {
* a real conversationId. Without this fallback the always-visible button
* would be dead for the whole first turn.
*/
it('falls back to interruptAndSend before a conversation exists', () => {
it('refuses Interrupt before a conversation exists without aborting it', () => {
const { result, stopGenerating } = setup({
conversationId: Constants.NEW_CONVO as string,
});
@ -2347,9 +2350,9 @@ describe('useSteering', () => {
act(() => {
consumed = result.current.interruptSteer('turn one interrupt');
});
expect(consumed).toBe(true);
expect(consumed).toBe(false);
expect(mockMutate).not.toHaveBeenCalled();
expect(stopGenerating).toHaveBeenCalled();
expect(stopGenerating).not.toHaveBeenCalled();
});
it('refuses empty text without touching the run', () => {
@ -2403,8 +2406,8 @@ describe('useSteering', () => {
* non-preempting, or they become indistinguishable from Interrupt & steer.
*/
it('leaves the explicit Steer action non-preempting even with the preference on', () => {
const { result } = setup({}, ({ set }) => {
set(store.steerInterruptsByDefault, true);
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'interrupt');
});
act(() => {
result.current.steerFromComposer('explicit steer row');
@ -2419,8 +2422,8 @@ describe('useSteering', () => {
thread's pending block renders; its own spec covers the preempt carry. */
it('an ordinary steer does not preempt by default', () => {
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
act(() => {
result.current.submitDuringRun('just steer');
@ -2431,10 +2434,10 @@ describe('useSteering', () => {
);
});
it('steerInterruptsByDefault makes the default Enter route preempt', () => {
const { result } = setup({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
set(store.steerInterruptsByDefault, true);
it('the Interrupt default makes Enter preempt', () => {
const { result } = setup({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
getDefaultStore().set(duringRunActionAtom, 'interrupt');
});
act(() => {
result.current.submitDuringRun('enter should interrupt');
@ -2467,6 +2470,10 @@ describe('useSteering', () => {
expect.objectContaining({ preempt: true }),
expect.anything(),
);
expect(mockShowToast).toHaveBeenCalledWith({
message: English.com_ui_steer_preempt_unsupported,
status: 'warning',
});
});
it('serializes rapid steer POSTs in submission order', () => {
@ -3474,8 +3481,8 @@ describe('useSteering', () => {
});
it('sendQueuedNow steers whenever steering is available, even under the queue preference', () => {
const { result } = setupWithState({}, ({ set }) => {
set(store.duringRunDefaultAction, 'queue');
const { result } = setupWithState({}, () => {
getDefaultStore().set(duringRunActionAtom, 'queue');
});
act(() => {
result.current.steering.enqueue('send me now');
@ -3774,8 +3781,8 @@ describe('useSteering', () => {
}
it('steers with the composer attachments as one unit', () => {
const { result, setFiles } = setupWithFiles({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result, setFiles } = setupWithFiles({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
let consumed = false;
act(() => {
@ -3931,8 +3938,8 @@ describe('useSteering', () => {
// Seed 'steer' so this covers steerFromComposer's own filesLoading
// guard; the queue-path guard is covered separately (queueFromComposer
// is exercised directly with filesLoading in the composer-draft tests).
const { result } = setupWithFiles({ filesLoading: true }, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setupWithFiles({ filesLoading: true }, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
let consumed = true;
act(() => {
@ -4051,8 +4058,8 @@ describe('useSteering', () => {
});
it('does not mark usage on the steer path (the 202 already marked)', () => {
const { result } = setupWithFiles({}, ({ set }) => {
set(store.duringRunDefaultAction, 'steer');
const { result } = setupWithFiles({}, () => {
getDefaultStore().set(duringRunActionAtom, 'steer');
});
act(() => {
result.current.steering.submitDuringRun('steer with media');

View file

@ -168,7 +168,7 @@ export type AddedChatContract = {
};
/** Composer action while a run is in flight: fold the text into the run, or queue a new turn. */
export type DuringRunAction = 'steer' | 'queue';
export type DuringRunAction = 'steer' | 'interrupt' | 'queue';
/**
* App-global preferences the chat reads but does not own. The host supplies them, so the chat
@ -180,8 +180,6 @@ export type ChatSettings = {
/** Default composer action while a run is in flight. */
duringRunDefaultAction: DuringRunAction;
setDuringRunDefaultAction: (action: DuringRunAction) => void;
/** Whether a steer interrupts the running step instead of waiting for the next one. */
steerInterruptsByDefault: boolean;
/** Closes the artifacts panel, called when the active conversation changes. */
resetVisibleArtifacts: () => void;
/** Whether composer text and attachments are kept as drafts across navigation. */

View file

@ -609,11 +609,8 @@ export default function useSteering({
const { mutate: markFilesUsage } = useMarkFilesUsageMutation();
const { mutate: enqueueAgentQueuedTurn } = useEnqueueAgentQueuedTurnMutation();
const { mutateAsync: cancelAgentQueuedTurn } = useCancelAgentQueuedTurnMutation();
const {
duringRunDefaultAction: defaultAction,
setDuringRunDefaultAction: setDefaultAction,
steerInterruptsByDefault,
} = useChatSettings();
const { duringRunDefaultAction: defaultAction, setDuringRunDefaultAction: setDefaultAction } =
useChatSettings();
const { selected: codeApprovalMode } = useCodeApprovalMode(conversation, addedConversation);
const endpoint = conversation?.endpointType ?? conversation?.endpoint;
@ -1970,10 +1967,18 @@ export default function useSteering({
}
return;
}
/** The server's echo is authoritative: a deployment whose SDK
* cannot seal mid-stream still queues the steer and answers
* `preempt: false`, which relabels the chip to the ordinary
* wording instead of surfacing an error. */
/** Unsupported runs retain the words as Steer, but never silently
* claim to have requested tool cancellation. */
if (
preempt &&
response.preempt !== true &&
visibleConversationRef.current === conversationId
) {
showToast({
message: localize('com_ui_steer_preempt_unsupported'),
status: 'warning',
});
}
const acknowledged = {
steerId: response.steerId,
clientSteerId: localId,
@ -2533,25 +2538,7 @@ export default function useSteering({
],
);
/**
* Interrupt & steer: the same POST, queue, chip lifecycle and degradation
* ladder as an ordinary steer: the only difference is that the server asks
* the generating replica to seal its model stream at the next
* provider-safe boundary instead of waiting for a tool step. The partial
* answer is kept and generation resumes in the same message.
*
* Falls back to `interruptAndSend` ONLY before a conversation exists:
* steering needs a server-side job, so `submitSteer` hard-refuses without a
* real conversationId, and an always-visible button would otherwise be dead
* for the entire first turn, exactly when a user most wants to stop a long
* answer.
*
* A run paused on tool approval refuses outright instead. `canSteer` is
* false there too, but routing that into `interruptAndSend` would hard-abort
* the run and discard the partial answer: the exact opposite of what this
* action promises. The standalone button is disabled while paused; the
* keyboard and hovercard paths reach here, so the guard lives here.
*/
/** Preempt the active step and continue the same response with the message. */
const interruptSteer = useCallback(
(text: string): boolean => {
const trimmed = text.trim();
@ -2560,7 +2547,8 @@ export default function useSteering({
trimmed.length === 0 ||
filesLoading ||
pausedOnApproval ||
!canControlGeneration
!canControlGeneration ||
!hasRealConvoId
) {
return false;
}
@ -2573,9 +2561,6 @@ export default function useSteering({
if (pendingReasoningOverride != null) {
return false;
}
if (!hasRealConvoId) {
return interruptAndSend(trimmed);
}
const consumed = submitSteer(trimmed, takeComposerFiles(), takeComposerQuotes(), {
preempt: true,
});
@ -2590,7 +2575,6 @@ export default function useSteering({
canControlGeneration,
hasRealConvoId,
pendingReasoningOverride,
interruptAndSend,
takeComposerFiles,
takeComposerQuotes,
takeComposerDraft,
@ -2604,21 +2588,15 @@ export default function useSteering({
if (composerDisabledRef.current || !duringRunActive) {
return false;
}
if (effectiveAction === 'interrupt') {
return interruptSteer(text);
}
if (effectiveAction === 'steer') {
/** Only the DEFAULT route honours the preference: the explicit Steer
* row and the Ctrl/Cmd+Enter alternate stay non-preempting, or they
* would become indistinguishable from Interrupt & steer. */
return steerFromComposer(text, steerInterruptsByDefault);
return steerFromComposer(text);
}
return queueFromComposer(text);
},
[
duringRunActive,
effectiveAction,
steerInterruptsByDefault,
steerFromComposer,
queueFromComposer,
],
[duringRunActive, effectiveAction, interruptSteer, steerFromComposer, queueFromComposer],
);
/** Memoized so consumers like `memo(Bar)` and `memo(Queue)` can bail on the
@ -2633,7 +2611,6 @@ export default function useSteering({
canSendQueuedNow,
effectiveAction,
defaultAction,
steerInterruptsByDefault,
pendingReasoningOverride,
pausedOnApproval,
setDefaultAction,
@ -2666,7 +2643,6 @@ export default function useSteering({
duringRunActive,
canSendQueuedNow,
effectiveAction,
steerInterruptsByDefault,
defaultAction,
pendingReasoningOverride,
pausedOnApproval,

View file

@ -84,6 +84,31 @@ describe('composeHint', () => {
expect(hint(state, false)).toContain('Alt+⏎');
});
it.each([
['tool approval', true, true],
['staged reasoning', true, false],
['tool approval with Enter inserting a newline', false, false],
['staged reasoning with Enter inserting a newline', false, true],
])('omits unavailable Interrupt during %s', (_reason, enterToSend, isMac) => {
const result = hint(
{
duringRunActive: true,
hasText: true,
isSubmitting: true,
canSteer: false,
duringRunAction: 'queue',
enterToSend,
},
isMac,
);
expect(result).not.toContain('com_ui_composer_hint_interrupt');
expect(result).not.toContain('com_ui_composer_hint_send_now');
expect(result).not.toContain(isMac ? '⌥⏎' : 'Alt+⏎');
expect(result).toContain(
enterToSend ? 'com_ui_composer_hint_queue_default' : 'com_ui_composer_hint_queue_verb',
);
});
it('falls back to the running copy when the modifiers have no text to act on', () => {
expect(hint({ duringRunActive: true, hasText: false, isSubmitting: true })).toBe(
'com_ui_composer_hint_running',
@ -211,3 +236,10 @@ describe('composeHint', () => {
});
});
});
it('names Interrupt as the default while leaving Queue as the alternate', () => {
const result = hint({ duringRunActive: true, hasText: true, duringRunAction: 'interrupt' });
expect(result).toContain('com_ui_interrupt_steer');
expect(result).toContain('com_ui_composer_hint_queue');
expect(result).not.toContain('com_ui_composer_hint_steer');
});

View file

@ -25,8 +25,7 @@ export interface ComposerHintState {
* Queueing is local, so it works throughout. */
canControlGeneration: boolean;
/** Which action Enter takes during a run, per the effective setting. */
duringRunAction: 'steer' | 'queue';
steerInterruptsByDefault?: boolean;
duringRunAction: 'steer' | 'interrupt' | 'queue';
/** Whether the steer route can accept input right now. A paused tool
* approval forces the effective action to queue and refuses steers, so the
* live-send alternate must not be advertised through it. */
@ -103,7 +102,7 @@ export function composeHint(
alternate is named only while the stock chord still works. */
const sendChord = sendBinding.customized ? sendBinding.display : mod;
const isSteer = state.duringRunAction === 'steer';
const interruptByDefault = isSteer && state.steerInterruptsByDefault === true;
const interruptByDefault = state.duringRunAction === 'interrupt';
/* The default action and the live submit route share this preference:
naming plain Enter as Steer while it preempts is materially misleading. */
let defaultAction: string;
@ -114,9 +113,10 @@ export function composeHint(
} else {
defaultAction = localize('com_ui_composer_hint_queue_default');
}
const alternateAction = isSteer
? `${mod} ${localize('com_ui_composer_hint_queue')}`
: `${mod} ${localize('com_ui_composer_hint_send_now')}`;
const alternateAction =
state.duringRunAction !== 'queue'
? `${mod} ${localize('com_ui_composer_hint_queue')}`
: `${mod} ${localize('com_ui_composer_hint_send_now')}`;
let chordVerb: Parameters<typeof localize>[0];
if (interruptByDefault) {
chordVerb = 'com_ui_interrupt_steer';
@ -130,7 +130,7 @@ export function composeHint(
parts.push(defaultAction);
/* The queue alternate is local and always lands; the send-now alternate
rides the steer route, which a paused approval refuses. */
if (!sendBinding.customized && (isSteer || state.canSteer)) {
if (!sendBinding.customized && (state.duringRunAction !== 'queue' || state.canSteer)) {
parts.push(alternateAction);
}
} else if (sendChord) {
@ -147,12 +147,12 @@ export function composeHint(
};
}
/* The interrupt chord is named only while the keydown resolver still hands
it back: a `submitMessage` rebound to Alt+Enter, a chord yielded to a
global shortcut, or shortcuts disabled altogether each make the key do
something else, and advertising it is worse than omitting it. */
const text = altEnterInterrupt
? [...parts, `${alt} ${localize('com_ui_composer_hint_interrupt')}`].join(SEPARATOR)
: parts.join(SEPARATOR);
it back and the run accepts steering. Approval pauses and staged reasoning
refuse Interrupt just like the disabled menu row. */
const text =
altEnterInterrupt && state.canSteer
? [...parts, `${alt} ${localize('com_ui_composer_hint_interrupt')}`].join(SEPARATOR)
: parts.join(SEPARATOR);
return {
text: text || localize('com_ui_composer_hint_running'),
kind: 'state',

View file

@ -806,8 +806,6 @@
"com_nav_delete_data_info": "All your data will be deleted.",
"com_nav_delete_warning": "WARNING: This will permanently delete your account.",
"com_nav_during_run_action": "While generating, Enter will",
"com_nav_during_run_action_queue": "Queue for after",
"com_nav_during_run_action_steer": "Steer the response",
"com_nav_enable_cache_tts": "Enable cache TTS",
"com_nav_enable_cloud_browser_voice": "Use cloud-based voices",
"com_nav_engine": "Engine",
@ -842,7 +840,7 @@
"com_nav_info_collapse_user_messages": "When enabled, long user messages render collapsed to a preview with a Show more option, so pasted text or code cannot dominate the conversation. The full text stays in the page, ready to copy or search.",
"com_nav_info_copy_rich_text": "When enabled, copying a message also places a formatted version on the clipboard, so headings, lists, tables and code keep their styling when pasted into apps that do not support Markdown, such as Teams, Outlook or Word.",
"com_nav_info_default_temporary_chat": "When enabled, new chats will start with temporary chat mode activated by default. Temporary chats are not saved to your history.",
"com_nav_info_during_run_action": "Choose what Enter does while the assistant responds. \"Steer the response\" usually waits for the next tool step or an end-of-response opportunity. Turn on \"Steer sooner on Enter\" to request an earlier safe point. \"Queue for after\" sends a new turn once the response finishes. The send button lets you choose per message.",
"com_nav_info_during_run_action": "Steer waits for a safe insertion point without cancelling tools or reasoning. Interrupt requests cancellation of active tools and reasoning, then continues with your message. Queue sends a follow-up after the response finishes. Choose per message in the send menu.",
"com_nav_info_enter_to_send": "When enabled, pressing `ENTER` will send your message. When disabled, pressing Enter will add a new line, and you'll need to press `CTRL + ENTER` / `⌘ + ENTER` to send your message.",
"com_nav_info_fork_change_default": "`Visible messages only` includes just the direct path to the selected message. `Include related branches` adds branches along the path. `Include all to/from here` includes all connected messages and branches.",
"com_nav_info_fork_split_target_setting": "When enabled, forking will commence from the target message to the latest message in the conversation, according to the behavior selected.",
@ -1388,7 +1386,7 @@
"com_ui_composer_files_images": "Images",
"com_ui_composer_hint_answer": "Answering. Esc to dismiss",
"com_ui_composer_hint_attach": "+ to attach",
"com_ui_composer_hint_interrupt": "interrupt & send",
"com_ui_composer_hint_interrupt": "interrupt",
"com_ui_composer_hint_mentions": "@ for models",
"com_ui_composer_hint_newline": "for newline",
"com_ui_composer_hint_prompts": "/ for prompts",
@ -1853,9 +1851,8 @@
"com_ui_importing": "Importing",
"com_ui_input": "Input",
"com_ui_instructions": "Instructions",
"com_ui_interrupt_send": "Interrupt & send",
"com_ui_interrupt_steer": "Steer sooner",
"com_ui_interrupt_steer_now": "Steer sooner",
"com_ui_interrupt_steer": "Interrupt",
"com_ui_interrupt_steer_now": "Interrupt now",
"com_ui_invalid_json": "Invalid JSON",
"com_ui_invocation_auto": "Auto",
"com_ui_invocation_auto_info": "The skill is automatically applied by the agent when relevant to the conversation",
@ -2855,20 +2852,17 @@
"com_ui_steer_recovery_held": "Recovery paused",
"com_ui_steer_cancel_failed": "Could not cancel the steering message — it may still reach the agent",
"com_ui_steer_delivered": "Delivered",
"com_ui_steer_delivered_info": "Delivered. Your message can join this response at the next tool step or, when possible, before it finishes.",
"com_ui_steer_delivered_info": "Delivered. Waiting for a safe insertion point after the current tool or reasoning step.",
"com_ui_steer_delivery_unconfirmed": "Delivery unconfirmed",
"com_ui_steer_delivery_uncertain": "Delivery status is unknown; this steering message may still reach the agent",
"com_ui_steer_failed": "Steering failed",
"com_ui_steer_failed_inline": "Couldn't add to this reply",
"com_ui_steer_first_turn_stop": "Stop & send (first response)",
"com_ui_steer_in_flight": "Steering",
"com_ui_steer_in_flight_preempt": "Steer sooner requested",
"com_ui_steer_interrupting_info": "Earlier steering requested. The agent may pause a text reply at a safe point or restart an attempt that has produced only reasoning. Running tools finish first. If it cannot pause, your message waits for the next tool step or an end-of-response opportunity.",
"com_ui_steer_interrupts_default": "Steer sooner on Enter",
"com_ui_steer_interrupts_default_info": "When steering is the default, Enter requests an earlier safe point instead of waiting for the next tool step. Running tools finish first; a thinking-only attempt may restart. Text already shown is kept.",
"com_ui_steer_in_flight_preempt": "Interrupt requested",
"com_ui_steer_interrupting_info": "Cancellation requested for active tools and reasoning. Completed output is kept, and the agent continues with your message. External effects already performed cannot be undone.",
"com_ui_steer_moved_to_queue": "Moved to the queue: it sends when this response finishes",
"com_ui_steer_paused_queued": "The agent is waiting for your review — your message was queued instead",
"com_ui_steer_preempt_unsupported": "This deployment can't steer mid-response. Your message waits for the next tool step or an end-of-response opportunity",
"com_ui_steer_preempt_unsupported": "Interrupt is unavailable for this run, including provider-hosted tools such as native search. Your message remains as Steer and waits for a safe insertion point.",
"com_ui_steer_queued_info": "Sends when this response finishes",
"com_ui_steer_send": "Steer the current response",
"com_ui_steer_sending": "Sending…",

View file

@ -1,18 +1,17 @@
import { useMemo } from 'react';
import { useAtom } from 'jotai';
import { useRecoilState, useRecoilValue, useResetRecoilState } from 'recoil';
import type { ReactNode } from 'react';
import type { ChatSettings } from '~/hooks/Chat/contract';
import { ChatTransportContext, defaultChatTransport } from '~/Providers/ChatTransportContext';
import { ChatSettingsContext } from '~/Providers/ChatSettingsContext';
import { duringRunActionAtom } from '~/store/duringRun';
import store from '~/store';
/** Supplies the chat's app-global preferences from the app's own settings store, and the
* transport its turns run over. */
export default function ChatSettingsProvider({ children }: { children: ReactNode }) {
const [duringRunDefaultAction, setDuringRunDefaultAction] = useRecoilState(
store.duringRunDefaultAction,
);
const steerInterruptsByDefault = useRecoilValue(store.steerInterruptsByDefault);
const [duringRunDefaultAction, setDuringRunDefaultAction] = useAtom(duringRunActionAtom);
const resetVisibleArtifacts = useResetRecoilState(store.visibleArtifacts);
const saveDrafts = useRecoilValue<boolean>(store.saveDrafts);
const [isTemporary, setIsTemporary] = useRecoilState<boolean>(store.isTemporary);
@ -21,7 +20,6 @@ export default function ChatSettingsProvider({ children }: { children: ReactNode
() => ({
duringRunDefaultAction,
setDuringRunDefaultAction,
steerInterruptsByDefault,
resetVisibleArtifacts,
saveDrafts,
isTemporary,
@ -30,7 +28,6 @@ export default function ChatSettingsProvider({ children }: { children: ReactNode
[
duringRunDefaultAction,
setDuringRunDefaultAction,
steerInterruptsByDefault,
resetVisibleArtifacts,
saveDrafts,
isTemporary,

View file

@ -1,7 +1,9 @@
import React from 'react';
import { useAtomValue, getDefaultStore } from 'jotai';
import { act, renderHook } from '@testing-library/react';
import { RecoilRoot, useRecoilValue, type MutableSnapshot } from 'recoil';
import { defaultChatSettings, useChatSettings } from '~/Providers/ChatSettingsContext';
import { duringRunActionAtom } from '~/store/duringRun';
import ChatSettingsProvider from '../ChatSettings';
import store from '~/store';
@ -9,7 +11,7 @@ const renderSettings = (initialize?: (snapshot: MutableSnapshot) => void) =>
renderHook(
() => ({
settings: useChatSettings(),
storedAction: useRecoilValue(store.duringRunDefaultAction),
storedAction: useAtomValue(duringRunActionAtom),
visibleArtifacts: useRecoilValue(store.visibleArtifacts),
}),
{
@ -22,15 +24,14 @@ const renderSettings = (initialize?: (snapshot: MutableSnapshot) => void) =>
);
describe('ChatSettingsProvider', () => {
beforeEach(() => getDefaultStore().set(duringRunActionAtom, 'steer'));
it('supplies the stored preferences to the chat', () => {
const { result } = renderSettings(({ set }) => {
set(store.duringRunDefaultAction, 'queue');
set(store.steerInterruptsByDefault, true);
const { result } = renderSettings(() => {
getDefaultStore().set(duringRunActionAtom, 'interrupt');
});
expect(result.current.settings).toMatchObject({
duringRunDefaultAction: 'queue',
steerInterruptsByDefault: true,
duringRunDefaultAction: 'interrupt',
});
});

View file

@ -0,0 +1,28 @@
import { createStore } from 'jotai';
import { duringRunActionAtom, migrateDuringRunAction } from './duringRun';
describe('during-run preference', () => {
it.each([
['steer', false, 'steer'],
['steer', true, 'interrupt'],
['queue', false, 'queue'],
['queue', true, 'queue'],
['interrupt', false, 'interrupt'],
['invalid', true, 'steer'],
])('migrates %s / %s to %s', (legacy, interrupts, expected) => {
expect(migrateDuringRunAction(legacy, interrupts)).toBe(expected);
});
it('persists each mode without overwriting legacy keys', () => {
localStorage.setItem('duringRunDefaultAction', JSON.stringify('queue'));
localStorage.setItem('steerInterruptsByDefault', JSON.stringify(true));
const store = createStore();
for (const mode of ['steer', 'interrupt', 'queue'] as const) {
store.set(duringRunActionAtom, mode);
expect(JSON.parse(localStorage.getItem('duringRunAction') ?? 'null')).toBe(mode);
}
expect(JSON.parse(localStorage.getItem('duringRunDefaultAction') ?? 'null')).toBe('queue');
expect(JSON.parse(localStorage.getItem('steerInterruptsByDefault') ?? 'null')).toBe(true);
localStorage.clear();
});
});

View file

@ -0,0 +1,23 @@
import { atom } from 'jotai';
import type { DuringRunAction } from '~/hooks/Chat/contract';
import { createStorageAtom, initializeFromStorage } from './jotai-utils';
export function migrateDuringRunAction(action: string, interrupts: boolean): DuringRunAction {
if (action === 'queue') return 'queue';
if (action === 'interrupt' || (action === 'steer' && interrupts)) return 'interrupt';
return 'steer';
}
/** Keep legacy keys untouched so older clients retain their saved behavior. */
const storedAction = createStorageAtom<DuringRunAction>(
'duringRunAction',
migrateDuringRunAction(
initializeFromStorage('duringRunDefaultAction', 'steer'),
initializeFromStorage('steerInterruptsByDefault', false),
),
);
export const duringRunActionAtom = atom(
(get) => migrateDuringRunAction(get(storedAction), false),
(_get, set, action: DuringRunAction) => set(storedAction, action),
);

View file

@ -58,19 +58,6 @@ const localStorageAtoms = {
// Chat settings
enterToSend: atomWithLocalStorage('enterToSend', true),
/** The action Enter uses while a reply is generating. */
duringRunDefaultAction: atomWithLocalStorage<'steer' | 'queue'>(
'duringRunDefaultAction',
'steer',
),
/**
* Whether a steer interrupts generation at the next safe boundary instead of
* waiting for the run's next tool step. Orthogonal to
* `duringRunDefaultAction`: that chooses steer-vs-queue, this chooses how
* soon a steer lands. The composer's interrupt button always interrupts
* regardless — this only governs the default Enter/steer route.
*/
steerInterruptsByDefault: atomWithLocalStorage('steerInterruptsByDefault', false),
maximizeChatSpace: atomWithLocalStorage('maximizeChatSpace', false),
chatDirection: atomWithLocalStorage('chatDirection', 'LTR'),
autoExpandTools: atomWithLocalStorage(LocalStorageKeys.AUTO_EXPAND_TOOLS, false),

View file

@ -50,6 +50,7 @@ const EMPTY_SLOW_REPLY_MARKER = 'E2E_EMPTY_SLOW_REPLY:';
const EMPTY_REPLY_MARKER = 'E2E_EMPTY_REPLY:';
const SLOW_COUNTED_REPLY_MARKER = 'E2E_SLOW_COUNTED_REPLY:';
const STEER_TOOL_REPLY_MARKER = 'E2E_STEER_TOOL_REPLY:';
const INTERRUPT_TOOL_REPLY_MARKER = 'E2E_INTERRUPT_TOOL_REPLY:';
const MCP_APP_MARKER = 'E2E_MCP_APP:';
const MCP_APP_PHASE_MARKER = 'E2E_MCP_APP_PHASE:';
const MCP_LINK_APP_MARKER = 'E2E_MCP_LINK_APP:';
@ -757,9 +758,19 @@ function replyResponses(text) {
* for the user row, then interrupts this whitespace-only stream. */
const emptySlowName = getMarkerValue(text, EMPTY_SLOW_REPLY_MARKER);
if (emptySlowName) {
let invocation = 0;
return {
responses: [' '.repeat(EMPTY_SLOW_REPLY_CHUNKS)],
responses: [''],
sleep: SLOW_CHUNK_DELAY_MS,
resolveInvocation: async (messages) => {
invocation += 1;
return {
response:
invocation === 1
? ' '.repeat(EMPTY_SLOW_REPLY_CHUNKS)
: `E2E empty reply continued ${emptySlowName} ${steerEchoSuffix(messages)}`,
};
},
};
}
@ -1763,6 +1774,39 @@ function activityProseReplyResponses(label, toolNames) {
};
}
function interruptToolReplyResponses(label, toolNames) {
const remember = Array.from(toolNames).find((name) => name.startsWith(STEER_TOOL_NAME_PREFIX));
const slow = Array.from(toolNames).find((name) => name.startsWith(SLOW_ECHO_TOOL_NAME_PREFIX));
if (!remember || !slow) return { responses: ['E2E interrupt tools unavailable'] };
let invocation = 0;
return {
responses: [''],
resolveInvocation: async (messages) => {
invocation += 1;
if (invocation === 1) {
return {
response: `E2E interrupt tools running ${label}`,
toolCalls: [
{
id: `call_interrupt_fast_${label}`,
name: remember,
args: { fact: `completed ${label}` },
type: 'tool_call',
},
{
id: `call_interrupt_slow_${label}`,
name: slow,
args: { text: `late ${label}`, delay_ms: 5000 },
type: 'tool_call',
},
],
};
}
return { response: `E2E interrupt tool reply done ${label} ${steerEchoSuffix(messages)}` };
},
};
}
/**
* A phase whose middle batch holds a failed call beside a slow one: `slow_echo`
* called without its required `text` fails schema validation before the tool
@ -3383,6 +3427,9 @@ function resolveResponses({ graph, messages, text, toolNames }) {
return statefulCodeResponses(statefulCodeOperation, toolNames);
}
const interruptToolLabel = getMarkerValue(text, INTERRUPT_TOOL_REPLY_MARKER);
if (interruptToolLabel) return interruptToolReplyResponses(interruptToolLabel, toolNames);
const steerToolLabel = getMarkerValue(text, STEER_TOOL_REPLY_MARKER);
if (steerToolLabel) {
return steerToolReplyResponses(steerToolLabel, toolNames);

View file

@ -65,6 +65,7 @@ test.describe('composer redesign contracts', () => {
/* The send-now chord would queue as well, so the hint names only the queue. */
await expect(messageInput(page)).toHaveAccessibleDescription(/Enter queues/);
await expect(messageInput(page)).not.toHaveAccessibleDescription(/send now/i);
await expect(messageInput(page)).not.toHaveAccessibleDescription(/interrupt/i);
await page.getByTestId('during-run-send-button').click();
await expect(
page.getByTestId('queued-message-row').filter({ hasText: 'new turn after reasoning' }),

View file

@ -6,16 +6,11 @@ import {
sendMessage,
replyPrompt,
replyText,
MOCK_REPLY_TEXT,
MOCK_ENDPOINTS,
NEW_CHAT_PATH,
} from '../helpers';
/**
* The follow-up queue, its run-end signals and the interrupt-drain flag are chat-owned Jotai
* state. Queueing and draining are covered by the composer-queue scenarios; this one drives the
* interrupt-drain flag through a real stopped run.
*/
/** Interrupt preserves the response instead of draining a separate follow-up. */
const messageInput = (page: Page) => page.getByRole('textbox', { name: 'Message input' });
const duringRunSendButton = (page: Page) => page.getByTestId('during-run-send-button');
@ -46,7 +41,7 @@ test.describe('chat-owned queue state', () => {
});
});
test('interrupt and send stops the run and sends the follow-up next @scenario:interrupt-and-send-drains-the-follow-up', async ({
test('Interrupt continues the current response @scenario:interrupt-and-send-drains-the-follow-up', async ({
page,
}) => {
test.setTimeout(120000);
@ -64,9 +59,10 @@ test.describe('chat-owned queue state', () => {
await typeDuringRun(page, followUp);
await messageInput(page).press('Alt+Enter');
await expect(messageTurns(page)).toHaveCount(6, { timeout: 60000 });
await expect(messageTurns(page).nth(4)).toContainText(followUp);
await expect(messageTurns(page).nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30000 });
await expect(messagesView(page).getByText(`[steers-seen=1] ${followUp}`)).toBeVisible();
await expect(messageTurns(page)).toHaveCount(4);
await expect(messageTurns(page).nth(3)).toContainText(followUp);
await expect(messagesView(page).getByText('chunk-010')).toBeVisible();
await expect(messagesView(page).getByText('chunk-159')).toHaveCount(0);
});
});

View file

@ -5,6 +5,8 @@ import type { Page, Response } from '@playwright/test';
import {
MOCK_ENDPOINTS,
NEW_CHAT_PATH,
getAccessToken,
requestJson,
messagesView,
replyPrompt,
replyText,
@ -79,19 +81,16 @@ async function expectModelContinuation(page: Page, label: string, steerText: str
* a real interrupt rather than relabelling a chip.
*/
test.describe('escalating waiting messages to an interrupt', () => {
/* The composer ships with Enter queueing during a run; escalation rides the
steer route, so pin the during-run default to steering. */
/** Pin Steer so the alternate shortcut queues. */
test.beforeEach(async ({ page }) => {
await page.addInitScript(() => {
localStorage.setItem('duringRunDefaultAction', JSON.stringify('steer'));
localStorage.setItem('duringRunAction', JSON.stringify('steer'));
});
});
/** `steerInterruptsByDefault` is a localStorage preference; the toggle test
* flips it, and a mid-test failure must not leak preempt-by-default into
* the rest of the serial suite. */
/** Reset the mode changed by the selector case. */
test.afterEach(async ({ page }) => {
await page.evaluate(() => window.localStorage.removeItem('steerInterruptsByDefault'));
await page.evaluate(() => window.localStorage.removeItem('duringRunAction'));
});
test('queued row escalates as an interrupt: the message seals mid-stream instead of waiting for run end', async ({
@ -259,10 +258,8 @@ test.describe('escalating waiting messages to an interrupt', () => {
});
}
test('always-interrupt toggle in a waiting row menu makes plain Enter preempt', async ({
page,
}) => {
test.setTimeout(150000);
test('the Interrupt default makes plain Enter preempt', async ({ page }) => {
test.setTimeout(45000);
const label = uniqueLabel('toggle');
const queueText = `Queued while toggling ${label}`;
const steerText = `Enter now interrupts ${label}`;
@ -282,20 +279,16 @@ test.describe('escalating waiting messages to an interrupt', () => {
const row = queuedRows(page).filter({ hasText: queueText });
await expect(row).toBeVisible({ timeout: 10000 });
// The during-run default lives in Settings > Chat as an ordinary switch.
await page.getByTestId('nav-user').click();
await page.getByRole('menuitem', { name: 'Settings' }).click();
await page.getByRole('tab', { name: 'Chat' }).click();
const interruptToggle = page.getByRole('switch', {
name: 'Steer sooner on Enter',
});
await expect(interruptToggle).toBeVisible({ timeout: 5000 });
await interruptToggle.click();
await expect(interruptToggle).toHaveAttribute('aria-checked', 'true');
const mode = page.getByTestId('duringRunAction');
await mode.click();
await page.getByRole('option', { name: 'Interrupt', exact: true }).click();
await expect(mode).toContainText('Interrupt');
await page.keyboard.press('Escape');
// The toggle is live for the SAME run: plain Enter now routes the default
// steer through the preempt path (the 202 carries the armed flag).
// The selected default applies to the current run.
await typeDuringRun(page, steerText);
const [steerResponse] = await Promise.all([
page.waitForResponse(isSteerRequest, { timeout: 15000 }),
@ -312,6 +305,98 @@ test.describe('escalating waiting messages to an interrupt', () => {
await expectModelContinuation(page, label, steerText);
});
test('native-search runs explicitly retain unsupported Interrupt messages as Steer', async ({
page,
}) => {
const label = uniqueLabel('native-search');
const text = `Change direction ${label}`;
await page.goto(NEW_CHAT_PATH);
const token = await getAccessToken(page);
const agent = await requestJson<{ id: string }>(page, {
path: '/api/agents',
token,
method: 'POST',
body: {
name: `Native search ${label}`,
provider: 'Mock Provider A',
model: 'mock-model-a',
model_parameters: { web_search: true },
tools: [],
},
});
try {
await page.goto(`${NEW_CHAT_PATH}?agent_id=${encodeURIComponent(agent.id)}`);
await establishConversation(page, `native-setup-${label}`);
await sendMessage(page, `E2E_SLOW_REPLY:${label}`);
await expect(messagesView(page).getByText('chunk-010')).toBeVisible();
await typeDuringRun(page, text);
const [response] = await Promise.all([
page.waitForResponse(isSteerRequest),
messageInput(page).press('Alt+Enter'),
]);
expect(response.status()).toBe(202);
expect((await response.json()).preempt).toBe(false);
await expect(
page
.getByRole('region', { name: 'Notifications (F8)' })
.getByText(/Interrupt is unavailable for this run/),
).toBeVisible();
if (process.env.E2E_CAPTURE_DIR) {
mkdirSync(process.env.E2E_CAPTURE_DIR, { recursive: true });
await page.screenshot({
path: path.join(process.env.E2E_CAPTURE_DIR, 'native-interrupt-unavailable.png'),
animations: 'disabled',
});
}
const bubble = inFlightSteers(page).filter({ hasText: text });
await expect(bubble.getByTestId('steer-receipt')).toHaveAttribute(
'data-receipt-state',
'delivered',
);
await page.getByTestId('stop-generation-button').click();
} finally {
await requestJson(page, {
path: `/api/agents/${encodeURIComponent(agent.id)}`,
token,
method: 'DELETE',
});
}
});
test('Interrupt cancels a running foreground tool and continues the same response', async ({
page,
}) => {
const label = uniqueLabel('tool-interrupt');
const steerText = `Change direction ${label}`;
await page.goto(NEW_CHAT_PATH);
await selectMockEndpoint(page, { label: 'Mock Provider C', model: 'mock-model-c' });
await establishConversation(page, `tools-${label}`);
await page.getByRole('button', { name: 'Attach and tools' }).click();
const memory = page
.getByRole('dialog', { name: 'Attach and tools' })
.getByRole('button', { name: /^E2E Memory\b/ });
await memory.click();
await page.keyboard.press('Escape');
await sendMessage(page, `E2E_INTERRUPT_TOOL_REPLY:${label}`);
await expect(
messagesView(page).getByText(`E2E interrupt tools running ${label}`),
).toBeVisible();
await typeDuringRun(page, steerText);
const [response] = await Promise.all([
page.waitForResponse(isSteerRequest),
messageInput(page).press('ControlOrMeta+Shift+Enter'),
]);
expect(response.status()).toBe(202);
await expect(messagesView(page).getByText(`[steers-seen=1] ${steerText}`)).toBeVisible();
await messagesView(page)
.getByRole('button', { name: /^Ran 2 actions/ })
.click();
await expect(messagesView(page).getByText(/Cancellation was requested/)).toBeVisible();
await expect(messageTurns(page)).toHaveCount(4);
await page.waitForTimeout(5500);
await expect(messagesView(page).getByText(`E2E slow echo: late ${label}`)).toHaveCount(0);
});
test('the dedicated shortcut escalates the newest waiting steer from the keyboard', async ({
page,
}) => {

View file

@ -679,7 +679,7 @@ test.describe('mid-run steering and queuing', () => {
await expect(followupReply.locator('.agent-turn')).toBeVisible();
});
test('interrupt & send (Alt+Enter) stops the run and auto-sends the text as the next turn', async ({
test('Interrupt (Alt+Enter) keeps completed text and continues the same response', async ({
page,
}) => {
test.setTimeout(120000);
@ -699,23 +699,20 @@ test.describe('mid-run steering and queuing', () => {
await typeDuringRun(page, interruptText);
await messageInput(page).press('Alt+Enter');
// The abort settles and the text auto-sends as the next user turn.
await expect(messageTurns(page)).toHaveCount(6, { timeout: 60000 });
const interruptTurn = messageTurns(page).nth(4);
await expect(interruptTurn).toContainText(interruptText);
await expect(interruptTurn.locator('.user-turn')).toBeVisible();
// The follow-up run streams its response into the LIVE view — no reload.
const freshReply = messageTurns(page).nth(5);
await expect(freshReply).toContainText(MOCK_REPLY_TEXT, { timeout: 30000 });
await expect(freshReply.locator('.agent-turn')).toBeVisible();
await expect(appliedSteerParts(page).filter({ hasText: interruptText })).toHaveCount(1);
await expect(messageTurns(page)).toHaveCount(4);
await expect(messagesView(page).getByText('chunk-010')).toBeVisible();
await expect(messagesView(page).getByText(`[steers-seen=1] ${interruptText}`)).toBeVisible();
await expect(
messagesView(page).getByText(`${SLOW_REPLY_CONTINUATION_TEXT} ${label}`),
).toBeVisible();
// The interrupted response was stopped mid-stream: its final chunk never
// arrived (an uninterrupted slow run always ends with it).
await expect(messagesView(page).getByText(SLOW_REPLY_LAST_CHUNK)).toHaveCount(0);
});
test('interrupt & send drains after a created response with no persistable content', async ({
test('Interrupt restarts a silent attempt and preserves the response parent', async ({
page,
}) => {
test.setTimeout(120000);
@ -754,27 +751,98 @@ test.describe('mid-run steering and queuing', () => {
.toBe(true);
await typeDuringRun(page, interruptText);
const [steerResponse] = await Promise.all([
page.waitForResponse(isSteerRequest),
messageInput(page).press('Alt+Enter'),
]);
expect(steerResponse.status()).toBe(202);
await expect(messagesView(page).getByText(`E2E empty reply continued ${label}`)).toBeVisible();
await expect(messagesView(page).getByText(`[steers-seen=1] ${interruptText}`)).toBeVisible();
await expect(appliedSteerParts(page).filter({ hasText: interruptText })).toHaveCount(1);
await expect(messageTurns(page)).toHaveCount(4);
await expect
.poll(async () => {
const records = await requestJson<PersistedMessage[]>(page, {
path: messagesPath,
token: accessToken,
});
return records.some(
(message) =>
message.isCreatedByUser === false &&
message.unfinished !== true &&
JSON.stringify(message.content).includes(interruptText),
);
})
.toBe(true);
const persisted = await requestJson<PersistedMessage[]>(page, {
path: messagesPath,
token: accessToken,
});
const interruptedUser = persisted.find(
(message) => message.isCreatedByUser === true && message.text === emptyRunPrompt,
);
expect(interruptedUser).toBeTruthy();
const continued = persisted.find(
(message) =>
message.isCreatedByUser === false && message.parentMessageId === interruptedUser?.messageId,
);
expect(continued).toBeTruthy();
expect(continued?.unfinished).not.toBe(true);
expect(JSON.stringify(continued?.content)).toContain(interruptText);
await expect(queuedRows(page)).toHaveCount(0);
});
test('Stop preserves an empty response parent for the next turn', async ({ page }) => {
test.setTimeout(120000);
const label = uniqueLabel('stop-empty');
const emptyRunPrompt = `E2E_EMPTY_SLOW_REPLY:${label}`;
const interruptText = `Interrupt empty follow-up ${label}`;
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
await establishConversation(page, `interrupt-empty-setup-${label}`);
const conversationId = new URL(page.url()).pathname.split('/').pop();
expect(conversationId).toBeTruthy();
const accessToken = await getAccessToken(page);
const messagesPath = `/api/messages/${encodeURIComponent(conversationId as string)}`;
const run = await sendMessage(page, emptyRunPrompt);
expect(run.ok()).toBeTruthy();
/** BaseClient starts its user-row write only after `onStart` emitted
* `created`. Waiting for that row proves the server is in the exact
* created-but-still-whitespace state, without relying on a sleep. */
await expect
.poll(
async () => {
const persisted = await requestJson<PersistedMessage[]>(page, {
path: messagesPath,
token: accessToken,
});
return persisted.some(
(message) => message.isCreatedByUser === true && message.text === emptyRunPrompt,
);
},
{ timeout: 30000 },
)
.toBe(true);
const [abortResponse] = await Promise.all([
page.waitForResponse(
(response) =>
response.request().method() === 'POST' &&
new URL(response.url()).pathname === '/api/agents/chat/abort',
{ timeout: 30000 },
),
messageInput(page).press('Alt+Enter'),
page.getByTestId('stop-generation-button').click(),
]);
expect(abortResponse.ok()).toBeTruthy();
await expect(page.getByTestId('stop-generation-button')).toHaveCount(0);
await sendMessage(page, interruptText);
await expect(messageTurns(page)).toHaveCount(6);
await expect(messageTurns(page).nth(5)).toContainText(MOCK_REPLY_TEXT);
// The abort FINAL releases the queued follow-up, which completes live.
await expect(messageTurns(page)).toHaveCount(6, { timeout: 60000 });
const followupTurn = messageTurns(page).nth(4);
await expect(followupTurn).toContainText(interruptText);
await expect(followupTurn.locator('.user-turn')).toBeVisible();
await expect(messageTurns(page).nth(5)).toContainText(MOCK_REPLY_TEXT, { timeout: 30000 });
/** The empty assistant is a durable parent, not merely the optimistic
* row that the created handler rendered. Without that row an underscore
* preliminary id can reject this same queued submission. */
const persisted = await requestJson<PersistedMessage[]>(page, {
path: messagesPath,
token: accessToken,
@ -789,26 +857,11 @@ test.describe('mid-run steering and queuing', () => {
message.isCreatedByUser === false &&
message.parentMessageId === interruptedUser?.messageId,
),
).toMatchObject({
content: [],
unfinished: true,
isCreatedByUser: false,
});
).toMatchObject({ content: [], unfinished: true });
await expect(queuedRows(page)).toHaveCount(0);
});
/**
* Interrupt & steer is the only path that can inject with NO tool boundary
* ahead of it: the server asks the generating replica to seal the model
* stream at the next provider-safe chunk, keeps the partial answer, and
* resumes in the same message.
*
* The contrast with the two tests above IS the feature. `E2E_SLOW_REPLY`
* streams pure text with no tools, so an ordinary steer there provably
* degrades to a queued follow-up turn ("steer after the last tool boundary"
* above), and interrupt & send discards the half-written answer entirely.
* This path does neither: same absence of a boundary, opposite outcome.
*/
/** The other interrupt chord uses the same no-tool-boundary continuation. */
test('interrupt & steer (Cmd/Ctrl+Shift+Enter) seals mid-stream and injects with no tool boundary', async ({
page,
}) => {

View file

@ -210,6 +210,8 @@ async function callAndCapture(
user?: IUser;
tenantId?: string;
requestBody?: Parameters<typeof createRun>[0]['requestBody'];
steering?: Parameters<typeof createRun>[0]['steering'];
customHandlers?: Parameters<typeof createRun>[0]['customHandlers'];
} = {},
) {
const agents = opts.agents ?? [makeAgent()];
@ -230,6 +232,8 @@ async function callAndCapture(
user: opts.user,
tenantId: opts.tenantId,
requestBody: opts.requestBody,
steering: opts.steering,
customHandlers: opts.customHandlers,
streaming: true,
streamUsage: true,
});
@ -5088,3 +5092,40 @@ describe('summarizeOnly resolution', () => {
expect(agents[1].summarizeOnly).toBeUndefined();
});
});
describe('steering provider capabilities', () => {
it.each([
['Anthropic search', { type: 'web_search_20250305', name: 'web_search' }],
['Google search', { googleSearch: {} }],
['OpenAI search', { type: 'web_search' }],
['Google URL context', { urlContext: {} }],
])('disables interruption before constructing a run with %s', async (_name, tool) => {
const disable = jest.fn(async () => undefined);
const handler = { handle: jest.fn() };
await callAndCapture({
agents: [makeAgent({ tools: [tool] })],
customHandlers: { on_tool_execute: handler },
steering: { hook: async () => ({}), preemption: { shouldPreempt: () => true, disable } },
});
expect(disable).toHaveBeenCalledTimes(1);
const config = jest.mocked(Run.create).mock.calls[0]?.[0];
expect(config?.preemption).toBeUndefined();
expect(config?.customHandlers?.on_tool_execute).toBe(handler);
});
it('keeps interruption for host-executed tools', async () => {
const disable = jest.fn(async () => undefined);
const tool = new DynamicStructuredTool({
name: 'web_search',
description: 'Host search',
schema: z.object({}),
func: async () => 'found it',
});
await callAndCapture({
agents: [makeAgent({ tools: [tool] })],
steering: { hook: async () => ({}), preemption: { shouldPreempt: () => true, disable } },
});
expect(disable).not.toHaveBeenCalled();
expect(jest.mocked(Run.create).mock.calls[0]?.[0].preemption).toBeDefined();
});
});

View file

@ -55,6 +55,7 @@ import type {
} from './backgroundCompletion';
import type { ScheduleMCPExecution } from '~/schedules/authorization/execution';
import type { SkillFileRecord, PrimeSkillFilesResult } from './skillFiles';
import type { InterruptibleToolBatchRequest } from './steering/tools';
import type { ArtifactDeliveryFailure } from '~/files/code';
import type { BackgroundToolResultState } from './harvest';
import type { SandboxTextReader } from '~/files/code/text';
@ -149,6 +150,7 @@ import {
import { editConflictExcerptText, formatEditConflict, parseEditConflict } from '~/code/edits';
import { buildSkillPrimeMessage, isSkillFilePath, SKILL_FILE_PREFIX } from './skills';
import { resolveCallerCapabilityProjectionSnapshot } from './callerCapabilities';
import { SteerToolInterrupt, interruptedToolResult } from './steering/tools';
import { BACKGROUND_TOOL_INVOCATION_CONFIG_KEY } from './invocation';
import { mergeCodeFilesIntoContext } from './codeFilesSession';
import { toolValidationFeedback } from './validationFeedback';
@ -5672,6 +5674,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
resolve,
reject,
} = data;
const onResultAdmissionStart = (data as InterruptibleToolBatchRequest).onResultAdmissionStart;
const executionContext = (
data as ToolExecuteBatchRequest & { executionContext?: SubagentExecutionContext }
).executionContext;
@ -6969,6 +6972,10 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
if (filteredArguments != null) {
return reportResult(filteredArguments);
}
if (runSignal?.reason instanceof SteerToolInterrupt) {
return reportResult(interruptedToolResult(tc.id));
}
onResultAdmissionStart?.(tc.id);
const pollContent = await runCheckBackgroundTask({
userId: backgroundUserId,
conversationId: backgroundConversationId,
@ -7041,6 +7048,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
* ORIGINAL tool-call identity by the completion harvest. */
if (toolEndCallback && !(isCodeTask && pending.harvestStarted === true)) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
@ -7226,6 +7234,10 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
persistBackgroundCodeResult == null
)
) {
if (runSignal?.reason instanceof SteerToolInterrupt) {
return reportResult(interruptedToolResult(tc.id));
}
onResultAdmissionStart?.(tc.id);
return reportResult(await dispatchBackgroundToolCall(tc));
}
@ -7240,6 +7252,9 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
isFileAuthoringCall &&
typeof (tc.args as { path?: unknown }).path === 'string' &&
!(tc.args as { path: string }).path.startsWith(SKILL_FILE_PREFIX);
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
let sandboxReadSucceeded = false;
if (
tc.name === Constants.SKILL_TOOL ||
@ -7359,6 +7374,9 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
};
}
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
const filteredOutput = filteredToolOutputResult(tc, req, {
content: handlerResult.content,
artifact: handlerResult.artifact,
@ -7371,6 +7389,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
* and re-executed — the blocked output stays blank. */
if (toolEndCallback && handlerResult.errorMessage == null) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
@ -7394,6 +7413,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
if (toolEndCallback && handlerResult.artifact) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
@ -7583,7 +7603,11 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
eligiblePtcToolMap.keys(),
ptcReq,
),
emit: emitPtcProgress,
emit: (event) => {
if (!(runSignal?.reason instanceof SteerToolInterrupt)) {
emitPtcProgress(event);
}
},
})
: eligiblePtcToolMap;
}
@ -7625,6 +7649,10 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
...(runSignal != null && { signal: runSignal }),
} as Record<string, unknown>);
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
/* Only sandbox-bound calls carry a runtime session hint, so
* this refreshes the prewarm module's warm window without
* inspecting tool names. */
@ -7659,6 +7687,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
* and re-executed — the blocked output stays blank. */
if (toolEndCallback) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
@ -7681,6 +7710,7 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
}
if (toolEndCallback) {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,

View file

@ -1,7 +1,7 @@
import { randomUUID } from 'crypto';
import { logger } from '@librechat/data-schemas';
import { ensureHandler } from '@langchain/core/callbacks/manager';
import { Run, Providers, Constants, HookRegistry } from '@librechat/agents';
import { Run, Providers, Constants, GraphEvents, HookRegistry } from '@librechat/agents';
import {
KnownEndpoints,
EModelEndpoint,
@ -53,13 +53,13 @@ import type { CallbackHandlerMethods } from '@langchain/core/callbacks/base';
import type { ToolApprovalGrantStorage } from 'librechat-data-provider';
import type { BaseMessage } from '@librechat/agents/langchain/messages';
import type { Callbacks } from '@langchain/core/callbacks/manager';
import type { TerminalSteerHook, SteerPreemption } from '~/agents/steering/runtime';
import type { ModelBoundChatModelCallback } from '~/middleware/modelBoundContent';
import type { ScheduledMCPPolicyError } from '~/schedules/authorization/policy';
import type { ScheduleMCPExecution } from '~/schedules/authorization/execution';
import type { ModelErrorTrackerCallback } from '~/agents/failures/tracker';
import type { ToolInputValidationError } from '~/agents/toolValidation';
import type { ResolvedToolApprovalHook } from '~/agents/hitl/hooks';
import type { TerminalSteerHook } from '~/agents/steering/runtime';
import type { LangfuseTraceContext } from '~/langfuse/identity';
import type { ResolvedAlwaysApplySkill } from '~/agents/skills';
import type { CodeExecutionContext } from '~/agents/execution';
@ -116,6 +116,7 @@ import { applyCustomHandoffPromptKeyCompatibility } from '~/agents/handoffPrompt
import { stripIntentFromToolRegistry, stripIntentFromToolDefinitions } from '~/agents/intent';
import { createAgentToolApprovalSession, bindRunToolApprovalSession } from './hitl/modes';
import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils/headers';
import { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools';
import { extractDefaultParams, resolveReasoningParams } from '~/endpoints/openai/llm';
import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';
import { createScheduledMCPRunPolicy } from '~/schedules/authorization/run';
@ -2287,7 +2288,7 @@ export async function createRun({
* (`createSteerPreemptPoll`). Threaded into `RunConfig.preemption`, which
* also makes the SDK reserve recursion-limit headroom for its seals.
*/
preemption?: StreamPreemption;
preemption?: StreamPreemption & Partial<Pick<SteerPreemption, 'disable'>>;
};
/**
* Run-scoped tool-batch summary hook (PostToolBatch). Like steering, it
@ -3025,11 +3026,25 @@ export async function createRun({
* runtime) — excess-property checks only apply to fresh literals. Inline
* the field at the call site once the dependency is bumped.
*/
let preemption = steering?.preemption;
if (preemption != null && !supportsRunInterruption(agentInputs)) {
await preemption.disable?.();
preemption = undefined;
}
const toolHandler = customHandlers?.[GraphEvents.ON_TOOL_EXECUTE];
const runHandlers =
toolHandler != null && preemption != null && isSteerPreemptSupported()
? {
...customHandlers,
[GraphEvents.ON_TOOL_EXECUTE]: interruptToolHandler(toolHandler, preemption),
}
: customHandlers;
const runConfig = {
runId: resolvedRunId,
graphConfig,
tokenCounter,
customHandlers,
customHandlers: runHandlers,
initialSessions,
calibrationRatio,
fadingTier,
@ -3119,8 +3134,7 @@ export async function createRun({
// Preemption is observation-only like the boundary hooks: the poll never
// mutates and the SDK refuses to seal unless a PreemptBoundary matcher is
// live, so gating both on the same capability keeps them in lockstep.
...(steering?.preemption != null &&
isSteerPreemptSupported() && { preemption: steering.preemption }),
...(preemption != null && isSteerPreemptSupported() && { preemption }),
// Stream circuit breakers (librechat.yaml endpoints.agents.maxToolCallArgBytes /
// maxDeltaEventsPerTurn). Omitted when unset so the SDK defaults apply: a runaway
// streamed tool-call argument aborts the run at 64 KiB, the per-turn delta event

View file

@ -24,6 +24,7 @@ import {
isSteerTerminalContinuationSupported,
} from '../runtime';
import type { TerminalSteerHookInput } from '../runtime';
import { handleSteerRequest, handleSteerArm } from '../request';
jest.spyOn(console, 'log').mockImplementation();
@ -921,6 +922,46 @@ describe('preempt wake channel', () => {
* falls back to the per-chunk poll rather than subscribing to a signal
* nothing reads.
*/
it('downgrades pre-armed messages before provider-hosted tools can execute', async () => {
const streamId = `provider-hosted-${Date.now()}`;
const job = await GenerationJobManager.createJob(streamId, 'user-1', undefined, {
initialMetadata: { preemptCapable: true },
});
await GenerationJobManager.steering.enqueue(streamId, {
...buildSteer('s1', 'change direction'),
preempt: true,
});
await GenerationJobManager.requestPreempt(streamId, 's1', job.createdAt);
const poll = createSteerPreemptPoll(streamId, job.createdAt);
await poll.disable();
expect(poll.shouldPreempt()).toBe(false);
expect((await GenerationJobManager.getJob(streamId))?.metadata?.preemptCapable).toBe(false);
expect((await GenerationJobManager.steering.peek(streamId))[0].preempt).not.toBe(true);
expect(
await handleSteerArm({ id: 'user-1' }, { conversationId: streamId, steerId: 's1' }),
).toMatchObject({ body: { armed: false, code: 'PREEMPT_UNSUPPORTED' } });
expect(
await handleSteerRequest(
{ id: 'user-1' },
{ conversationId: streamId, text: 'another message', preempt: true },
),
).toMatchObject({ status: 202, body: { preempt: false } });
});
it('cannot disable a replacement generation with a stale capability callback', async () => {
const streamId = `provider-replaced-${Date.now()}`;
const oldJob = await GenerationJobManager.createJob(streamId, 'user-1');
const oldPoll = createSteerPreemptPoll(streamId, oldJob.createdAt);
await GenerationJobManager.abortJob(streamId);
await new Promise((resolve) => setTimeout(resolve, 2));
const replacement = await GenerationJobManager.createJob(streamId, 'user-1', undefined, {
initialMetadata: { preemptCapable: true },
});
expect(replacement.createdAt).not.toBe(oldJob.createdAt);
await oldPoll.disable();
expect((await GenerationJobManager.getJob(streamId))?.metadata?.preemptCapable).toBe(true);
});
it('supplies the channel only when the SDK can act on it', async () => {
const streamId = `preempt-wake-probe-${Date.now()}`;
await GenerationJobManager.createJob(streamId, 'user-1');

View file

@ -0,0 +1,431 @@
import { z } from 'zod';
import { Providers } from '@librechat/agents';
import { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import type { EventHandler, StreamPreemption, ToolExecuteBatchRequest } from '@librechat/agents';
import type { BackgroundToolResultClaim } from '@librechat/data-schemas';
import type { InterruptibleToolBatchRequest } from '../tools';
import { SteerToolInterrupt, interruptToolHandler, supportsRunInterruption } from '../tools';
import { CHECK_BACKGROUND_TASK_NAME } from '~/agents/background';
import { createToolExecuteHandler } from '~/agents/handlers';
function control() {
let requested = false;
const listeners = new Set<() => void>();
const preemption: StreamPreemption = {
shouldPreempt: () => requested,
subscribe: (wake) => {
listeners.add(wake);
if (requested) wake();
return () => listeners.delete(wake);
},
};
return {
preemption,
listeners,
wake: () => {
for (const wake of listeners) wake();
},
interrupt: () => {
requested = true;
for (const wake of listeners) wake();
},
};
}
function batch(overrides: Partial<ToolExecuteBatchRequest> = {}): ToolExecuteBatchRequest {
return {
toolCalls: [
{ id: 'one', name: 'search', args: {} },
{ id: 'two', name: 'search', args: {} },
],
resolve: jest.fn(),
reject: jest.fn(),
...overrides,
};
}
function pendingHandler() {
let request: ToolExecuteBatchRequest | undefined;
const handler: EventHandler = {
handle: jest.fn(async (_event, data) => {
request = data as ToolExecuteBatchRequest;
}),
};
return {
handler,
request: () => {
if (request == null) throw new Error('Tool handler was not called');
return request;
},
};
}
describe('interruptToolHandler', () => {
it('waits for tools during ordinary steering and ignores spurious wakes', async () => {
const { handler, request } = pendingHandler();
const state = control();
const input = batch();
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
state.wake();
expect(input.resolve).not.toHaveBeenCalled();
expect(request().signal?.aborted).toBe(false);
request().resolve([]);
await pending;
expect(state.listeners.size).toBe(0);
});
it('keeps completed results and cancels only the unfinished work without stopping the run', async () => {
const { handler, request } = pendingHandler();
const state = control();
const run = new AbortController();
const input = batch({ signal: run.signal });
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
const completed = { toolCallId: 'one', status: 'success' as const, content: 'found it' };
request().onResult?.(completed);
state.interrupt();
await pending;
expect(request().signal?.aborted).toBe(true);
expect(run.signal.aborted).toBe(false);
expect(input.resolve).toHaveBeenCalledWith([
completed,
expect.objectContaining({
toolCallId: 'two',
status: 'error',
errorMessage: expect.stringContaining('Do not repeat'),
}),
]);
expect(state.listeners.size).toBe(0);
});
it('does not start a side effect when interruption is already armed', async () => {
const { handler } = pendingHandler();
const state = control();
state.interrupt();
const input = batch();
await interruptToolHandler(handler, state.preemption).handle('on_tool_execute', input);
expect(handler.handle).not.toHaveBeenCalled();
expect(input.resolve).toHaveBeenCalledTimes(1);
expect(state.listeners.size).toBe(0);
});
it('ignores late results and rejects after interruption', async () => {
const { handler, request } = pendingHandler();
const state = control();
const input = batch({ onResult: jest.fn() });
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
state.interrupt();
await pending;
const late = { toolCallId: 'two', status: 'success' as const, content: 'late' };
request().onResult?.(late);
request().resolve([late]);
request().reject(new Error('late error'));
expect(input.resolve).toHaveBeenCalledTimes(1);
expect(input.onResult).not.toHaveBeenCalled();
expect(input.reject).not.toHaveBeenCalled();
});
it('forwards normal failures and releases the subscription', async () => {
const { handler, request } = pendingHandler();
const state = control();
const input = batch();
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
const failure = new Error('failed');
request().reject(failure);
await expect(pending).rejects.toBe(failure);
expect(input.reject).toHaveBeenCalledWith(failure);
expect(state.listeners.size).toBe(0);
});
it('releases the subscription when Stop aborts the run', async () => {
const { handler } = pendingHandler();
const state = control();
const controller = new AbortController();
const input = batch({ signal: controller.signal });
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
const failure = new Error('Run stopped');
controller.abort(failure);
await expect(pending).rejects.toBe(failure);
expect(input.reject).toHaveBeenCalledWith(failure);
expect(state.listeners.size).toBe(0);
});
it('leaves independently controlled child executions alone', async () => {
const { handler } = pendingHandler();
const state = control();
const input = batch({
executionContext: {
rootRunId: 'root',
depth: 1,
ancestry: [],
hookSessionId: 'child',
},
});
await interruptToolHandler(handler, state.preemption).handle('on_tool_execute', input);
expect(handler.handle).toHaveBeenCalledWith('on_tool_execute', input, undefined, undefined);
expect(state.listeners.size).toBe(0);
});
it('keeps admitted output when a cancelled sibling reports a scope-abort failure', async () => {
const { handler, request } = pendingHandler();
const state = control();
const input = batch();
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
(request() as InterruptibleToolBatchRequest).onResultAdmissionStart?.('one');
state.interrupt();
request().reject(new SteerToolInterrupt());
expect(input.reject).not.toHaveBeenCalled();
expect(input.resolve).not.toHaveBeenCalled();
const completed = { toolCallId: 'one', status: 'success' as const, content: 'admitted output' };
request().onResult?.(completed);
await pending;
expect(input.resolve).toHaveBeenCalledWith([
completed,
expect.objectContaining({ toolCallId: 'two', status: 'error' }),
]);
});
it('preserves a durable background result claimed while interruption is requested', async () => {
const state = control();
let finishClaim: ((claim: BackgroundToolResultClaim) => void) | undefined;
let started: (() => void) | undefined;
const ready = new Promise<void>((resolve) => {
started = resolve;
});
const settleClaimed = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [] }),
backgroundToolCompletion: {
persist: async () => true,
claim: async () => {
started?.();
return new Promise<BackgroundToolResultClaim>((resolve) => {
finishClaim = resolve;
});
},
pending: {
list: async () => ({ completions: [], dead: [], complete: true }),
listSubagentWakeups: async () => ({ taskIds: [], complete: true }),
discard: async () => 'not_pending',
settleClaimed,
},
},
});
const input = batch({
toolCalls: [
{
id: 'poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: 'durable-task' },
},
],
configurable: {
req: { user: { id: 'owner' }, body: { conversationId: 'thread' } },
backgroundToolNames: ['search'],
},
metadata: { thread_id: 'thread', run_id: 'root-run' },
});
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
await ready;
state.interrupt();
expect(input.resolve).not.toHaveBeenCalled();
finishClaim?.({
status: 'acquired',
results: [
{
taskId: 'durable-task',
toolCallId: 'original',
toolName: 'search',
status: 'completed',
output: 'CLAIMED RESULT',
},
],
});
await pending;
expect(settleClaimed).toHaveBeenCalledTimes(1);
expect(input.resolve).toHaveBeenCalledWith([
expect.objectContaining({
status: 'success',
content: expect.stringContaining('CLAIMED RESULT'),
}),
]);
expect(state.listeners.size).toBe(0);
});
it('does not acquire background ownership after interruption during tool loading', async () => {
const state = control();
let finishLoad: (() => void) | undefined;
let started: (() => void) | undefined;
const ready = new Promise<void>((resolve) => {
started = resolve;
});
const claim = jest.fn(async () => ({ status: 'not_ready' as const }));
const handler = createToolExecuteHandler({
loadTools: async () => {
started?.();
await new Promise<void>((resolve) => {
finishLoad = resolve;
});
return { loadedTools: [] };
},
backgroundToolCompletion: { persist: async () => true, claim },
});
const input = batch({
toolCalls: [
{
id: 'poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: 'unclaimed-task' },
},
],
configurable: {
req: { user: { id: 'owner' }, body: { conversationId: 'thread' } },
backgroundToolNames: ['search'],
},
metadata: { thread_id: 'thread', run_id: 'root-run' },
});
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
await ready;
state.interrupt();
await pending;
finishLoad?.();
await new Promise((resolve) => setImmediate(resolve));
expect(claim).not.toHaveBeenCalled();
expect(input.resolve).toHaveBeenCalledTimes(1);
});
it('waits for admitted artifact validation and preserves the successful result', async () => {
const state = control();
let release: (() => void) | undefined;
let start: (() => void) | undefined;
const ready = new Promise<void>((resolve) => {
start = resolve;
});
const publications: string[] = [];
const tool = new DynamicStructuredTool({
name: 'search',
description: 'Search',
schema: z.object({}),
responseFormat: 'content_and_artifact',
func: async () => ['completed output', { files: [] }],
});
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
toolEndCallback: async () => {
start?.();
await new Promise<void>((resolve) => {
release = resolve;
});
publications.push('file');
},
});
const input = batch({ toolCalls: [{ id: 'one', name: 'search', args: {} }] });
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
await ready;
state.interrupt();
expect(input.resolve).not.toHaveBeenCalled();
release?.();
await pending;
expect(publications).toEqual(['file']);
expect(input.resolve).toHaveBeenCalledWith([
expect.objectContaining({
toolCallId: 'one',
status: 'success',
content: 'completed output',
}),
]);
expect(state.listeners.size).toBe(0);
});
it('cancels a real tool invocation and suppresses artifacts from a tool that ignores cancellation', async () => {
const state = control();
let finish: (() => void) | undefined;
let signal: AbortSignal | undefined;
let started: (() => void) | undefined;
const ready = new Promise<void>((resolve) => {
started = resolve;
});
const tool = new DynamicStructuredTool({
name: 'search',
description: 'Search',
schema: z.object({}),
responseFormat: 'content_and_artifact',
func: async (_input, _manager, config) => {
signal = config?.signal;
started?.();
await new Promise<void>((resolve) => {
finish = resolve;
});
return ['late result', { files: [] }];
},
});
const callback = jest.fn();
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
toolEndCallback: callback,
});
const input = batch({ toolCalls: [{ id: 'one', name: 'search', args: {} }] });
const pending = interruptToolHandler(handler, state.preemption).handle(
'on_tool_execute',
input,
);
await ready;
state.interrupt();
await pending;
expect(signal?.aborted).toBe(true);
finish?.();
await new Promise((resolve) => setImmediate(resolve));
expect(callback).not.toHaveBeenCalled();
expect(input.resolve).toHaveBeenCalledTimes(1);
expect(input.reject).not.toHaveBeenCalled();
});
});
describe('supportsRunInterruption', () => {
it('gates provider search plugins that do not expose tool definitions', () => {
expect(
supportsRunInterruption([
{
provider: Providers.OPENAI,
agentId: 'agent',
clientOptions: { modelKwargs: { plugins: [{ id: 'web' }] } },
},
]),
).toBe(false);
expect(
supportsRunInterruption([
{
provider: Providers.OPENAI,
agentId: 'agent',
clientOptions: { modelKwargs: { plugins: [{ id: 'other' }] } },
},
]),
).toBe(true);
});
});

View file

@ -338,9 +338,22 @@ export function createSteerTerminalContinuationHook(
* is: a run wired to a generation that has since been replaced must not be
* woken by the replacement's arms.
*/
export function createSteerPreemptPoll(streamId: string, jobCreatedAt?: number): StreamPreemption {
export interface SteerPreemption extends StreamPreemption {
/** Restrict owner-recorded capability before a provider-hosted tool can start. */
disable: () => Promise<void>;
}
export function createSteerPreemptPoll(streamId: string, jobCreatedAt?: number): SteerPreemption {
let enabled = true;
return {
shouldPreempt: () => GenerationJobManager.isPreemptRequested(streamId),
shouldPreempt: () => enabled && GenerationJobManager.isPreemptRequested(streamId),
disable: async () => {
enabled = false;
await GenerationJobManager.updateMetadata(streamId, { preemptCapable: false }, jobCreatedAt);
if (jobCreatedAt != null) {
await GenerationJobManager.rearmQueuedPreempts(streamId, jobCreatedAt);
}
},
...(isSteerPreemptRestartSupported() && {
subscribe: (wake: () => void) =>
GenerationJobManager.subscribePreempt(streamId, wake, jobCreatedAt),

View file

@ -0,0 +1,133 @@
import type {
ToolExecuteBatchRequest,
ToolExecuteResult,
StreamPreemption,
EventHandler,
AgentInputs,
} from '@librechat/agents';
/** The pinned SDK cannot cancel unanswered provider-hosted tools without orphaning them. */
export function supportsRunInterruption(agents: readonly AgentInputs[]): boolean {
return agents.every((agent) => {
if (agent.tools?.some((tool) => !('invoke' in tool) || typeof tool.invoke !== 'function'))
return false;
const plugins = (
agent.clientOptions as { modelKwargs?: { plugins?: Array<{ id?: string }> } } | undefined
)?.modelKwargs?.plugins;
return !plugins?.some((plugin) => plugin.id === 'web');
});
}
/** Host-only admission channel for durable claims and completed-output validation. */
export interface InterruptibleToolBatchRequest extends ToolExecuteBatchRequest {
onResultAdmissionStart?: (toolCallId: string) => void;
}
const INTERRUPTED =
'Interrupted by a user message. Cancellation was requested; external effects may already have occurred. Do not repeat this operation automatically.';
export class SteerToolInterrupt extends Error {
constructor() {
super('Interrupted by a user message');
this.name = 'AbortError';
}
}
export function interruptedToolResult(toolCallId: string): ToolExecuteResult {
return { toolCallId, status: 'error', content: '', errorMessage: INTERRUPTED };
}
/** Cancel the batch, not the run: its PostToolBatch hook still injects the steer. */
export function interruptToolHandler(
handler: EventHandler,
preemption: StreamPreemption,
): EventHandler {
return {
handle: async (event: string, data: ToolExecuteBatchRequest, metadata, graph) => {
if (data.executionContext != null || preemption.subscribe == null) {
return handler.handle(event, data, metadata, graph);
}
const controller = new AbortController();
const signal =
data.signal == null ? controller.signal : AbortSignal.any([data.signal, controller.signal]);
const completed = new Map<string, ToolExecuteResult>();
const admitted = new Set<string>();
let interrupted = false;
let settled = false;
let unsubscribe: (() => void) | undefined;
let onAbort: (() => void) | undefined;
await new Promise<void>((resolve, reject) => {
const finish = (results: ToolExecuteResult[]) => {
if (settled) return;
settled = true;
try {
data.resolve(results);
resolve();
} catch (error) {
reject(error);
}
};
const fail = (error: Error) => {
if (settled) return;
if (interrupted && error instanceof SteerToolInterrupt && !data.signal?.aborted) {
finishInterrupt();
return;
}
settled = true;
data.reject(error);
reject(error);
};
const finishInterrupt = () => {
if (!interrupted || admitted.size > 0) return;
finish(
data.toolCalls.map((call) => completed.get(call.id) ?? interruptedToolResult(call.id)),
);
};
const interrupt = () => {
if (settled || interrupted || data.signal?.aborted || !preemption.shouldPreempt()) return;
interrupted = true;
controller.abort(new SteerToolInterrupt());
finishInterrupt();
};
onAbort = () =>
fail(
data.signal?.reason instanceof Error
? data.signal.reason
: new DOMException('Run aborted', 'AbortError'),
);
data.signal?.addEventListener('abort', onAbort, { once: true });
if (data.signal?.aborted) {
onAbort();
return;
}
unsubscribe = preemption.subscribe?.(interrupt);
interrupt();
if (settled) return;
const request: InterruptibleToolBatchRequest = {
...data,
signal,
resolve: (results) => (interrupted ? finishInterrupt() : finish(results)),
reject: fail,
onResultAdmissionStart: (toolCallId) => {
if (!settled && !interrupted) admitted.add(toolCallId);
},
onResult: (result) => {
if (settled || (interrupted && !admitted.has(result.toolCallId))) return;
completed.set(result.toolCallId, result);
admitted.delete(result.toolCallId);
data.onResult?.(result);
finishInterrupt();
},
};
try {
Promise.resolve(handler.handle(event, request, metadata, graph)).catch(fail);
} catch (error) {
fail(error instanceof Error ? error : new Error('Tool execution failed'));
}
}).finally(() => {
unsubscribe?.();
if (onAbort != null) data.signal?.removeEventListener('abort', onAbort);
});
},
};
}