Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { z } from 'zod';
import { logger } from '@librechat/data-schemas';
import { tool as structuredTool } from '@librechat/agents/langchain/tools';
import type { StructuredToolInterface } from '@librechat/agents/langchain/tools';
import type { FiltersConfig } from 'librechat-data-provider';
import type { BackgroundToolWakeupAdmission } from './backgroundCompletion';
import type { ToolExecuteOptions } from './handlers';
import {
BACKGROUND_TASK_ABORT_GRACE_MS,
BACKGROUND_TASK_TIMEOUT_MS,
BACKGROUND_TOOL_PRODUCER_HEARTBEAT_MS,
} from './backgroundCompletion';
import {
backgroundTaskRegistry,
runCheckBackgroundTask,
CHECK_BACKGROUND_TASK_NAME,
} from './background';
import { BACKGROUND_TOOL_INVOCATION_CONFIG_KEY } from './invocation';
import { ContentFilterError } from '../middleware/contentFilter';
import { createToolExecuteHandler } from './handlers';
interface BatchInput {
toolCalls: Array<{
id: string;
name: string;
args: Record<string, unknown>;
stepId?: string;
turn?: number;
codeSessionContext?: { session_id: string; files?: Array<Record<string, unknown>> };
runtimeSessionHint?: string;
}>;
agentId: string;
configurable: Record<string, unknown>;
metadata: Record<string, unknown>;
resolve: (results: Array<{ content: string }>) => void;
reject: (error: Error) => void;
}
const flushMicrotasks = () => new Promise((resolve) => setImmediate(resolve));
const MODEL_BOUND_FILE_CONTENT_BLOCK = JSON.stringify({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'file',
field: 'content',
});
const MODEL_BOUND_TOOL_OUTPUT_BLOCK = JSON.stringify({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'tool_argument',
field: 'output',
});
const CODE_TOOL_OUTPUT_BLOCK = `Error: [execute_code] tool call failed: ${MODEL_BOUND_TOOL_OUTPUT_BLOCK}`;
const CODE_FILE_CONTENT_BLOCK = `Error: [execute_code] tool call failed: ${MODEL_BOUND_FILE_CONTENT_BLOCK}`;
const makeSearchTool = (state: { calls: number; lastInput?: Record<string, unknown> }) =>
({
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: async (input: Record<string, unknown>) => {
state.calls += 1;
state.lastInput = input;
return { content: `RESULT for ${String(input.q)}` };
},
}) as unknown as StructuredToolInterface;
const buildConfig = (
backgroundToolNames: string[] = ['search_mcp_docs'],
filters?: FiltersConfig,
) => ({
req: {
user: { id: 'exec_user' },
body: { conversationId: 'exec_convo' },
...(filters != null ? { config: { filters } } : {}),
},
backgroundToolNames,
});
const runBatch = async (
handler: ReturnType<typeof createToolExecuteHandler>,
input: Omit<BatchInput, 'resolve' | 'reject'>,
): Promise<Array<{ content: string }>> => {
let out: Array<{ content: string }> = [];
await handler.handle('on_tool_execute', {
...input,
resolve: (results: Array<{ content: string }>) => {
out = results;
},
reject: (error: Error) => {
throw error;
},
} as unknown as Parameters<typeof handler.handle>[1]);
return out;
};
describe('createToolExecuteHandler — background tool calls', () => {
it('hands off an explicit polling call and preserves validation feedback in its result', async () => {
const execute = jest.fn(async () => 'executed');
const bash = structuredTool(execute, {
name: 'build_project',
description: 'Starts commands',
schema: {
type: 'object',
required: ['command'],
properties: { command: { type: 'string' } },
},
});
const handler = createToolExecuteHandler({ loadTools: async () => ({ loadedTools: [bash] }) });
const configurable = buildConfig(['build_project']);
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'invalid-background-bash',
name: 'build_project',
args: { background_task_id: 'secret-task', run_in_background: true },
},
],
agentId: 'agent_parent_1',
configurable,
metadata: { thread_id: 'exec_convo', run_id: 'invalid-background-run' },
});
const handle = JSON.parse(dispatch.content);
const statusCheck = JSON.parse(handle.message.split('Status request: ')[1]);
expect(statusCheck).toEqual({
name: CHECK_BACKGROUND_TASK_NAME,
arguments: { background_task_id: handle.background_task_id },
});
await flushMicrotasks();
const [poll] = await runBatch(handler, {
toolCalls: [
{
id: 'poll-invalid-background-bash',
name: statusCheck.name,
args: statusCheck.arguments,
},
],
agentId: 'agent_parent_1',
configurable,
metadata: { thread_id: 'exec_convo', run_id: 'invalid-background-run' },
});
expect(execute).not.toHaveBeenCalled();
expect(poll.content).toContain('Missing required fields: command');
expect(poll.content).not.toContain('secret-task');
});
it('pre-registers an ordinary completion before invoke and persists its terminal receipt', async () => {
const events: string[] = [];
const retire = jest.fn(async () => true);
const persistResult = jest.fn(async () => {
events.push('receipt');
return true;
});
const preregister = jest.fn(async () => {
events.push('preregister');
return { renew: jest.fn(async () => true), persistResult, retire };
});
const persist = jest.fn(async () => {
events.push('persist');
return true;
});
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(async () => {
events.push('invoke');
return { content: 'durable result' };
}),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister,
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-wakeup',
name: tool.name,
args: { q: 'continuations', run_in_background: true },
stepId: 'step-wakeup',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
expect(events.slice(0, 2)).toEqual(['preregister', 'invoke']);
expect(tool.invoke).toHaveBeenCalledWith(
{ q: 'continuations' },
expect.objectContaining({
configurable: expect.objectContaining({
[BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true,
}),
}),
);
expect(JSON.parse(dispatch.content).message).toContain('host will resume you');
await flushMicrotasks();
expect(events).toEqual(['preregister', 'invoke', 'receipt', 'persist']);
expect(preregister).toHaveBeenCalledWith(
expect.objectContaining({
toolCallId: 'call-wakeup',
conversationId: 'exec_convo',
parentMessageId: 'response-1',
parentAgentId: 'agent_parent_1',
}),
);
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({
output: 'durable result',
stepId: 'step-wakeup',
backgroundTask: expect.objectContaining({
taskId: expect.any(String),
status: 'completed',
}),
}),
);
expect(persistResult).toHaveBeenCalledWith(
expect.objectContaining({ status: 'completed', output: 'durable result' }),
);
expect(retire).not.toHaveBeenCalled();
});
it('persists structured background content using the registry serialization', async () => {
const structuredContent = [
{ type: 'text', text: 'structured result' },
{ type: 'resource', uri: 'memory://result' },
];
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(async () => ({ content: structuredContent })),
} as unknown as StructuredToolInterface;
const persist = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
})),
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-structured-wakeup',
name: tool.name,
args: { q: 'structured', run_in_background: true },
stepId: 'step-structured-wakeup',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-structured' },
});
await flushMicrotasks();
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({ output: JSON.stringify(structuredContent) }),
);
});
it.each(['acknowledged', 'ambiguous'])(
'keeps delivery live for an %s receipt without a projection',
async (ack) => {
const retire = jest.fn(async () => true);
const persistResult = jest.fn(async () => {
if (ack === 'ambiguous') throw new Error('receipt committed but acknowledgement lost');
return true;
});
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(async () => ({ content: 'available before parent row' })),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
persistResult,
retire,
})),
persist: jest.fn(async () => false),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: `call-independent-receipt-${ack}`,
name: tool.name,
args: { q: 'receipt', run_in_background: true },
stepId: 'step-independent-receipt',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: `response-independent-receipt-${ack}` },
});
await flushMicrotasks();
expect(persistResult).toHaveBeenCalledWith(
expect.objectContaining({ status: 'completed', output: 'available before parent row' }),
);
expect(retire).not.toHaveBeenCalled();
},
);
it('keeps polling guidance when the completion adapter skips registration', async () => {
const tool = makeSearchTool({ calls: 0 });
const preregister = jest.fn(async () => false as const);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister,
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-skipped-wakeup',
name: tool.name,
args: { q: 'ephemeral', run_in_background: true },
stepId: 'step-skipped-wakeup',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
expect(preregister).toHaveBeenCalledTimes(1);
expect(JSON.parse(dispatch.content).message).toContain('Call check_background_task');
expect(JSON.parse(dispatch.content).message).not.toContain('host will resume you');
});
it('keeps repeated provider ids poll-only when the host step identity is absent', async () => {
const tool = makeSearchTool({ calls: 0 });
const preregister = jest.fn(async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
}));
const persist = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister,
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-without-step',
name: tool.name,
args: { q: 'legacy', run_in_background: true },
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
await flushMicrotasks();
expect(preregister).not.toHaveBeenCalled();
expect(persist).not.toHaveBeenCalled();
expect(JSON.parse(dispatch.content).message).toContain('Call check_background_task');
expect(JSON.parse(dispatch.content).message).not.toContain('host will resume you');
});
it('expedites the delivery when only the parent-message projection was persisted', async () => {
const tool = makeSearchTool({ calls: 0 });
const expedite = jest.fn();
const retire = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
persistResult: jest.fn(async () => false),
retire,
expedite,
})),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-projection-only',
name: tool.name,
args: { q: 'projection', run_in_background: true },
stepId: 'step-projection-only',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
await flushMicrotasks();
await flushMicrotasks();
expect(expedite).toHaveBeenCalledTimes(1);
expect(retire).not.toHaveBeenCalled();
});
it('retires a preregistered delivery when terminal persistence fails', async () => {
const tool = makeSearchTool({ calls: 0 });
const retire = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({ renew: jest.fn(async () => true), retire })),
persist: jest.fn(async () => false),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-persistence-failure',
name: tool.name,
args: { q: 'retire', run_in_background: true },
stepId: 'step-persistence-failure',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
await flushMicrotasks();
await flushMicrotasks();
expect(retire).toHaveBeenCalledWith('background tool result was not persisted', undefined);
});
it('copies committed manual reconciliation into the final background projection retry', async () => {
let finishPersistence: (persisted: boolean) => void = () => undefined;
let resolveProjection: (() => { resultClaim?: { receiptReconciled?: true } }) | undefined;
const tool = makeSearchTool({ calls: 0 });
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: async () => ({
renew: async () => true,
retire: async () => true,
persistResult: async () => true,
}),
claim: async () => ({ status: 'not_ready' }),
persist: (params) => {
resolveProjection = params.resolveBackgroundTask;
return new Promise<boolean>((resolve) => {
finishPersistence = resolve;
});
},
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'manual-marker-dispatch',
stepId: 'manual-marker-step',
name: tool.name,
args: { q: 'marker', run_in_background: true },
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'manual-marker-convo', run_id: 'manual-marker-parent' },
});
await flushMicrotasks();
const taskId = JSON.parse(dispatch.content).background_task_id as string;
try {
expect(resolveProjection?.().resultClaim).toBeUndefined();
expect(
backgroundTaskRegistry.claimResult('exec_user', 'manual-marker-convo', taskId, {
kind: 'manual',
claimId: 'manual-marker-poll',
receiptReconciled: true,
generationId: 'manual-marker-generation',
}),
).toBe('acquired');
expect(resolveProjection?.().resultClaim).toMatchObject({ receiptReconciled: true });
} finally {
finishPersistence(true);
await flushMicrotasks();
}
});
it('falls back to the settled local result when a poll retired delivery before persistence failed', async () => {
let finishPersistence: ((persisted: boolean) => void) | undefined;
const persist = jest.fn(
() =>
new Promise<boolean>((resolve) => {
finishPersistence = resolve;
}),
);
const retire = jest.fn().mockResolvedValueOnce(true).mockResolvedValueOnce(false);
const tool = makeSearchTool({ calls: 0 });
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({ renew: jest.fn(async () => true), retire })),
persist,
claim: jest.fn(async () => ({ status: 'not_ready' as const })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-poll-before-failure',
name: tool.name,
args: { q: 'settle', run_in_background: true },
stepId: 'step-poll-before-failure',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-poll-before-failure' },
});
await flushMicrotasks();
const taskId = JSON.parse(dispatch.content).background_task_id as string;
const waiting = JSON.parse(
await runCheckBackgroundTask({
userId: 'exec_user',
conversationId: 'exec_convo',
args: { background_task_id: taskId },
toolCallId: 'manual-poll-1',
runId: 'response-poll-before-failure',
claimBackgroundToolResult: async () => ({ status: 'not_ready' }),
}),
);
expect(waiting.status).toBe('result_persisting');
expect(
backgroundTaskRegistry.get('exec_user', 'exec_convo', taskId)?.resultClaim,
).toBeUndefined();
finishPersistence?.(false);
await flushMicrotasks();
await flushMicrotasks();
expect(
backgroundTaskRegistry.get('exec_user', 'exec_convo', taskId)?.completionPersistenceFailed,
).toBe(true);
const recovered = JSON.parse(
await runCheckBackgroundTask({
userId: 'exec_user',
conversationId: 'exec_convo',
args: { background_task_id: taskId },
toolCallId: 'manual-poll-2',
runId: 'response-poll-before-failure',
claimBackgroundToolResult: async () => ({ status: 'not_ready' }),
}),
);
expect(recovered).toMatchObject({
status: 'completed',
result: 'RESULT for settle',
});
});
it('keeps durable ownership active when an ambiguous persistence failure cannot retire a lease', async () => {
const tool = makeSearchTool({ calls: 0 });
const retire = jest.fn(async () => false);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({ renew: jest.fn(async () => true), retire })),
persist: jest.fn(async () => {
throw new Error('write receipt lost');
}),
claim: jest.fn(async () => ({ status: 'claimed' as const })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-ambiguous-persistence',
name: tool.name,
args: { q: 'ambiguous', run_in_background: true },
stepId: 'step-ambiguous-persistence',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-ambiguous' },
});
await flushMicrotasks();
await flushMicrotasks();
const taskId = JSON.parse(dispatch.content).background_task_id as string;
expect(retire).toHaveBeenCalledWith('background tool result persistence failed', {
onlyIfUnclaimed: true,
});
const task = backgroundTaskRegistry.get('exec_user', 'exec_convo', taskId);
expect(task?.completionWakeup).toBe(true);
expect(task?.completionPersistenceFailed).toBeUndefined();
});
it('elects live polling only when the settled result actually contains an artifact', async () => {
const retire = jest.fn(async () => true);
const preregister = jest.fn(async () => ({
renew: jest.fn(async () => true),
retire,
}));
const persist = jest.fn(async () => true);
const tool = {
name: 'artifact_tool',
description: 'returns a live artifact',
schema: z.object({ q: z.string() }),
responseFormat: 'content_and_artifact',
invoke: jest.fn(async () => ({
content: 'artifact result',
artifact: { files: ['report.pdf'] },
})),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister,
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-artifact-poll',
name: tool.name,
args: { q: 'artifact', run_in_background: true },
stepId: 'step-artifact-poll',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-artifact' },
});
await flushMicrotasks();
expect(preregister).toHaveBeenCalledTimes(1);
expect(retire).toHaveBeenCalledWith('background tool artifact requires live polling');
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({
backgroundTask: expect.not.objectContaining({ completionWakeup: true }),
}),
);
expect(JSON.parse(dispatch.content).message).toContain('must call check_background_task');
expect(JSON.parse(dispatch.content).message).toContain('do not end the turn');
});
it('keeps automatic completion for a declared artifact tool that returns content only', async () => {
const retire = jest.fn(async () => true);
const persist = jest.fn(async () => true);
const tool = {
name: 'optional_artifact_tool',
description: 'may return an artifact',
schema: z.object({ q: z.string() }),
responseFormat: 'content_and_artifact',
invoke: jest.fn(async () => ({ content: 'content-only result' })),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
retire,
})),
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-optional-artifact',
name: tool.name,
args: { q: 'content', run_in_background: true },
stepId: 'step-optional-artifact',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-optional-artifact' },
});
await flushMicrotasks();
expect(retire).not.toHaveBeenCalled();
expect(JSON.parse(dispatch.content).message).toContain('must call check_background_task');
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({
backgroundTask: expect.objectContaining({ completionWakeup: true }),
}),
);
});
it('persists ordinary background failures in the renderer-recognized error shape', async () => {
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(async () => {
throw new Error('boom');
}),
} as unknown as StructuredToolInterface;
const persist = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
})),
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-ordinary-failure',
name: tool.name,
args: { q: 'fail', run_in_background: true },
stepId: 'step-ordinary-failure',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-1' },
});
await flushMicrotasks();
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({
output: 'Error: [search_mcp_docs] tool call failed: boom',
backgroundTask: expect.objectContaining({ status: 'error' }),
}),
);
});
it('persists a terminal receipt when an admitted background task times out', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
try {
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(
(_input: unknown, config?: { signal?: AbortSignal }) =>
new Promise((_resolve, reject) => {
const signal = config?.signal;
if (signal?.aborted === true) {
reject(signal.reason);
return;
}
signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
}),
),
} as unknown as StructuredToolInterface;
const persist = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
})),
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-timeout-wakeup',
name: tool.name,
args: { q: 'hang', run_in_background: true },
stepId: 'step-timeout-wakeup',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-timeout' },
});
jest.advanceTimersByTime(31 * 60 * 1000);
await flushMicrotasks();
await flushMicrotasks();
expect(persist).toHaveBeenCalledWith(
expect.objectContaining({
output: 'Error: [search_mcp_docs] tool call failed: Background task timed out',
backgroundTask: expect.objectContaining({
taskId: JSON.parse(dispatch.content).background_task_id,
status: 'error',
}),
}),
);
} finally {
jest.useRealTimers();
}
});
it('preserves timeout provenance when cancellation is requested after the deadline', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
try {
let rejectInvocation: ((error: unknown) => void) | undefined;
let invocationSignal: AbortSignal | undefined;
const tool = {
name: 'execute_code',
description: 'settles after acknowledging an abort',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: jest.fn(
(_input: unknown, config?: { signal?: AbortSignal }) =>
new Promise((_resolve, reject) => {
invocationSignal = config?.signal;
rejectInvocation = reject;
}),
),
} as unknown as StructuredToolInterface;
const persistBackgroundCodeResult = jest.fn(
async (
_params: Parameters<NonNullable<ToolExecuteOptions['persistBackgroundCodeResult']>>[0],
) => ({ attachments: [] }),
);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
ordinaryToolCancellation: true,
persistBackgroundCodeResult,
backgroundToolCompletion: {
preregister: async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
}),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const configurable = buildConfig([tool.name]);
const metadata = { thread_id: 'late_cancel_conversation', run_id: 'late-cancel-run' };
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call_late_cancel',
name: 'execute_code',
args: { lang: 'python', code: 'while True: pass', run_in_background: true },
},
],
agentId: 'agent_late_cancel',
configurable,
metadata,
});
const taskId = JSON.parse(dispatch.content).background_task_id as string;
jest.advanceTimersByTime(31 * 60 * 1000);
await flushMicrotasks();
const [cancellation] = await runBatch(handler, {
toolCalls: [
{
id: 'call_late_cancel_control',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId, action: 'cancel' },
},
],
agentId: 'agent_late_cancel',
configurable,
metadata,
});
expect(JSON.parse(cancellation.content)).toMatchObject({
status: 'unavailable',
background_task_id: taskId,
});
rejectInvocation?.(
invocationSignal?.reason ?? new DOMException('Background task timed out', 'AbortError'),
);
await flushMicrotasks();
await flushMicrotasks();
const persisted =
persistBackgroundCodeResult.mock.calls[
persistBackgroundCodeResult.mock.calls.length - 1
]?.[0];
expect(persisted).toEqual(
expect.objectContaining({ output: expect.stringContaining('Background task timed out') }),
);
expect(persisted?.backgroundTask?.cancelled).not.toBe(true);
} finally {
jest.useRealTimers();
}
});
it('retires the automatic wakeup after an abort-resistant invocation exceeds its grace period', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
try {
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(() => new Promise(() => undefined)),
} as unknown as StructuredToolInterface;
const persist = jest.fn(async () => true);
const renew = jest.fn(async () => true);
const retire = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew,
retire,
})),
persist,
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call-timeout-resistant',
name: tool.name,
args: { q: 'hang', run_in_background: true },
stepId: 'step-timeout-resistant',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-timeout-resistant' },
});
jest.advanceTimersByTime(BACKGROUND_TASK_TIMEOUT_MS + BACKGROUND_TASK_ABORT_GRACE_MS);
await flushMicrotasks();
await flushMicrotasks();
const taskId = JSON.parse(dispatch.content).background_task_id as string;
expect(backgroundTaskRegistry.get('exec_user', 'exec_convo', taskId)?.status).toBe('running');
expect(persist).not.toHaveBeenCalled();
expect(renew).toHaveBeenCalled();
expect(retire).toHaveBeenCalledWith(
'background task did not settle after its abort grace period',
{ onlyIfUnclaimed: true },
);
const renewalsBefore = renew.mock.calls.length;
jest.advanceTimersByTime(3 * 60 * 1000);
await flushMicrotasks();
expect(renew).toHaveBeenCalledTimes(renewalsBefore);
} finally {
jest.useRealTimers();
}
});
it('stops producer heartbeats after the completion lease is lost', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
try {
let finishTool: ((value: { content: string }) => void) | undefined;
const tool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
invoke: jest.fn(
() =>
new Promise<{ content: string }>((resolve) => {
finishTool = resolve;
}),
),
} as unknown as StructuredToolInterface;
const renew = jest.fn(async () => false);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew,
retire: jest.fn(async () => true),
})),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-lost-producer-lease',
name: tool.name,
args: { q: 'lease', run_in_background: true },
stepId: 'step-lost-producer-lease',
},
],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-lost-producer-lease' },
});
jest.advanceTimersByTime(BACKGROUND_TOOL_PRODUCER_HEARTBEAT_MS);
await flushMicrotasks();
expect(renew).toHaveBeenCalledTimes(1);
jest.advanceTimersByTime(BACKGROUND_TOOL_PRODUCER_HEARTBEAT_MS * 6);
await flushMicrotasks();
expect(renew).toHaveBeenCalledTimes(1);
finishTool?.({ content: 'settled after lease loss' });
await flushMicrotasks();
await flushMicrotasks();
} finally {
jest.useRealTimers();
}
});
it('persists an Event Actor launch before invoking and terminal evidence before wakeup', async () => {
const events: string[] = [];
let finishTool: ((value: { content: string }) => void) | undefined;
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke: () => {
events.push('invoke');
return new Promise<{ content: string }>((resolve) => {
finishTool = resolve;
});
},
} as unknown as StructuredToolInterface;
let reservations = 0;
const eventActorDetachedAction = {
reserve: jest.fn(async () => {
events.push('reserve');
reservations += 1;
return {
status: reservations === 1 ? ('reserved' as const) : ('replay' as const),
taskId: 'event-task-stable-1',
idempotencyKey: 'a'.repeat(64),
};
}),
markRunning: jest.fn(async () => {
events.push('running');
return true;
}),
settle: jest.fn(async () => {
events.push('terminal');
return true;
}),
wake: jest.fn(async () => {
events.push('wake');
}),
};
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction,
});
const request = {
toolCalls: [
{
id: 'call-event-detached',
name: tool.name,
args: { move: 'e4', run_in_background: true },
},
],
agentId: 'agent-player',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'event-conversation', run_id: 'event-response' },
};
const first = await runBatch(handler, request);
expect(JSON.parse(first[0].content)).toMatchObject({
status: 'running',
background_task_id: 'event-task-stable-1',
});
expect(events).toEqual(['reserve', 'invoke', 'running']);
finishTool?.({ content: 'move accepted' });
await flushMicrotasks();
await flushMicrotasks();
expect(events).toEqual(['reserve', 'invoke', 'running', 'terminal', 'wake']);
expect(eventActorDetachedAction.reserve).toHaveBeenCalledWith(
expect.objectContaining({ turnId: 'event-response:' }),
);
const replay = await runBatch(handler, request);
expect(JSON.parse(replay[0].content).background_task_id).toBe('event-task-stable-1');
expect(events).toEqual(['reserve', 'invoke', 'running', 'terminal', 'wake', 'reserve']);
expect(eventActorDetachedAction.settle).toHaveBeenCalledWith(
expect.objectContaining({
taskId: 'event-task-stable-1',
status: 'succeeded',
result: 'move accepted',
}),
);
});
it('records filtered detached output as successful side-effect evidence', async () => {
const protectedValue = 'Authorization: Bearer detached-secret';
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke: jest.fn(async () => ({ content: protectedValue })),
} as unknown as StructuredToolInterface;
const eventActorDetachedAction = {
reserve: jest.fn(async () => ({
status: 'reserved' as const,
taskId: 'event-task-filtered',
idempotencyKey: 'e'.repeat(64),
})),
markRunning: jest.fn(async () => true),
settle: jest.fn(async () => true),
wake: jest.fn(async () => undefined),
};
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction,
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-event-filtered',
name: tool.name,
args: { move: 'e4', run_in_background: true },
},
],
agentId: 'agent-player',
configurable: buildConfig([tool.name], {
toolArguments: {
pii: { fields: ['output'], starterPatterns: ['bearer_header'] },
},
}),
metadata: { thread_id: 'event-filtered-conversation', run_id: 'event-filtered-turn' },
});
await flushMicrotasks();
await flushMicrotasks();
expect(eventActorDetachedAction.settle).toHaveBeenCalledWith(
expect.objectContaining({
taskId: 'event-task-filtered',
status: 'succeeded',
result: expect.stringContaining('content_filter_block'),
}),
);
expect(JSON.stringify(eventActorDetachedAction.settle.mock.calls)).not.toContain(
protectedValue,
);
expect(eventActorDetachedAction.settle).not.toHaveBeenCalledWith(
expect.objectContaining({ status: 'failed' }),
);
expect(eventActorDetachedAction.wake).toHaveBeenCalledTimes(1);
});
it('rejects capacity before creating durable Event Actor launch authority', async () => {
let invocations = 0;
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke: () => {
invocations += 1;
return new Promise(() => undefined);
},
} as unknown as StructuredToolInterface;
const configurable = {
req: {
user: { id: 'capacity-user' },
body: { conversationId: 'capacity-conversation' },
},
backgroundToolNames: [tool.name],
};
const metadata = { thread_id: 'capacity-conversation', run_id: 'capacity-run' };
const ordinaryHandler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
});
await runBatch(ordinaryHandler, {
toolCalls: Array.from({ length: 10 }, (_, index) => ({
id: `capacity-${index}`,
name: tool.name,
args: { move: 'e4', run_in_background: true },
})),
agentId: 'agent-player',
configurable,
metadata,
});
const reserve = jest.fn(async () => ({
status: 'reserved' as const,
taskId: 'event-task-capacity',
idempotencyKey: 'f'.repeat(64),
}));
const detachedHandler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction: {
reserve,
markRunning: jest.fn(async () => true),
settle: jest.fn(async () => true),
wake: jest.fn(async () => undefined),
},
});
const [rejected] = await runBatch(detachedHandler, {
toolCalls: [
{
id: 'capacity-detached',
name: tool.name,
args: { move: 'e5', run_in_background: true },
},
],
agentId: 'agent-player',
configurable,
metadata,
});
expect(rejected.content).toContain('Too many background tasks');
expect(invocations).toBe(10);
expect(reserve).not.toHaveBeenCalled();
});
it('does not launch an expected action when staged production is disabled', async () => {
const invoke = jest.fn(async () => ({ content: 'move accepted' }));
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke,
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction: {
reserve: jest.fn(async () => ({
status: 'conflict' as const,
error: 'Detached Event Actor production is not activated',
})),
markRunning: jest.fn(async () => true),
settle: jest.fn(async () => true),
wake: jest.fn(async () => undefined),
},
});
await expect(
runBatch(handler, {
toolCalls: [
{
id: 'call-disabled',
name: tool.name,
args: { move: 'e4', run_in_background: true },
},
],
agentId: 'agent-player',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'event-conversation', run_id: 'event-response' },
}),
).resolves.toEqual([
expect.objectContaining({ content: '', errorMessage: expect.stringContaining('activated') }),
]);
expect(invoke).not.toHaveBeenCalled();
});
it('persists a synchronous detached-tool rejection as terminal evidence', async () => {
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke: () => {
throw new Error('launch rejected synchronously');
},
} as unknown as StructuredToolInterface;
const eventActorDetachedAction = {
reserve: jest.fn(async () => ({
status: 'reserved' as const,
taskId: 'event-task-sync-error',
idempotencyKey: 'b'.repeat(64),
})),
markRunning: jest.fn(async () => true),
settle: jest.fn(async () => true),
wake: jest.fn(async () => undefined),
};
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction,
});
await expect(
runBatch(handler, {
toolCalls: [
{
id: 'call-sync-error',
name: tool.name,
args: { move: 'e4', run_in_background: true },
},
],
agentId: 'agent-player',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'event-conversation', run_id: 'event-response' },
}),
).resolves.toEqual([
expect.objectContaining({ content: expect.stringContaining('event-task-sync-error') }),
]);
await flushMicrotasks();
await flushMicrotasks();
expect(eventActorDetachedAction.settle).toHaveBeenCalledWith(
expect.objectContaining({
taskId: 'event-task-sync-error',
status: 'failed',
error: expect.stringContaining('launch rejected synchronously'),
}),
);
expect(eventActorDetachedAction.wake).toHaveBeenCalledTimes(1);
});
it('does not claim an unrequested provider abort was owner cancellation', async () => {
const abortError = Object.assign(new Error('operation aborted'), { name: 'AbortError' });
const tool = {
name: 'submit_move_mcp_chess',
description: 'submits a move',
schema: z.object({ move: z.string() }),
invoke: async () => {
throw abortError;
},
} as unknown as StructuredToolInterface;
const eventActorDetachedAction = {
reserve: jest.fn(async () => ({
status: 'reserved' as const,
taskId: 'event-task-cancelled',
idempotencyKey: 'c'.repeat(64),
})),
markRunning: jest.fn(async () => true),
settle: jest.fn(async () => true),
wake: jest.fn(async () => undefined),
};
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
eventActorDetachedAction,
});
await runBatch(handler, {
toolCalls: [
{
id: 'call-cancelled',
name: tool.name,
args: { move: 'e4', run_in_background: true },
},
],
agentId: 'agent-player',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'event-conversation', run_id: 'event-response' },
});
await flushMicrotasks();
await flushMicrotasks();
expect(eventActorDetachedAction.settle).toHaveBeenCalledWith(
expect.objectContaining({ status: 'failed', error: 'operation aborted' }),
);
});
it('returns a handle immediately, runs the tool once detached, and yields the result via check_background_task', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig();
const metadata = { thread_id: 'exec_convo' };
const dispatchResults = await runBatch(handler, {
toolCalls: [
{
id: 'call_bg',
name: 'search_mcp_docs',
args: { q: 'librechat', run_in_background: true },
},
],
agentId: 'agent_1',
configurable,
metadata,
});
expect(dispatchResults).toHaveLength(1);
const handle = JSON.parse(dispatchResults[0].content);
expect(handle.status).toBe('running');
expect(typeof handle.background_task_id).toBe('string');
await flushMicrotasks();
await flushMicrotasks();
// real tool ran exactly once, without the injected flag
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ q: 'librechat' });
const pollResults = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handle.background_task_id },
},
],
agentId: 'agent_1',
configurable,
metadata,
});
const polled = JSON.parse(pollResults[0].content);
expect(polled.status).toBe('completed');
expect(polled.result).toContain('RESULT for librechat');
});
it('cancels a running background Bash mutation, reports settlement truthfully, and reuses the workspace', async () => {
let delayedWrites = 0;
let invocations = 0;
const bashTool = {
name: 'bash_tool',
description: 'runs a workspace command',
schema: z.object({ command: z.string() }),
invoke: jest.fn(
async (
input: { command: string },
config?: { signal?: AbortSignal },
): Promise<{ content: string }> => {
invocations += 1;
if (input.command === 'pwd') {
return { content: '/workspace' };
}
return await new Promise((resolve, reject) => {
const timer = setTimeout(() => {
delayedWrites += 1;
resolve({ content: 'late mutation completed' });
}, 50);
config?.signal?.addEventListener(
'abort',
() => {
clearTimeout(timer);
reject(
config.signal?.reason ??
new DOMException('Background task cancellation requested', 'AbortError'),
);
},
{ once: true },
);
});
},
),
} as unknown as StructuredToolInterface;
const persistBackgroundCodeResult = jest.fn(async () => ({ attachments: [] }));
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [bashTool] }),
ordinaryToolCancellation: true,
persistBackgroundCodeResult,
});
const configurable = buildConfig(['bash_tool']);
const metadata = { thread_id: 'cancel_bash_conversation', run_id: 'cancel-bash-run' };
const dispatch = await runBatch(handler, {
toolCalls: [
{
id: 'call_cancel_bash',
name: 'bash_tool',
stepId: 'step_cancel_bash',
args: { command: 'sleep-then-write', run_in_background: true },
},
],
agentId: 'agent_cancel_bash',
configurable,
metadata,
});
const taskId = JSON.parse(dispatch[0].content).background_task_id as string;
const cancellation = JSON.parse(
(
await runBatch(handler, {
toolCalls: [
{
id: 'call_cancel_control',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId, action: 'cancel' },
},
],
agentId: 'agent_cancel_bash',
configurable,
metadata,
})
)[0].content,
);
expect(cancellation).toMatchObject({
status: 'cancellation_requested',
cancellation_requested: true,
});
await flushMicrotasks();
await flushMicrotasks();
await new Promise((resolve) => setTimeout(resolve, 75));
const terminal = JSON.parse(
(
await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_cancelled_bash',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'agent_cancel_bash',
configurable,
metadata,
})
)[0].content,
);
expect(terminal).toMatchObject({
status: 'cancelled',
background_task_id: taskId,
});
expect(persistBackgroundCodeResult).toHaveBeenCalledWith(
expect.objectContaining({
backgroundTask: expect.objectContaining({ taskId, status: 'error', cancelled: true }),
}),
);
expect(persistBackgroundCodeResult).toHaveBeenCalledWith(
expect.objectContaining({
reapply: true,
output: expect.stringContaining('cancellation requested'),
backgroundTask: expect.objectContaining({
taskId,
status: 'error',
cancelled: true,
}),
}),
);
expect(delayedWrites).toBe(0);
const reused = await runBatch(handler, {
toolCalls: [
{
id: 'call_reuse_bash',
name: 'bash_tool',
args: { command: 'pwd', run_in_background: true },
},
],
agentId: 'agent_cancel_bash',
configurable,
metadata: { ...metadata, run_id: 'reuse-run' },
});
const reusedTaskId = JSON.parse(reused[0].content).background_task_id as string;
await flushMicrotasks();
await flushMicrotasks();
const reusedTerminal = JSON.parse(
await runCheckBackgroundTask({
userId: 'exec_user',
conversationId: 'cancel_bash_conversation',
args: { background_task_id: reusedTaskId },
}),
);
expect(reusedTerminal).toMatchObject({ status: 'completed', result: '/workspace' });
expect(invocations).toBe(2);
});
it('blocks normalized arguments before registering or dispatching a background task', async () => {
const protectedValue = 'PROTECTED-BACKGROUND';
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig(['search_mcp_docs'], {
toolArguments: {
pii: {
starterPatterns: [],
customPatterns: [
{
id: 'protected-value',
label: 'protected value',
regex: 'PROTECTED-[A-Z]+',
},
],
},
},
});
const results = await runBatch(handler, {
toolCalls: [
{
id: 'call_filtered_background',
name: 'search_mcp_docs',
args: { q: protectedValue, run_in_background: true },
},
],
agentId: 'agent_1',
configurable,
metadata: { thread_id: 'exec_convo_filtered' },
});
const result = results[0] as {
content: string;
status?: string;
errorMessage?: string;
};
await flushMicrotasks();
expect(result.status).toBe('error');
expect(result.content).toBe('');
expect(result.errorMessage).toContain('content_filter_block');
expect(result.errorMessage).not.toContain(protectedValue);
expect(state.calls).toBe(0);
});
it.each([
['bearer_header', 'Authorization: Bearer background-token', 'Bearer token'],
['api_key_header', 'api-key: background-token', 'api-key header'],
] as const)(
'keeps a blocked background %s result stable across repeated model-bound polls',
async (starterPattern, protectedValue, detectorLabel) => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig(['search_mcp_docs'], {
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: [starterPattern],
},
},
});
const metadata = { thread_id: `exec_convo_filtered_output_${starterPattern}` };
const dispatchResults = await runBatch(handler, {
toolCalls: [
{
id: `call_filtered_background_output_${starterPattern}`,
name: 'search_mcp_docs',
args: { q: protectedValue, run_in_background: true },
},
],
agentId: 'agent_1',
configurable,
metadata,
});
const handle = JSON.parse(dispatchResults[0].content);
await flushMicrotasks();
for (const pollSuffix of ['first', 'second']) {
const [pollResult] = (await runBatch(handler, {
toolCalls: [
{
id: `call_poll_filtered_output_${starterPattern}_${pollSuffix}`,
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handle.background_task_id },
},
],
agentId: 'agent_1',
configurable,
metadata,
})) as Array<{ content: string; status?: string; errorMessage?: string }>;
const polled = JSON.parse(pollResult.content);
expect(pollResult.status).toBe('success');
expect(pollResult.errorMessage).toBeUndefined();
expect(polled.status).toBe('error');
expect(JSON.parse(polled.error)).toEqual({
error: 'content_filter_block',
message: 'Submitted content was blocked by content policy.',
source: 'tool_argument',
field: 'output',
});
expect(JSON.stringify(polled)).not.toContain(protectedValue);
expect(JSON.stringify(polled)).not.toContain(detectorLabel);
}
expect(state.calls).toBe(1);
},
);
it('filters poll arguments before reading the background task registry', async () => {
const protectedValue = 'PROTECTED-POLL-ARGUMENT';
const debugSpy = jest.spyOn(logger, 'debug').mockReturnValue(logger);
try {
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [] }),
});
const configurable = buildConfig(['search_mcp_docs'], {
toolArguments: {
pii: {
fields: ['arguments'],
starterPatterns: [],
customPatterns: [
{
id: 'protected-argument',
label: 'protected argument',
regex: 'PROTECTED-[A-Z-]+',
},
],
},
},
});
const [result] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_filtered_poll_argument',
name: CHECK_BACKGROUND_TASK_NAME,
args: { submitted_selector: protectedValue },
},
],
agentId: 'agent_1',
configurable,
metadata: { thread_id: 'exec_convo_filtered_poll_argument' },
})) as Array<{ content: string; status?: string; errorMessage?: string }>;
expect(result.status).toBe('error');
expect(result.content).toBe('');
expect(result.errorMessage).toContain('content_filter_block');
expect(result.errorMessage).not.toContain(protectedValue);
expect(
debugSpy.mock.calls.some(([message]) =>
String(message).includes('check_background_task listed'),
),
).toBe(false);
} finally {
debugSpy.mockRestore();
}
});
it('re-inspects a pre-policy background artifact before poll callbacks or delivery', async () => {
const protectedValue = 'PROTECTED-TIGHTENED-POLL';
const artifact = { files: [protectedValue] };
const tool = {
name: 'search_mcp_docs',
description: 'returns historical protected output',
schema: z.object({ q: z.string() }),
invoke: async () => ({ content: 'safe historical result', artifact }),
} as unknown as StructuredToolInterface;
const toolEndCallback = jest.fn();
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
toolEndCallback,
});
const metadata = { thread_id: 'exec_convo_tightened_poll' };
const dispatchConfig = buildConfig(['search_mcp_docs']);
const [dispatch] = await runBatch(handler, {
toolCalls: [
{
id: 'call_pre_policy_background',
name: 'search_mcp_docs',
args: { q: 'historical', run_in_background: true },
},
],
agentId: 'agent_1',
configurable: dispatchConfig,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
const taskId = JSON.parse(dispatch.content).background_task_id;
const tightenedConfig = buildConfig(['search_mcp_docs'], {
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: [],
customPatterns: [
{
id: 'protected-output',
label: 'protected output',
regex: 'PROTECTED-[A-Z-]+',
},
],
},
},
});
const [blockedPoll] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_tightened_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'agent_1',
configurable: tightenedConfig,
metadata,
})) as Array<{ content: string; status?: string; errorMessage?: string }>;
expect(blockedPoll.status).toBe('error');
expect(blockedPoll.content).toBe('');
expect(blockedPoll.errorMessage).toContain('content_filter_block');
expect(blockedPoll.errorMessage).not.toContain(protectedValue);
expect(toolEndCallback).not.toHaveBeenCalled();
const [allowedPoll] = await runBatch(handler, {
toolCalls: [
{
id: 'call_unfiltered_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'agent_1',
configurable: dispatchConfig,
metadata,
});
expect(JSON.parse(allowedPoll.content).result).toBe('safe historical result');
expect(toolEndCallback).toHaveBeenCalledTimes(1);
/** Delivery callbacks must carry provenance: they report the ORIGINAL
* tool's name with the poll call's arguments, so identity-fencing
* consumers (the event-actor action recorder) can exclude them. */
expect(toolEndCallback).toHaveBeenCalledWith(
expect.objectContaining({
backgroundDelivery: true,
input: { background_task_id: taskId },
output: expect.objectContaining({ artifact }),
}),
expect.any(Object),
);
});
it('does not double-dispatch when the same tool call re-executes (resume/replay)', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig();
const metadata = { thread_id: 'exec_convo_dup' };
const toolCalls = [
{ id: 'call_same', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
];
const first = await runBatch(handler, { toolCalls, agentId: 'a', configurable, metadata });
await flushMicrotasks();
const second = await runBatch(handler, { toolCalls, agentId: 'a', configurable, metadata });
await flushMicrotasks();
const firstId = JSON.parse(first[0].content).background_task_id;
const secondId = JSON.parse(second[0].content).background_task_id;
expect(secondId).toBe(firstId);
expect(state.calls).toBe(1);
});
it('uses host step identity when repeated provider ids have no turn number', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeSearchTool(state)] }),
});
const results = await runBatch(handler, {
toolCalls: [
{
id: 'call_repeated',
name: 'search_mcp_docs',
args: { q: 'first', run_in_background: true },
stepId: 'step-first',
},
{
id: 'call_repeated',
name: 'search_mcp_docs',
args: { q: 'second', run_in_background: true },
stepId: 'step-second',
},
],
agentId: 'a',
configurable: buildConfig(),
metadata: { thread_id: 'exec_convo_repeated_steps', run_id: 'response-repeated' },
});
await flushMicrotasks();
expect(state.calls).toBe(2);
expect(JSON.parse(results[0].content).background_task_id).not.toBe(
JSON.parse(results[1].content).background_task_id,
);
});
it('runs the tool synchronously when background is not requested', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig();
const metadata = { thread_id: 'exec_convo_sync' };
const results = await runBatch(handler, {
toolCalls: [{ id: 'call_sync', name: 'search_mcp_docs', args: { q: 'now' } }],
agentId: 'a',
configurable,
metadata,
});
expect(state.calls).toBe(1);
expect(results[0].content).toContain('RESULT for now');
});
it('enforces the per-tool opt-in: a tool not in backgroundToolNames runs foreground even with the flag', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
// background enabled for the run, but for a DIFFERENT tool
const configurable = buildConfig(['some_other_tool']);
const metadata = { thread_id: 'exec_convo_gate' };
const results = await runBatch(handler, {
toolCalls: [
{ id: 'call_gate', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
],
agentId: 'a',
configurable,
metadata,
});
// ran in the foreground; result is the tool output, not a background handle
expect(state.calls).toBe(1);
expect(results[0].content).toContain('RESULT for x');
});
it('never backgrounds an ephemeral request-scoped MCP tool: runs it foreground (no detached, leak-free)', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const ephemeralTool = {
name: 'search_mcp_docs',
description: 'search docs',
schema: z.object({ q: z.string() }),
// Tagged in createToolInstance for servers on a runtime-body-placeholder
// connection, which is torn down at request end.
mcpRequiresEphemeralConnection: true,
invoke: async (input: Record<string, unknown>) => {
state.calls += 1;
state.lastInput = input;
return { content: `RESULT for ${String(input.q)}` };
},
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [ephemeralTool] }),
});
// background IS enabled for this tool, and the model asked to background it
const configurable = buildConfig();
const metadata = { thread_id: 'exec_convo_ephemeral' };
const results = await runBatch(handler, {
toolCalls: [
{ id: 'call_eph', name: 'search_mcp_docs', args: { q: 'z', run_in_background: true } },
],
agentId: 'a',
configurable,
metadata,
});
// ran synchronously in the foreground: real output inline, not a handle, flag stripped
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ q: 'z' });
expect(results[0].content).toContain('RESULT for z');
expect(results[0].content).not.toContain('background_task_id');
});
it('does not intercept a check_background_task-named tool when background is off for the run', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const collisionTool = {
name: CHECK_BACKGROUND_TASK_NAME,
description: 'a user MCP tool that happens to share the name',
schema: z.object({ q: z.string() }),
invoke: async (input: Record<string, unknown>) => {
state.calls += 1;
return { content: `REAL for ${String(input.q)}` };
},
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [collisionTool] }),
});
const configurable = buildConfig([]); // background not active for this run
const metadata = { thread_id: 'exec_convo_collision' };
const results = await runBatch(handler, {
toolCalls: [{ id: 'call_collision', name: CHECK_BACKGROUND_TASK_NAME, args: { q: 'y' } }],
agentId: 'a',
configurable,
metadata,
});
// the real tool ran; the host poll-tool shortcut did not swallow it
expect(state.calls).toBe(1);
expect(results[0].content).toContain('REAL for y');
});
it('strips run_in_background:false on a foreground call of a background-capable tool', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const searchTool = makeSearchTool(state);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [searchTool] }),
});
const configurable = buildConfig(['search_mcp_docs']);
const metadata = { thread_id: 'exec_convo_falseflag' };
const results = await runBatch(handler, {
toolCalls: [
{ id: 'call_false', name: 'search_mcp_docs', args: { q: 'z', run_in_background: false } },
],
agentId: 'a',
configurable,
metadata,
});
// ran in the foreground, and the injected flag never reached the real tool
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ q: 'z' });
expect(results[0].content).toContain('RESULT for z');
});
it('delivers a backgrounded tool artifact on poll (live turn), not on the finalized dispatch turn', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const artifactTool = {
name: 'search_mcp_docs',
description: 'returns an artifact',
schema: z.object({ q: z.string() }),
invoke: async (input: Record<string, unknown>) => {
state.calls += 1;
return { content: `RESULT for ${String(input.q)}`, artifact: { files: ['a.png'] } };
},
} as unknown as StructuredToolInterface;
const toolEndCalls: Array<{ name?: string; artifact?: unknown }> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [artifactTool] }),
toolEndCallback: (async (data: { output?: { name?: string; artifact?: unknown } }) => {
toolEndCalls.push({ name: data.output?.name, artifact: data.output?.artifact });
}) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
});
const configurable = buildConfig(['search_mcp_docs']);
const metadata = { thread_id: 'exec_convo_artifact', run_id: 'run-artifact' };
const dispatch = await runBatch(handler, {
toolCalls: [
{ id: 'call_art', name: 'search_mcp_docs', args: { q: 'img', run_in_background: true } },
],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
// the tool ran, but its artifact is NOT pushed through the finalized dispatch turn
expect(state.calls).toBe(1);
expect(toolEndCalls).toHaveLength(0);
const handleId = JSON.parse(dispatch[0].content).background_task_id;
const poll = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_artifact', run_id: 'run-poll' },
});
// the poll turn delivers the artifact once, attributed to the original tool
expect(JSON.parse(poll[0].content).status).toBe('completed');
expect(toolEndCalls).toHaveLength(1);
expect(toolEndCalls[0]).toEqual({ name: 'search_mcp_docs', artifact: { files: ['a.png'] } });
// polling again does not re-deliver (idempotent)
await runBatch(handler, {
toolCalls: [
{
id: 'call_poll2',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_artifact', run_id: 'run-poll2' },
});
expect(toolEndCalls).toHaveLength(1);
});
it('scopes tasks by configurable user_id when req is absent (external service hosts)', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeSearchTool(state)] }),
});
const configurable = {
user_id: 'exec_user_external',
backgroundToolNames: ['search_mcp_docs'],
};
const metadata = { thread_id: 'exec_convo_external', run_id: 'run-external' };
const dispatch = await runBatch(handler, {
toolCalls: [
{ id: 'call_ext', name: 'search_mcp_docs', args: { q: 'ping', run_in_background: true } },
],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
const handleId = JSON.parse(dispatch[0].content).background_task_id;
const poll = await runBatch(handler, {
toolCalls: [
{
id: 'call_ext_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_external', run_id: 'run-external-poll' },
});
const polled = JSON.parse(poll[0].content);
expect(polled.status).toBe('completed');
expect(polled.result).toContain('RESULT for ping');
// a different user id cannot see the task (isolation is not conversation-only)
const foreign = await runBatch(handler, {
toolCalls: [
{
id: 'call_foreign_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable: { user_id: 'someone_else', backgroundToolNames: ['search_mcp_docs'] },
metadata: { thread_id: 'exec_convo_external', run_id: 'run-foreign' },
});
expect(JSON.parse(foreign[0].content).status).toBe('not_found');
});
it('errors immediately (like foreground) when a background-requested tool failed to load', async () => {
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [] }),
});
const results = (await runBatch(handler, {
toolCalls: [
{ id: 'call_missing', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
],
agentId: 'a',
configurable: buildConfig(['search_mcp_docs']),
metadata: { thread_id: 'exec_convo_missing', run_id: 'run-missing' },
})) as Array<{ content: string; status?: string; errorMessage?: string }>;
expect(results[0].status).toBe('error');
expect(results[0].errorMessage).toBe('Tool search_mcp_docs not found');
expect(results[0].content).not.toContain('background_task_id');
});
it('strips a run_in_background arg imitated onto a tool this agent never opted in', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeSearchTool(state)] }),
});
// background is enabled for the run via another tool; search_mcp_docs is NOT opted in
await runBatch(handler, {
toolCalls: [
{
id: 'call_foreign',
name: 'search_mcp_docs',
args: { q: 'hello', run_in_background: true },
},
],
agentId: 'a',
configurable: buildConfig(['other_tool']),
metadata: { thread_id: 'exec_convo_foreign', run_id: 'run-foreign' },
});
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ q: 'hello' });
});
it('forwards run_in_background untouched to a tool whose own schema declares it', async () => {
const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
const owningTool = {
name: 'owns_the_param',
description: 'declares run_in_background itself',
schema: z.object({ q: z.string(), run_in_background: z.boolean().optional() }),
invoke: async (input: Record<string, unknown>) => {
state.calls += 1;
state.lastInput = input;
return { content: 'OWNED' };
},
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [owningTool] }),
});
await runBatch(handler, {
toolCalls: [
{
id: 'call_owned',
name: 'owns_the_param',
args: { q: 'hello', run_in_background: true },
},
],
agentId: 'a',
configurable: buildConfig(['other_tool']),
metadata: { thread_id: 'exec_convo_owned', run_id: 'run-owned' },
});
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ q: 'hello', run_in_background: true });
});
it('retries artifact delivery on the next poll when the callback fails (artifact not lost)', async () => {
const artifactTool = {
name: 'search_mcp_docs',
description: 'returns an artifact',
schema: z.object({ q: z.string() }),
invoke: async () => ({ content: 'RESULT', artifact: { files: ['a.png'] } }),
} as unknown as StructuredToolInterface;
const toolEndCalls: Array<{ name?: string; artifact?: unknown }> = [];
let failNextDelivery = true;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [artifactTool] }),
toolEndCallback: (async (data: { output?: { name?: string; artifact?: unknown } }) => {
if (failNextDelivery) {
failNextDelivery = false;
throw new Error('transient storage failure');
}
toolEndCalls.push({ name: data.output?.name, artifact: data.output?.artifact });
}) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
});
const configurable = buildConfig(['search_mcp_docs']);
const dispatch = await runBatch(handler, {
toolCalls: [
{ id: 'call_art', name: 'search_mcp_docs', args: { q: 'img', run_in_background: true } },
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-artifact' },
});
await flushMicrotasks();
await flushMicrotasks();
const handleId = JSON.parse(dispatch[0].content).background_task_id;
// first poll: delivery fails, but the poll itself still succeeds
const poll1 = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-poll' },
});
expect(JSON.parse(poll1[0].content).status).toBe('completed');
expect(toolEndCalls).toHaveLength(0);
// second poll: the restored artifact is re-claimed and delivered
await runBatch(handler, {
toolCalls: [
{
id: 'call_poll2',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handleId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-poll2' },
});
expect(toolEndCalls).toHaveLength(1);
expect(toolEndCalls[0]).toEqual({ name: 'search_mcp_docs', artifact: { files: ['a.png'] } });
});
});
describe('createToolExecuteHandler — backgrounded code execution', () => {
interface CodeToolState {
calls: number;
throwError?: boolean;
errorMessage?: string;
lastInput?: Record<string, unknown>;
lastConfig?: { toolCall?: Record<string, unknown> };
}
const CODE_ARTIFACT = {
session_id: 'exec-sess',
files: [{ id: 'f1', name: 'plot.png', storage_session_id: 'store-1' }],
};
const makeCodeTool = (state: CodeToolState) =>
({
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async (
input: Record<string, unknown>,
config: { toolCall?: Record<string, unknown> },
) => {
state.calls += 1;
state.lastInput = input;
state.lastConfig = config;
if (state.throwError) {
throw new Error(state.errorMessage ?? 'Execution error:\n\nboom');
}
return { content: 'stdout:\nhello', artifact: CODE_ARTIFACT };
},
}) as unknown as StructuredToolInterface;
const codeCall = (overrides: Record<string, unknown> = {}) => ({
id: 'call_code',
name: 'execute_code',
args: { lang: 'py', code: 'print(1)', run_in_background: true },
stepId: 'step_1',
turn: 2,
codeSessionContext: {
session_id: 'sess-prev',
files: [{ id: 'in1', name: 'data.csv', storage_session_id: 'store-0', resource_id: 'r1' }],
},
runtimeSessionHint: 'convo-hint',
...overrides,
});
it('keeps step-less code harvests available to the legacy poll path', async () => {
const state: CodeToolState = { calls: 0 };
const preregister = jest.fn(async () => ({
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
}));
const persistBackgroundCodeResult = jest.fn(async () => ({ attachments: [] }));
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
persistBackgroundCodeResult,
backgroundToolCompletion: {
preregister,
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_step_less_code', run_id: 'response-step-less' };
const [dispatch] = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_step_less_code', stepId: undefined, turn: undefined })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
expect(preregister).not.toHaveBeenCalled();
expect(persistBackgroundCodeResult).toHaveBeenCalledWith(
expect.not.objectContaining({ backgroundTask: expect.anything() }),
);
const taskId = JSON.parse(dispatch.content).background_task_id;
const [poll] = (await runBatch(handler, {
toolCalls: [
{
id: 'poll_step_less_code',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: metadata.thread_id, run_id: 'poll-step-less' },
})) as Array<{ content: string; artifact?: unknown }>;
await flushMicrotasks();
expect(JSON.parse(poll.content)).toMatchObject({ status: 'completed' });
expect(poll.artifact).toEqual(CODE_ARTIFACT);
expect(persistBackgroundCodeResult).toHaveBeenCalledTimes(2);
expect(persistBackgroundCodeResult).toHaveBeenLastCalledWith(
expect.objectContaining({
reapply: true,
toolCallId: 'call_step_less_code',
stepId: undefined,
}),
);
});
it('carries full code-session config into the detached invoke, harvests onto the dispatch turn, and re-emits on poll', async () => {
const state: CodeToolState = { calls: 0 };
const persistCalls: Array<Record<string, unknown>> = [];
const emitted: unknown[] = [];
const toolEndCalls: unknown[] = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
toolEndCallback: (async (data: { output?: unknown }) => {
toolEndCalls.push(data.output);
}) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [{ file_id: 'f1', toolCallId: params.toolCallId }] };
},
emitAttachment: (attachment) => {
emitted.push(attachment);
},
});
const codeExecutionContext = {
baseUrl: 'https://code-stateful.example.com',
codeSessionKey: 'execute_code:stateful:convo-hint',
executionProfile: 'stateful' as const,
runtimeSessionHint: 'convo-hint',
statefulSessions: true,
};
const configurable = { ...buildConfig(['execute_code']), codeExecutionContext };
const metadata = { thread_id: 'exec_convo_code', run_id: 'msg-dispatch' };
const dispatch = await runBatch(handler, {
toolCalls: [codeCall()],
agentId: 'a',
configurable,
metadata,
});
const handle = JSON.parse(dispatch[0].content);
expect(handle.status).toBe('running');
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
// detached invoke received the same session/file config a foreground call gets
expect(state.calls).toBe(1);
expect(state.lastInput).toEqual({ lang: 'py', code: 'print(1)' });
const toolCall = state.lastConfig?.toolCall ?? {};
expect(toolCall.session_id).toBe('sess-prev');
expect(toolCall._injected_files).toEqual([
{ id: 'in1', name: 'data.csv', storage_session_id: 'store-0', resource_id: 'r1' },
]);
expect(toolCall._runtime_session_hint).toBe('convo-hint');
expect(toolCall.id).toBe('call_code');
expect(toolCall.stepId).toBe('step_1');
// completion-time harvest anchored to the ORIGINAL dispatch identity
expect(persistCalls).toHaveLength(1);
expect(persistCalls[0]).toEqual(
expect.objectContaining({
toolName: 'execute_code',
toolCallId: 'call_code',
messageId: 'msg-dispatch',
conversationId: 'exec_convo_code',
dispatchedAt: expect.any(Number),
output: 'stdout:\nhello',
artifact: CODE_ARTIFACT,
codeExecutionContext,
}),
);
// nothing rode the finalized dispatch turn's callback
expect(toolEndCalls).toHaveLength(0);
const poll = (await runBatch(handler, {
toolCalls: [
{
id: 'call_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: handle.background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code', run_id: 'msg-poll' },
})) as Array<{ content: string; artifact?: unknown }>;
await flushMicrotasks();
const polled = JSON.parse(poll[0].content);
expect(polled.status).toBe('completed');
expect(polled.result).toContain('hello');
expect(polled.note).toContain('attached to the tool call');
// harvested attachments re-emitted on the live poll stream (not
// re-processed), followed by the live completion marker
expect(emitted).toEqual([
{ file_id: 'f1', toolCallId: 'call_code' },
expect.objectContaining({
type: 'background_task_status',
/** Agent-suffixed: sibling agents' `call_0` markers must not upsert
* over each other client-side. */
file_id: 'bg-call_code-a-step_1',
messageId: 'msg-dispatch',
toolCallId: 'call_code',
stepId: 'step_1',
status: 'completed',
}),
]);
expect(toolEndCalls).toHaveLength(0);
// the claimed artifact rides the poll result so the SDK folds the exec session
expect(poll[0].artifact).toEqual(CODE_ARTIFACT);
// the poll also re-anchors the row patch (idempotent heal after full-row saves)
expect(persistCalls).toHaveLength(2);
expect(persistCalls[1]).toEqual(
expect.objectContaining({
reapply: true,
toolCallId: 'call_code',
messageId: 'msg-dispatch',
output: 'stdout:\nhello',
attachments: [{ file_id: 'f1', toolCallId: 'call_code' }],
}),
);
});
it('blocks a pre-policy code artifact before poll claim, emission, or re-persistence', async () => {
const protectedValue = 'PROTECTED-CODE-ARTIFACT';
const artifact = {
session_id: 'exec-protected',
files: [{ id: 'f-protected', name: protectedValue }],
};
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => ({ content: 'safe stdout', artifact }),
} as unknown as StructuredToolInterface;
const persistCalls: Array<Record<string, unknown>> = [];
const emitted: unknown[] = [];
const toolEndCallback = jest.fn();
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
toolEndCallback,
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [{ file_id: 'f-protected', name: 'safe attachment' }] };
},
emitAttachment: (attachment) => {
emitted.push(attachment);
},
});
const metadata = { thread_id: 'exec_convo_tightened_code', run_id: 'msg-dispatch' };
const dispatchConfig = buildConfig(['execute_code']);
const [dispatch] = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_pre_policy_code' })],
agentId: 'a',
configurable: dispatchConfig,
metadata,
});
const taskId = JSON.parse(dispatch.content).background_task_id;
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistCalls).toHaveLength(1);
persistCalls.length = 0;
const tightenedConfig = buildConfig(['execute_code'], {
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: [],
customPatterns: [
{
id: 'protected-output',
label: 'protected output',
regex: 'PROTECTED-[A-Z-]+',
},
],
},
},
});
const [blockedPoll] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_tightened_code_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable: tightenedConfig,
metadata: { thread_id: 'exec_convo_tightened_code', run_id: 'msg-poll' },
})) as Array<{
content: string;
status?: string;
errorMessage?: string;
artifact?: unknown;
}>;
await flushMicrotasks();
expect(blockedPoll.status).toBe('error');
expect(blockedPoll.content).toBe('');
expect(blockedPoll.errorMessage).toContain('content_filter_block');
expect(blockedPoll.errorMessage).not.toContain(protectedValue);
expect(blockedPoll.artifact).toBeUndefined();
expect(toolEndCallback).not.toHaveBeenCalled();
expect(emitted).toEqual([]);
expect(persistCalls).toEqual([]);
const [allowedPoll] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_allowed_code_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable: dispatchConfig,
metadata: { thread_id: 'exec_convo_tightened_code', run_id: 'msg-poll-allowed' },
})) as Array<{ content: string; artifact?: unknown }>;
expect(JSON.parse(allowedPoll.content).result).toBe('safe stdout');
expect(allowedPoll.artifact).toEqual(artifact);
});
it('does not gate task completion on the harvest (same-turn polls see completed)', async () => {
const state: CodeToolState = { calls: 0 };
const toolEndCalls: unknown[] = [];
const emitted: unknown[] = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
toolEndCallback: (async (data: { output?: unknown }) => {
toolEndCalls.push(data.output);
}) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
/** The dispatch turn's row does not exist until that turn finalizes, so
* the real persister can block for a long time — completion must not. */
persistBackgroundCodeResult: () => new Promise(() => undefined),
emitAttachment: (attachment) => {
emitted.push(attachment);
},
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_code_slow', run_id: 'msg-slow' };
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_slow' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
const poll = (await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_slow',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_slow', run_id: 'msg-slow-poll' },
})) as Array<{ content: string; artifact?: unknown }>;
const polled = JSON.parse(poll[0].content);
expect(polled.status).toBe('completed');
expect(polled.result).toContain('hello');
expect(polled.note).toContain('being attached');
// Harvest has not landed: no artifact, attachments, status marker, or
// poll-identity fallback may cross the live boundary before file inspection.
expect(emitted).toEqual([]);
expect(toolEndCalls).toHaveLength(0);
expect(poll[0].artifact).toBeUndefined();
});
it('releases stored files to same-turn polls while the row patch waits for the dispatch turn', async () => {
const state: CodeToolState = { calls: 0 };
const emitted: unknown[] = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
/** Files are stored; the row patch then waits for the long dispatch turn. */
persistBackgroundCodeResult: (params) => {
params.onFilesPersisted?.([{ file_id: 'f1', toolCallId: params.toolCallId }]);
return new Promise(() => undefined);
},
emitAttachment: (attachment) => {
emitted.push(attachment);
},
});
const configurable = buildConfig(['execute_code']);
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_long_turn' })],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_long_turn', run_id: 'msg-long-turn' },
});
await flushMicrotasks();
await flushMicrotasks();
const poll = (await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_long_turn',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_long_turn', run_id: 'msg-long-turn' },
})) as Array<{ content: string; artifact?: unknown }>;
const polled = JSON.parse(poll[0].content);
expect(polled.status).toBe('completed');
expect(polled.note).toContain('attached to the tool call');
expect(emitted[0]).toEqual({ file_id: 'f1', toolCallId: 'call_code_long_turn' });
expect(poll[0].artifact).toEqual(CODE_ARTIFACT);
/** Still protected from retention eviction while the row patch waits. */
expect(
backgroundTaskRegistry.get(
'exec_user',
'exec_convo_code_long_turn',
JSON.parse(dispatch[0].content).background_task_id,
)?.completionPersistencePending,
).toBe(true);
});
it('falls back to poll-turn delivery when the harvest fails (files not lost)', async () => {
const state: CodeToolState = { calls: 0 };
const toolEndCalls: Array<{ name?: string; artifact?: unknown }> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
toolEndCallback: (async (data: { output?: { name?: string; artifact?: unknown } }) => {
toolEndCalls.push({ name: data.output?.name, artifact: data.output?.artifact });
}) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
persistBackgroundCodeResult: async () => {
throw new Error('mongo down');
},
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_code_hfail', run_id: 'msg-hfail' };
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_hfail' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
const poll = (await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_hfail',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_hfail', run_id: 'msg-hfail-poll' },
})) as Array<{ content: string; artifact?: unknown }>;
/** Harvest revoked: the poll turn's callback processes the files instead. */
expect(toolEndCalls).toHaveLength(1);
expect(toolEndCalls[0].artifact).toEqual(CODE_ARTIFACT);
expect(poll[0].artifact).toEqual(CODE_ARTIFACT);
});
it('does not publish an output-only receipt when generated files miss their message anchor', async () => {
const state: CodeToolState = { calls: 0 };
const retire = jest.fn(async () => true);
const persistResult = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
persistBackgroundCodeResult: async () => ({
deliveryReady: false,
attachments: [{ filename: 'plot.png' }],
}),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
persistResult,
retire,
})),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_missing_anchor' })],
agentId: 'a',
configurable: buildConfig(['execute_code']),
metadata: { thread_id: 'exec_convo_code_missing_anchor', run_id: 'msg-missing-anchor' },
});
await flushMicrotasks();
await flushMicrotasks();
expect(persistResult).not.toHaveBeenCalled();
expect(retire).toHaveBeenCalledWith('background code result was not persisted', undefined);
});
it('uses the configured durable completion result size', async () => {
const persistResult: jest.MockedFunction<
NonNullable<BackgroundToolWakeupAdmission['persistResult']>
> = jest.fn(
async (_result: Parameters<NonNullable<BackgroundToolWakeupAdmission['persistResult']>>[0]) =>
true,
);
const tool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: jest.fn(async () => ({ content: '0123456789'.repeat(10), artifact: CODE_ARTIFACT })),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [tool] }),
backgroundCompletionResultMaxChars: 32,
persistBackgroundCodeResult: async () => ({ deliveryReady: true, attachments: [] }),
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
persistResult,
retire: jest.fn(async () => true),
})),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
await runBatch(handler, {
toolCalls: [codeCall({ id: 'call-sized-receipt' })],
agentId: 'agent_parent_1',
configurable: buildConfig([tool.name]),
metadata: { thread_id: 'exec_convo', run_id: 'response-sized-receipt' },
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistResult).toHaveBeenCalledWith(
expect.objectContaining({ status: 'completed', output: expect.any(String) }),
);
expect(persistResult.mock.calls[0][0].output).toHaveLength(32);
});
it('makes a completion-time generated-file policy rejection terminal across polls', async () => {
const protectedValue = 'PROTECTED-GENERATED-FILE-BYTES';
const blockedArtifact = {
session_id: 'exec-blocked',
files: [{ id: 'f-blocked', name: 'output.txt', opaqueBytes: protectedValue }],
};
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => ({ content: 'safe stdout', artifact: blockedArtifact }),
} as unknown as StructuredToolInterface;
const persistBackgroundCodeResult = jest.fn(async () => {
throw new ContentFilterError({
detectorId: 'custom',
ruleId: 'blocked-generated-file',
label: 'protected generated-file content',
source: 'file',
field: 'content',
provenance: 'tool',
fragmentId: 'generated-file',
fragmentPath: '/content',
});
});
const toolEndCallback = jest.fn();
const retire = jest.fn(async () => true);
const persistResult = jest.fn(async () => true);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
toolEndCallback,
persistBackgroundCodeResult,
backgroundToolCompletion: {
preregister: jest.fn(async () => ({
renew: jest.fn(async () => true),
retire,
persistResult,
})),
persist: jest.fn(async () => true),
claim: jest.fn(async () => ({ status: 'acquired' as const, results: [] })),
},
});
const configurable = buildConfig(['execute_code']);
const metadata = {
thread_id: 'exec_convo_code_policy_reject',
run_id: 'msg-policy-reject',
};
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_policy_reject' })],
agentId: 'a',
configurable,
metadata,
});
const taskId = JSON.parse(dispatch[0].content).background_task_id;
await flushMicrotasks();
await flushMicrotasks();
expect(persistResult).toHaveBeenCalledWith(
expect.objectContaining({ status: 'error', output: MODEL_BOUND_FILE_CONTENT_BLOCK }),
);
expect(retire).not.toHaveBeenCalled();
await flushMicrotasks();
for (const pollId of ['call_policy_poll_1', 'call_policy_poll_2']) {
const [poll] = (await runBatch(handler, {
toolCalls: [
{
id: pollId,
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_code_policy_reject',
run_id: `msg-${pollId}`,
},
})) as Array<{ content: string; artifact?: unknown }>;
const polled = JSON.parse(poll.content);
expect(polled).toEqual(
expect.objectContaining({
status: 'error',
error: MODEL_BOUND_FILE_CONTENT_BLOCK,
}),
);
expect(polled.result).toBeUndefined();
expect(poll.artifact).toBeUndefined();
expect(JSON.stringify(poll)).not.toContain(protectedValue);
}
expect(persistBackgroundCodeResult).toHaveBeenCalledTimes(1);
expect(toolEndCallback).not.toHaveBeenCalled();
});
it('withholds code-session artifacts while completion-time file inspection is pending', async () => {
const protectedValue = 'PROTECTED-PENDING-HARVEST-BYTES';
const blockedArtifact = {
session_id: 'exec-pending-blocked',
files: [{ id: 'f-pending-blocked', name: 'output.txt', opaqueBytes: protectedValue }],
};
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => ({ content: 'safe stdout', artifact: blockedArtifact }),
} as unknown as StructuredToolInterface;
let rejectInspection: (error: Error) => void = () => undefined;
const persistBackgroundCodeResult = jest.fn(
() =>
new Promise<never>((_resolve, reject) => {
rejectInspection = reject;
}),
);
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
persistBackgroundCodeResult,
});
const configurable = buildConfig(['execute_code']);
const metadata = {
thread_id: 'exec_convo_code_pending_policy',
run_id: 'msg-pending-policy',
};
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_pending_policy' })],
agentId: 'a',
configurable,
metadata,
});
const taskId = JSON.parse(dispatch[0].content).background_task_id;
await flushMicrotasks();
const [pendingPoll] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_pending_policy_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_code_pending_policy',
run_id: 'msg-pending-policy-poll',
},
})) as Array<{ content: string; artifact?: unknown }>;
expect(JSON.parse(pendingPoll.content).status).toBe('completed');
expect(pendingPoll.artifact).toBeUndefined();
expect(JSON.stringify(pendingPoll)).not.toContain(protectedValue);
rejectInspection(
new ContentFilterError({
detectorId: 'custom',
ruleId: 'blocked-pending-file',
label: 'protected generated-file content',
source: 'file',
field: 'content',
provenance: 'tool',
fragmentId: 'pending-generated-file',
fragmentPath: '/content',
}),
);
await flushMicrotasks();
await flushMicrotasks();
const [blockedPoll] = (await runBatch(handler, {
toolCalls: [
{
id: 'call_blocked_after_pending_poll',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_code_pending_policy',
run_id: 'msg-blocked-after-pending',
},
})) as Array<{ content: string; artifact?: unknown }>;
expect(JSON.parse(blockedPoll.content)).toEqual(
expect.objectContaining({
status: 'error',
error: MODEL_BOUND_FILE_CONTENT_BLOCK,
}),
);
expect(blockedPoll.artifact).toBeUndefined();
expect(JSON.stringify(blockedPoll)).not.toContain(protectedValue);
});
it('makes a poll-time generated-file policy rejection terminal without delivering bytes', async () => {
const protectedValue = 'PROTECTED-POLL-FALLBACK-BYTES';
const blockedArtifact = {
session_id: 'exec-poll-blocked',
files: [{ id: 'f-poll-blocked', name: 'output.txt', opaqueBytes: protectedValue }],
};
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => ({ content: 'safe stdout', artifact: blockedArtifact }),
} as unknown as StructuredToolInterface;
const persistBackgroundCodeResult = jest.fn(async () => {
throw new Error('temporary harvest storage failure');
});
const toolEndCallback = jest.fn(async () => {
throw new ContentFilterError({
detectorId: 'custom',
ruleId: 'blocked-poll-file',
label: 'protected generated-file content',
source: 'file',
field: 'content',
provenance: 'tool',
fragmentId: 'poll-generated-file',
fragmentPath: '/content',
});
});
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
toolEndCallback: toolEndCallback as unknown as Parameters<
typeof createToolExecuteHandler
>[0]['toolEndCallback'],
persistBackgroundCodeResult,
});
const configurable = buildConfig(['execute_code']);
const metadata = {
thread_id: 'exec_convo_code_poll_policy_reject',
run_id: 'msg-poll-policy-reject',
};
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_poll_policy_reject' })],
agentId: 'a',
configurable,
metadata,
});
const taskId = JSON.parse(dispatch[0].content).background_task_id;
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
for (const pollId of ['call_poll_policy_reject_1', 'call_poll_policy_reject_2']) {
const [poll] = (await runBatch(handler, {
toolCalls: [
{
id: pollId,
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: taskId },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_code_poll_policy_reject',
run_id: `msg-${pollId}`,
},
})) as Array<{ content: string; artifact?: unknown }>;
const polled = JSON.parse(poll.content);
expect(polled).toEqual(
expect.objectContaining({
status: 'error',
error: MODEL_BOUND_FILE_CONTENT_BLOCK,
}),
);
expect(polled.result).toBeUndefined();
expect(poll.artifact).toBeUndefined();
expect(JSON.stringify(poll)).not.toContain(protectedValue);
}
expect(persistBackgroundCodeResult).toHaveBeenCalledTimes(1);
expect(toolEndCallback).toHaveBeenCalledTimes(1);
});
it('re-anchors failed code tasks on poll (error output heals like success)', async () => {
const state: CodeToolState = { calls: 0, throwError: true };
const persistCalls: Array<Record<string, unknown>> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_code_errheal', run_id: 'msg-errheal' };
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_errheal' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_errheal',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_errheal', run_id: 'msg-errheal-poll' },
});
await flushMicrotasks();
expect(persistCalls).toHaveLength(2);
expect(persistCalls[1]).toEqual(
expect.objectContaining({ reapply: true, toolCallId: 'call_code_errheal' }),
);
expect(String(persistCalls[1].output)).toContain('boom');
});
it('wraps filtered background code output before registry and harvest persistence', async () => {
const protectedValue = 'Authorization: Bearer returned-background-token';
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => ({ content: protectedValue }),
} as unknown as StructuredToolInterface;
const persistCalls: Array<Record<string, unknown>> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code'], {
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: ['bearer_header'],
},
},
});
const metadata = {
thread_id: 'exec_convo_filtered_background_result',
run_id: 'msg-filtered-result',
};
const [dispatch] = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_filtered_background_result' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistCalls).toHaveLength(1);
expect(persistCalls[0].output).toBe(CODE_TOOL_OUTPUT_BLOCK);
expect(JSON.stringify(persistCalls)).not.toContain(protectedValue);
expect(JSON.stringify(persistCalls)).not.toContain('Bearer token');
const [poll] = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_filtered_background_result',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch.content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_filtered_background_result',
run_id: 'msg-filtered-result-poll',
},
});
const polled = JSON.parse(poll.content);
expect(polled).toEqual(
expect.objectContaining({
status: 'error',
error: CODE_TOOL_OUTPUT_BLOCK,
}),
);
expect(JSON.stringify(polled)).not.toContain(protectedValue);
expect(JSON.stringify(polled)).not.toContain('Bearer token');
});
it('filters thrown background errors before registry, harvest, and persistence', async () => {
const protectedValue = 'Authorization: Bearer persisted-background-token';
const state: CodeToolState = {
calls: 0,
throwError: true,
errorMessage: protectedValue,
};
const persistCalls: Array<Record<string, unknown>> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code'], {
toolArguments: {
pii: {
fields: ['output'],
starterPatterns: ['bearer_header'],
},
},
});
const metadata = {
thread_id: 'exec_convo_filtered_background_error',
run_id: 'msg-filtered-error',
};
const [dispatch] = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_filtered_background_error' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistCalls).toHaveLength(1);
expect(persistCalls[0].output).toBe(CODE_TOOL_OUTPUT_BLOCK);
expect(JSON.stringify(persistCalls)).not.toContain(protectedValue);
expect(JSON.stringify(persistCalls)).not.toContain('Bearer token');
const [poll] = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_filtered_background_error',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch.content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_filtered_background_error',
run_id: 'msg-filtered-error-poll',
},
});
const polled = JSON.parse(poll.content);
expect(polled.status).toBe('error');
expect(polled.error).toBe(CODE_TOOL_OUTPUT_BLOCK);
expect(JSON.stringify(polled)).not.toContain(protectedValue);
expect(JSON.stringify(polled)).not.toContain('Bearer token');
});
it('wraps a thrown background content-policy error without detector details', async () => {
const detectorLabel = 'generated-file bearer token';
const detectorRule = 'generated-file-bearer';
const codeTool = {
name: 'execute_code',
description: 'run code',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: async () => {
throw new ContentFilterError({
detectorId: 'pii-pattern',
ruleId: detectorRule,
label: detectorLabel,
source: 'file',
field: 'content',
provenance: 'tool',
fragmentId: 'generated-file',
fragmentPath: '/content',
});
},
} as unknown as StructuredToolInterface;
const persistCalls: Array<Record<string, unknown>> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [codeTool] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code']);
const metadata = {
thread_id: 'exec_convo_policy_background_error',
run_id: 'msg-policy-error',
};
const [dispatch] = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_policy_background_error' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistCalls).toHaveLength(1);
expect(persistCalls[0].output).toBe(CODE_FILE_CONTENT_BLOCK);
expect(JSON.stringify(persistCalls)).not.toContain(detectorLabel);
expect(JSON.stringify(persistCalls)).not.toContain(detectorRule);
const [poll] = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_policy_background_error',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch.content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: {
thread_id: 'exec_convo_policy_background_error',
run_id: 'msg-policy-error-poll',
},
});
const polled = JSON.parse(poll.content);
expect(polled).toEqual(
expect.objectContaining({
status: 'error',
error: CODE_FILE_CONTENT_BLOCK,
}),
);
expect(JSON.stringify(polled)).not.toContain(detectorLabel);
expect(JSON.stringify(polled)).not.toContain(detectorRule);
});
it('re-anchors abort-confirmed timeout failures with the client-recognized wrapper', async () => {
jest.useFakeTimers({ doNotFake: ['setImmediate'] });
try {
const persistCalls: Array<Record<string, unknown>> = [];
const hangingTool = {
name: 'execute_code',
description: 'never settles',
schema: z.object({ lang: z.string(), code: z.string() }),
invoke: (_input: unknown, config?: { signal?: AbortSignal }) =>
new Promise((_resolve, reject) => {
const signal = config?.signal;
if (signal?.aborted === true) {
reject(signal.reason);
return;
}
signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
}),
} as unknown as StructuredToolInterface;
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [hangingTool] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code']);
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_reap' })],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_reap', run_id: 'msg-reap' },
});
/** Past the deadline the tool acknowledges abort by rejecting. */
jest.advanceTimersByTime(31 * 60 * 1000);
await flushMicrotasks();
await flushMicrotasks();
const poll = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_reap',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_reap', run_id: 'msg-reap-poll' },
});
await flushMicrotasks();
expect(JSON.parse(poll[0].content).status).toBe('error');
const timeoutPersistence = persistCalls.find((call) =>
String(call.output).includes('timed out'),
);
expect(timeoutPersistence).toBeDefined();
expect(String(timeoutPersistence?.output)).toMatch(
/^Error:\s*\[execute_code\]\s*tool call failed:/,
);
} finally {
jest.useRealTimers();
}
});
it('patches the dispatch turn with the error message when a backgrounded code call fails', async () => {
const state: CodeToolState = { calls: 0, throwError: true };
const persistCalls: Array<Record<string, unknown>> = [];
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
persistBackgroundCodeResult: async (params) => {
persistCalls.push(params as unknown as Record<string, unknown>);
return { attachments: [] };
},
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_code_err', run_id: 'msg-err' };
const dispatch = await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_err' })],
agentId: 'a',
configurable,
metadata,
});
await flushMicrotasks();
await flushMicrotasks();
await flushMicrotasks();
expect(persistCalls).toHaveLength(1);
expect(String(persistCalls[0].output)).toContain('boom');
/** Parity with foreground failures (the graph's error wrapper) so the
* client's `isError` detection flags the patched output on reload. */
expect(String(persistCalls[0].output)).toMatch(
/^Error:\s*\[execute_code\]\s*tool call failed:/,
);
expect(String(persistCalls[0].output).match(/tool call failed:/gi)).toHaveLength(1);
expect(persistCalls[0].artifact).toBeUndefined();
const poll = await runBatch(handler, {
toolCalls: [
{
id: 'call_poll_err',
name: CHECK_BACKGROUND_TASK_NAME,
args: { background_task_id: JSON.parse(dispatch[0].content).background_task_id },
},
],
agentId: 'a',
configurable,
metadata: { thread_id: 'exec_convo_code_err', run_id: 'msg-err-poll' },
});
const polled = JSON.parse(poll[0].content);
expect(polled.status).toBe('error');
expect(polled.error).toContain('boom');
});
it('downgrades code calls to foreground when the host wires no persister (OpenAI-compat routes)', async () => {
const state: CodeToolState = { calls: 0 };
const handler = createToolExecuteHandler({
loadTools: async () => ({ loadedTools: [makeCodeTool(state)] }),
/** No persistBackgroundCodeResult: generated files could only anchor
* via a later poll (or never) — safer to run the call foreground. */
});
const configurable = buildConfig(['execute_code']);
const metadata = { thread_id: 'exec_convo_code_fg', run_id: 'msg-fg' };
const results = (await runBatch(handler, {
toolCalls: [codeCall({ id: 'call_code_fg' })],
agentId: 'a',
configurable,
metadata,
})) as Array<{ content: string; artifact?: unknown }>;
expect(state.calls).toBe(1);
expect(results[0].content).not.toContain('background_task_id');
expect(results[0].content).toContain('hello');
expect(results[0].artifact).toEqual(CODE_ARTIFACT);
/** The injected flag never reaches the real tool. */
expect(state.lastInput).toEqual({ lang: 'py', code: 'print(1)' });
});
});