🔱 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

@ -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);
});
},
};
}