mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 15:33:45 +00:00
🔱 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:
parent
82cde522f2
commit
d55dbc3bd8
30 changed files with 1248 additions and 349 deletions
|
|
@ -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();
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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');
|
||||
|
|
|
|||
431
packages/api/src/agents/steering/__tests__/tools.spec.ts
Normal file
431
packages/api/src/agents/steering/__tests__/tools.spec.ts
Normal 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);
|
||||
});
|
||||
});
|
||||
|
|
@ -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),
|
||||
|
|
|
|||
133
packages/api/src/agents/steering/tools.ts
Normal file
133
packages/api/src/agents/steering/tools.ts
Normal 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);
|
||||
});
|
||||
},
|
||||
};
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue