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 { logger } from '@librechat/data-schemas';
import { InMemorySubagentTaskStore } from '@librechat/agents';
import type {
LCTool,
LCToolRegistry,
SubagentTaskClaim,
SubagentTaskConfig,
SubagentTaskRuntime,
SubagentUpdateEvent,
SubagentTaskSnapshot,
} from '@librechat/agents';
import type { HostSubagentTaskConfig } from './subagentDelivery';
import type { ActivitySnapshot } from './digest';
import {
isBackgroundEligibleToolName,
isBackgroundRequested,
stripRunInBackgroundArg,
injectRunInBackgroundParam,
stripBackgroundFromToolDefinitions,
stripBackgroundFromToolRegistry,
applyBackgroundToolCalls,
synthesizeBackgroundToolOptions,
registerBackgroundTaskTool,
buildBackgroundCapacityContent,
buildBackgroundHandleContent,
runCheckBackgroundTask,
getBackgroundCodeDelivery,
backgroundTaskRegistry,
BackgroundTaskRegistryClass,
CHECK_BACKGROUND_TASK_NAME,
RUN_IN_BACKGROUND_ARG,
} from './background';
import {
SUBAGENT_POLL_GUIDANCE,
SUBAGENT_WAKEUP_GUIDANCE,
SUBAGENT_COMPLETION_DELIVERY,
SUBAGENT_POLL_WAKEUP_GUIDANCE,
} from './subagentDelivery';
import { parseBackgroundTaskOutput } from '../../../chat/src/core/parts/background';
import { parseBackgroundHandle } from '../../../chat/src/core/parts/handle';
import { SubagentTaskOwnerUnavailableError } from './subagentTaskRouting';
import { TOOL_SELECTION_WILDCARD } from './selection';
import { toolOptionsSchema } from './validation';
import { ActivityRecorder } from './digest';
const mcpDef = (name: string): LCTool =>
({
name,
description: `${name} description`,
parameters: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
}) as unknown as LCTool;
async function waitForSubagentTaskToSettle(
store: InMemorySubagentTaskStore,
scopeId: string,
taskId: string,
): Promise<void> {
for (let attempt = 0; attempt < 100; attempt += 1) {
if (store.get(scopeId, taskId)?.status !== 'running') {
return;
}
await new Promise<void>((resolve) => setTimeout(resolve, 1));
}
throw new Error('Timed out waiting for the detached subagent task.');
}
describe('manual reconciliation restoration', () => {
it('upgrades only the confirmed local owner and preserves the marker on replay', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'marker-user',
conversationId: 'marker-convo',
toolCallId: 'marker-call',
toolName: 'tool',
});
if ('atCapacity' in created) throw new Error('Unexpected capacity');
registry.complete('marker-user', 'marker-convo', created.task.id, { content: 'done' });
const claim = { kind: 'manual' as const, claimId: 'poll' };
expect(registry.claimResult('marker-user', 'marker-convo', created.task.id, claim)).toBe(
'acquired',
);
expect(
registry.claimResult('marker-user', 'marker-convo', created.task.id, {
...claim,
claimId: 'foreign',
receiptReconciled: true,
}),
).toBe('claimed');
expect(created.task.resultClaim?.receiptReconciled).toBeUndefined();
expect(
registry.claimResult('marker-user', 'marker-convo', created.task.id, {
...claim,
receiptReconciled: true,
}),
).toBe('replay');
expect(registry.claimResult('marker-user', 'marker-convo', created.task.id, claim)).toBe(
'replay',
);
expect(created.task.resultClaim?.receiptReconciled).toBe(true);
});
});
describe('isBackgroundEligibleToolName', () => {
it('excludes direct-path, host-special, and machinery tools', () => {
for (const name of [
'read_file',
'skill',
'tool_search',
'run_tools_with_code',
'run_tools_with_bash',
'subagent',
'create_file',
'edit_file',
'set_memory',
'delete_memory',
'ask_user_question',
'web_search',
'file_search',
'dalle',
'dall-e',
'stable-diffusion',
'flux',
'gemini_image_gen',
'image_gen_oai',
'image_edit_oai',
CHECK_BACKGROUND_TASK_NAME,
'lc_transfer_to_researcher',
]) {
expect(isBackgroundEligibleToolName(name)).toBe(false);
}
});
it('allows MCP and other event-driven tools', () => {
for (const name of ['search_mcp_docs', 'lookup_customer', 'fetch_weather']) {
expect(isBackgroundEligibleToolName(name)).toBe(true);
}
});
it('allows the code-execution pair (natively backgroundable)', () => {
expect(isBackgroundEligibleToolName('execute_code')).toBe(true);
expect(isBackgroundEligibleToolName('bash_tool')).toBe(true);
});
});
describe('isBackgroundRequested / stripRunInBackgroundArg', () => {
it('detects the flag only when explicitly true on an object', () => {
expect(isBackgroundRequested({ [RUN_IN_BACKGROUND_ARG]: true })).toBe(true);
expect(isBackgroundRequested({ [RUN_IN_BACKGROUND_ARG]: false })).toBe(false);
expect(isBackgroundRequested({})).toBe(false);
expect(isBackgroundRequested('run_in_background')).toBe(false);
expect(isBackgroundRequested(undefined)).toBe(false);
expect(isBackgroundRequested(null)).toBe(false);
});
it('strips the flag without mutating the original', () => {
const args = { q: 'hi', [RUN_IN_BACKGROUND_ARG]: true };
const stripped = stripRunInBackgroundArg(args) as Record<string, unknown>;
expect(stripped).toEqual({ q: 'hi' });
expect(RUN_IN_BACKGROUND_ARG in args).toBe(true);
});
it('returns non-object / flagless args unchanged', () => {
expect(stripRunInBackgroundArg('str')).toBe('str');
const noFlag = { q: 'hi' };
expect(stripRunInBackgroundArg(noFlag)).toBe(noFlag);
});
it('handles stringified JSON args', () => {
expect(isBackgroundRequested('{"run_in_background":true,"q":"x"}')).toBe(true);
expect(isBackgroundRequested('{"q":"x"}')).toBe(false);
expect(isBackgroundRequested('not json')).toBe(false);
expect(stripRunInBackgroundArg('{"run_in_background":true,"q":"x"}')).toEqual({ q: 'x' });
// flag absent -> string returned unchanged (no shape rewrite)
expect(stripRunInBackgroundArg('{"q":"x"}')).toBe('{"q":"x"}');
});
});
describe('injectRunInBackgroundParam', () => {
it('preserves required command fields across injection and inherited-definition cleanup', () => {
const definition = {
name: 'bash_tool',
description: 'Starts a command',
parameters: {
type: 'object',
properties: { command: { type: 'string' } },
required: ['command'],
},
} as LCTool;
const injected = injectRunInBackgroundParam(definition);
expect(injected.parameters?.required).toEqual(['command']);
expect(injected.name).toBe('bash_tool');
const [restored] = stripBackgroundFromToolDefinitions([injected], ['bash_tool']);
expect(restored.parameters?.required).toEqual(['command']);
expect(restored.parameters?.properties).toEqual(definition.parameters?.properties);
});
it('adds a run_in_background boolean without mutating a frozen def', () => {
const def = Object.freeze(mcpDef('search_mcp_docs'));
const injected = injectRunInBackgroundParam(def);
const props = (injected.parameters as { properties: Record<string, { type: string }> })
.properties;
expect(props[RUN_IN_BACKGROUND_ARG]).toEqual(expect.objectContaining({ type: 'boolean' }));
expect(props.q).toEqual({ type: 'string' });
// original untouched
expect(RUN_IN_BACKGROUND_ARG in (def.parameters as { properties: object }).properties).toBe(
false,
);
});
it('creates an object schema when the tool declares no parameters', () => {
const def = { name: 'no_params' } as unknown as LCTool;
const injected = injectRunInBackgroundParam(def);
const params = injected.parameters as { type: string; properties: Record<string, unknown> };
expect(params.type).toBe('object');
expect(params.properties[RUN_IN_BACKGROUND_ARG]).toBeDefined();
});
it('is a no-op when the param already exists', () => {
const def = mcpDef('search_mcp_docs');
const once = injectRunInBackgroundParam(def);
const twice = injectRunInBackgroundParam(once);
expect(twice).toBe(once);
});
});
describe('applyBackgroundToolCalls', () => {
it('is a no-op when no tool opted in (returns the same defs, registers nothing)', () => {
const defs = [mcpDef('search_mcp_docs')];
const registry: LCToolRegistry = new Map();
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: { search_mcp_docs: { defer_loading: true } },
});
expect(result.toolDefinitions).toBe(defs);
expect(result.backgroundToolNames).toEqual([]);
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(false);
});
it('injects only opted-in eligible tools and registers the poll tool', () => {
const defs = [mcpDef('search_mcp_docs'), mcpDef('lookup_customer')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: { search_mcp_docs: { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual(['search_mcp_docs']);
const searchDef = result.toolDefinitions.find((d) => d.name === 'search_mcp_docs');
const lookupDef = result.toolDefinitions.find((d) => d.name === 'lookup_customer');
expect(
(searchDef?.parameters as { properties: Record<string, unknown> }).properties[
RUN_IN_BACKGROUND_ARG
],
).toBeDefined();
expect(
(lookupDef?.parameters as { properties: Record<string, unknown> }).properties[
RUN_IN_BACKGROUND_ARG
],
).toBeUndefined();
expect(result.toolDefinitions.some((d) => d.name === CHECK_BACKGROUND_TASK_NAME)).toBe(true);
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
// registry entry for the opted-in tool also carries the injected param
expect(
(registry.get('search_mcp_docs')?.parameters as { properties: Record<string, unknown> })
.properties[RUN_IN_BACKGROUND_ARG],
).toBeDefined();
});
it('does not inject or register when an opted-in tool is excluded', () => {
const defs = [mcpDef('read_file')];
const registry: LCToolRegistry = new Map();
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: { read_file: { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual([]);
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(false);
});
it('skips a tool the host excludeTool predicate rejects (e.g. ephemeral MCP server)', () => {
const defs = [mcpDef('ephemeral_mcp__body_server'), mcpDef('search_mcp_docs')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: {
ephemeral_mcp__body_server: { run_in_background: true },
search_mcp_docs: { run_in_background: true },
},
excludeTool: (name) => name === 'ephemeral_mcp__body_server',
});
expect(result.backgroundToolNames).toEqual(['search_mcp_docs']);
const ephemeralDef = result.toolDefinitions.find(
(d) => d.name === 'ephemeral_mcp__body_server',
);
expect(
(ephemeralDef?.parameters as { properties?: Record<string, unknown> }).properties?.[
RUN_IN_BACKGROUND_ARG
],
).toBeUndefined();
});
it('resolves an action opt-in stored with the raw `---` domain against the collapsed def name', () => {
/** Agents persist `swapi---tech`; the runtime def is named `swapi_tech`. */
const defs = [mcpDef('getPerson_action_swapi_tech')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: { 'getPerson_action_swapi---tech': { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual(['getPerson_action_swapi_tech']);
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
});
it('merges a raw action opt-in into an existing normalized option entry', () => {
const defs = [mcpDef('getPerson_action_swapi_tech')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: {
'getPerson_action_swapi---tech': { run_in_background: true },
getPerson_action_swapi_tech: { defer_loading: true },
},
});
expect(result.backgroundToolNames).toEqual(['getPerson_action_swapi_tech']);
});
it('keeps an explicit normalized action background option authoritative', () => {
const defs = [mcpDef('getPerson_action_swapi_tech')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: {
'getPerson_action_swapi---tech': { run_in_background: true },
getPerson_action_swapi_tech: { run_in_background: false },
},
});
expect(result.backgroundToolNames).toEqual([]);
});
it('does not collapse hyphens in the operationId when normalizing an action key', () => {
const defs = [
mcpDef('get_foo---bar_action_swapi_tech'),
mcpDef('get_foo_bar_action_swapi_tech'),
];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: { 'get_foo---bar_action_swapi---tech': { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual(['get_foo---bar_action_swapi_tech']);
});
it('injects an opted-in action tool but not one the OAuth excludeTool rejects', () => {
const oauthActionNames = new Set(['sendMail_action_mail---example---com']);
const defs = [
mcpDef('getWeather_action_weather---com'),
mcpDef('sendMail_action_mail---example---com'),
];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: {
'getWeather_action_weather---com': { run_in_background: true },
'sendMail_action_mail---example---com': { run_in_background: true },
},
excludeTool: (name) => oauthActionNames.has(name),
});
expect(result.backgroundToolNames).toEqual(['getWeather_action_weather---com']);
const oauthDef = result.toolDefinitions.find(
(d) => d.name === 'sendMail_action_mail---example---com',
);
expect(
(oauthDef?.parameters as { properties?: Record<string, unknown> }).properties?.[
RUN_IN_BACKGROUND_ARG
],
).toBeUndefined();
});
it('skips a non-object (string-input) schema without rewriting it', () => {
const defs = [{ name: 'legacy_tool', parameters: { type: 'string' } } as unknown as LCTool];
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: new Map(),
toolOptions: { legacy_tool: { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual([]);
expect((result.toolDefinitions[0].parameters as { type: string }).type).toBe('string');
});
it('skips a tool that already declares its own run_in_background param', () => {
const defs = [
{
name: 'owns_it',
parameters: { type: 'object', properties: { run_in_background: { type: 'boolean' } } },
} as unknown as LCTool,
];
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: new Map(),
toolOptions: { owns_it: { run_in_background: true } },
});
expect(result.backgroundToolNames).toEqual([]);
});
});
describe('stripBackgroundFromToolDefinitions', () => {
it('removes the poll tool and the injected param (self-spawn sanitization)', () => {
const injected = injectRunInBackgroundParam(mcpDef('search_mcp_docs'));
const withPoll = registerBackgroundTaskTool({
toolRegistry: new Map(),
toolDefinitions: [injected],
}).toolDefinitions;
const stripped = stripBackgroundFromToolDefinitions(withPoll, ['search_mcp_docs']);
expect(stripped.some((d) => d.name === CHECK_BACKGROUND_TASK_NAME)).toBe(false);
const search = stripped.find((d) => d.name === 'search_mcp_docs');
expect(
(search?.parameters as { properties: Record<string, unknown> }).properties[
RUN_IN_BACKGROUND_ARG
],
).toBeUndefined();
});
});
describe('registerBackgroundTaskTool', () => {
it('adds the poll tool once (idempotent)', () => {
const registry: LCToolRegistry = new Map();
const first = registerBackgroundTaskTool({ toolRegistry: registry, toolDefinitions: [] });
expect(first.toolDefinitions).toHaveLength(1);
const second = registerBackgroundTaskTool({
toolRegistry: registry,
toolDefinitions: first.toolDefinitions,
});
expect(second.toolDefinitions).toHaveLength(1);
});
it('reserves the name: shadows a colliding non-poll tool with the host poll schema', () => {
const collidingDef = {
name: CHECK_BACKGROUND_TASK_NAME,
description: 'a user MCP tool that happens to share the name',
parameters: { type: 'object', properties: {} },
} as unknown as LCTool;
const registry: LCToolRegistry = new Map([[CHECK_BACKGROUND_TASK_NAME, { ...collidingDef }]]);
const result = registerBackgroundTaskTool({
toolRegistry: registry,
toolDefinitions: [collidingDef],
});
const matching = result.toolDefinitions.filter((d) => d.name === CHECK_BACKGROUND_TASK_NAME);
expect(matching).toHaveLength(1);
// the surviving def/registry entry is the host poll tool, not the user's
expect(matching[0].description).not.toBe(collidingDef.description);
expect(registry.get(CHECK_BACKGROUND_TASK_NAME)?.description).not.toBe(
collidingDef.description,
);
});
it('advertises automatic delivery for wakeup-enabled background work', () => {
const registry: LCToolRegistry = new Map();
const manual = registerBackgroundTaskTool({ toolRegistry: registry, toolDefinitions: [] });
const manualDescription = manual.toolDefinitions[0].description ?? '';
expect(manualDescription).toContain('Results are not pushed to you');
const automatic = registerBackgroundTaskTool({
toolRegistry: registry,
toolDefinitions: manual.toolDefinitions,
subagentCompletionWakeups: true,
});
expect(automatic.toolDefinitions).toHaveLength(1);
expect(automatic.toolDefinitions[0].description).toContain(
'Background tools and detached subagents use automatic completion delivery',
);
expect(automatic.toolDefinitions[0].description).toContain(
'Ordinary tool execution remains process-local',
);
expect(automatic.toolDefinitions[0].description).toContain(
'A task is outstanding until its result is delivered',
);
expect(automatic.toolDefinitions[0].description).toContain(
'Polling or cancelling a finished task retires its pending delivery',
);
for (const description of [manualDescription, automatic.toolDefinitions[0].description ?? '']) {
expect(description).toContain('Pass since: activity.cursor');
expect(description).toContain('expand:');
/** OpenAI-compatible validators reject longer tool descriptions. */
expect(description.length).toBeLessThan(1024);
}
});
});
describe('synthesizeBackgroundToolOptions', () => {
it('returns undefined when neither the ephemeral toggle nor the model spec carries a policy', () => {
expect(synthesizeBackgroundToolOptions({})).toBeUndefined();
/** The ephemeral toggle is a badge default, not a decision — its `false`
* stays no-policy so the background-native code pair keeps its default. */
expect(
synthesizeBackgroundToolOptions({
ephemeralAgent: { run_in_background: false },
}),
).toBeUndefined();
});
it('records a spec runInBackground: false as an explicit "none", like the empty list', () => {
/** Pre-native, `false` and absent were behaviorally identical (off); a
* config that wrote `false` must not silently flip to backgrounding code. */
expect(synthesizeBackgroundToolOptions({ modelSpec: { runInBackground: false } })).toEqual({
[TOOL_SELECTION_WILDCARD]: { run_in_background: false },
});
});
it('records boolean/ephemeral modes as a wildcard opt-in (no name enumeration)', () => {
const expected = { [TOOL_SELECTION_WILDCARD]: { run_in_background: true } };
expect(synthesizeBackgroundToolOptions({ modelSpec: { runInBackground: true } })).toEqual(
expected,
);
expect(
synthesizeBackgroundToolOptions({ ephemeralAgent: { run_in_background: true } }),
).toEqual(expected);
});
it('records a list as a wildcard opt-out plus verbatim opt-ins', () => {
expect(
synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['slow_report_mcp_analytics', 'execute_code'] },
}),
).toEqual({
[TOOL_SELECTION_WILDCARD]: { run_in_background: false },
slow_report_mcp_analytics: { run_in_background: true },
execute_code: { run_in_background: true },
});
});
it('treats an empty list as enabling nothing', () => {
expect(synthesizeBackgroundToolOptions({ modelSpec: { runInBackground: [] } })).toEqual({
[TOOL_SELECTION_WILDCARD]: { run_in_background: false },
});
});
it('drops and warns about a literal wildcard in the list (reserved)', () => {
/** `runInBackground: ['*']` would otherwise overwrite the opt-out default
* and detach-enable every eligible tool instead of selecting one. */
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
expect(
synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: [TOOL_SELECTION_WILDCARD, 'search_mcp_docs'] },
}),
).toEqual({
[TOOL_SELECTION_WILDCARD]: { run_in_background: false },
search_mcp_docs: { run_in_background: true },
});
expect(warn).toHaveBeenCalledWith(expect.stringContaining('reserved'));
warn.mockRestore();
});
it('the ephemeral toggle stays global even when the spec narrows', () => {
expect(
synthesizeBackgroundToolOptions({
ephemeralAgent: { run_in_background: true },
modelSpec: { runInBackground: ['search_mcp_docs'] },
}),
).toEqual({ [TOOL_SELECTION_WILDCARD]: { run_in_background: true } });
});
});
describe('selection policy at injection time', () => {
it('a wildcard opt-in reaches eligible definitions and skips excluded built-ins', () => {
const toolOptions = synthesizeBackgroundToolOptions({ modelSpec: { runInBackground: true } });
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [
mcpDef('search_mcp_overlay_server'),
mcpDef('web_search'),
mcpDef('ask_user_question'),
],
toolRegistry: undefined,
toolOptions,
});
expect(backgroundToolNames).toEqual(['search_mcp_overlay_server']);
});
it('keeps host-side workspace search in the foreground', () => {
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('search_workspace')],
toolRegistry: undefined,
toolOptions: { search_workspace: { run_in_background: true } },
});
expect(backgroundToolNames).toEqual([]);
});
it('keeps host-side workspace file listing in the foreground', () => {
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('list_workspace_files')],
toolRegistry: undefined,
toolOptions: { list_workspace_files: { run_in_background: true } },
});
expect(backgroundToolNames).toEqual([]);
});
it('rejects and diagnoses a marker whose runtime definitions are all excluded', () => {
/** `runInBackground: ['memory']` used to record a successful-looking
* option under the marker while set_memory/delete_memory — the
* definitions it expands into — are background-excluded; nothing
* consumed the entry and nothing warned. */
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
const toolOptions = synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['memory'] },
});
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('set_memory'), mcpDef('delete_memory')],
toolRegistry: undefined,
toolOptions,
capabilityToolNames: new Map([['memory', ['set_memory', 'delete_memory']]]),
});
expect(backgroundToolNames).toEqual([]);
expect(warn).toHaveBeenCalledWith(expect.stringContaining('memory'));
warn.mockRestore();
});
it('projects a saved-agent execute_code entry onto the bash_tool definition', () => {
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('bash_tool')],
toolRegistry: undefined,
toolOptions: { execute_code: { run_in_background: true } },
capabilityToolNames: new Map([['execute_code', ['read_file', 'bash_tool']]]),
});
expect(backgroundToolNames).toEqual(['bash_tool']);
});
it('backgrounds the code pair natively, with no tool_options at all', () => {
const defs = [mcpDef('bash_tool'), mcpDef('search_mcp_docs')];
const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
const result = applyBackgroundToolCalls({
toolDefinitions: defs,
toolRegistry: registry,
toolOptions: undefined,
});
expect(result.backgroundToolNames).toEqual(['bash_tool']);
const bashDef = result.toolDefinitions.find((d) => d.name === 'bash_tool');
expect(
(bashDef?.parameters as { properties: Record<string, unknown> }).properties[
RUN_IN_BACKGROUND_ARG
],
).toBeDefined();
const searchDef = result.toolDefinitions.find((d) => d.name === 'search_mcp_docs');
expect(
(searchDef?.parameters as { properties: Record<string, unknown> }).properties[
RUN_IN_BACKGROUND_ARG
],
).toBeUndefined();
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
});
it('an explicit false opts the native pair out — by definition name or by marker projection', () => {
const byName = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('bash_tool')],
toolRegistry: new Map(),
toolOptions: { bash_tool: { run_in_background: false } },
});
expect(byName.backgroundToolNames).toEqual([]);
const registry: LCToolRegistry = new Map();
const byMarker = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('bash_tool')],
toolRegistry: registry,
toolOptions: { execute_code: { run_in_background: false } },
capabilityToolNames: new Map([['execute_code', ['read_file', 'bash_tool']]]),
});
expect(byMarker.backgroundToolNames).toEqual([]);
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(false);
});
it('a narrowing selection that omits the code pair opts it out via the wildcard', () => {
const options = synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['slow_report_mcp_analytics'] },
});
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('bash_tool'), mcpDef('slow_report_mcp_analytics')],
toolRegistry: undefined,
toolOptions: options,
});
expect(backgroundToolNames).toEqual(['slow_report_mcp_analytics']);
});
it('a selection can name the code pair by its runtime name (bash_tool)', () => {
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
const options = synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['bash_tool'] },
});
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('bash_tool'), mcpDef('search_mcp_docs')],
toolRegistry: undefined,
toolOptions: options,
capabilityToolNames: new Map([['execute_code', ['read_file', 'bash_tool']]]),
});
expect(backgroundToolNames).toEqual(['bash_tool']);
expect(warn).not.toHaveBeenCalled();
warn.mockRestore();
});
it('still enforces eligibility for explicitly named tools, and diagnoses them', () => {
/** Backgrounding these would silently drop attachments/citations or break
* artifact continuity, so a list must not be able to force them on. */
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
const toolOptions = synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['search_mcp_docs', 'web_search', 'ask_user_question'] },
});
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [
mcpDef('search_mcp_docs'),
mcpDef('web_search'),
mcpDef('ask_user_question'),
],
toolRegistry: undefined,
toolOptions,
});
expect(backgroundToolNames).toEqual(['search_mcp_docs']);
expect(warn).toHaveBeenCalledWith(expect.stringContaining('web_search'));
warn.mockRestore();
});
it('warns about selection names the spec does not equip, rather than silently skipping', () => {
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
const toolOptions = synthesizeBackgroundToolOptions({
modelSpec: { runInBackground: ['search_mcp_docs', 'typo_tool_name'] },
});
const { backgroundToolNames } = applyBackgroundToolCalls({
toolDefinitions: [mcpDef('search_mcp_docs')],
toolRegistry: undefined,
toolOptions,
});
expect(backgroundToolNames).toEqual(['search_mcp_docs']);
expect(warn).toHaveBeenCalledWith(expect.stringContaining('typo_tool_name'));
warn.mockRestore();
});
it('does not warn about saved-agent options with no narrowing policy', () => {
const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
applyBackgroundToolCalls({
toolDefinitions: [mcpDef('search_mcp_docs')],
toolRegistry: undefined,
toolOptions: { stale_tool: { run_in_background: true } },
});
expect(warn).not.toHaveBeenCalled();
warn.mockRestore();
});
});
describe('BackgroundTaskRegistryClass', () => {
it('requests cancellation idempotently without settling or releasing running capacity', () => {
const registry = new BackgroundTaskRegistryClass();
const requestCancellation = jest.fn();
const created = registry.create({
userId: 'cancel-owner',
conversationId: 'cancel-conversation',
toolCallId: 'cancel-call',
toolName: 'bash_tool',
requestCancellation,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
expect(
registry.requestCancellation('other-owner', 'cancel-conversation', created.task.id),
).toEqual({ status: 'not_found' });
expect(
registry.requestCancellation('cancel-owner', 'other-conversation', created.task.id),
).toEqual({ status: 'not_found' });
expect(
registry.requestCancellation('cancel-owner', 'cancel-conversation', created.task.id).status,
).toBe('requested');
expect(
registry.requestCancellation('cancel-owner', 'cancel-conversation', created.task.id).status,
).toBe('already_requested');
expect(requestCancellation).toHaveBeenCalledTimes(1);
expect(created.task).toMatchObject({
status: 'running',
cancellationRequestedAt: expect.any(Number),
});
for (let index = 0; index < 9; index += 1) {
const admitted = registry.create({
userId: 'cancel-owner',
conversationId: 'cancel-conversation',
toolCallId: `other-call-${index}`,
toolName: 'background-tool',
});
expect('atCapacity' in admitted).toBe(false);
}
expect(
registry.create({
userId: 'cancel-owner',
conversationId: 'cancel-conversation',
toolCallId: 'blocked-until-settlement',
toolName: 'background-tool',
}),
).toEqual({ atCapacity: true, scope: 'conversation_running' });
registry.cancel(
'cancel-owner',
'cancel-conversation',
created.task.id,
'Background task cancellation requested',
);
expect(created.task.status).toBe('cancelled');
expect(
registry.create({
userId: 'cancel-owner',
conversationId: 'cancel-conversation',
toolCallId: 'admitted-after-settlement',
toolName: 'background-tool',
}),
).toMatchObject({ isNew: true });
expect(
registry.requestCancellation('cancel-owner', 'cancel-conversation', created.task.id).status,
).toBe('settled');
});
it('lets actual completion win when an abort-resistant invocation settles successfully', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'race-owner',
conversationId: 'race-conversation',
toolCallId: 'race-call',
toolName: 'mutation',
requestCancellation: jest.fn(),
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.requestCancellation('race-owner', 'race-conversation', created.task.id);
registry.complete('race-owner', 'race-conversation', created.task.id, {
content: 'completed despite cancellation request',
});
registry.cancel('race-owner', 'race-conversation', created.task.id, 'cancelled too late');
expect(created.task).toMatchObject({
status: 'completed',
result: 'completed despite cancellation request',
});
});
it('does not record a manual cancellation when another abort source already won', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'timeout-owner',
conversationId: 'timeout-conversation',
toolCallId: 'timeout-call',
toolName: 'mutation',
requestCancellation: () => false,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
expect(
registry.requestCancellation('timeout-owner', 'timeout-conversation', created.task.id),
).toMatchObject({ status: 'unavailable' });
expect(created.task.cancellationRequestedAt).toBeUndefined();
});
it('creates, completes, and reads a task', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_1',
toolName: 'search_mcp_docs',
});
expect('atCapacity' in created).toBe(false);
if ('atCapacity' in created) {
return;
}
expect(created.isNew).toBe(true);
expect(created.task.status).toBe('running');
registry.complete('u1', 'c1', created.task.id, { content: 'DONE' });
const task = registry.get('u1', 'c1', created.task.id);
expect(task?.status).toBe('completed');
expect(task?.result).toBe('DONE');
});
it('stamps strictly-increasing createdAt even for same-millisecond dispatches', () => {
/* `createdAt` orders writers in the stale-output guard, which accepts
* equal stamps for idempotent re-commits — a wall-clock tie between two
* DIFFERENT dispatches would let the older one overwrite the newer. */
const registry = new BackgroundTaskRegistryClass();
const frozenNow = Date.now();
const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(frozenNow);
try {
const first = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_a',
toolName: 'execute_code',
});
const second = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_b',
toolName: 'execute_code',
});
if ('atCapacity' in first || 'atCapacity' in second) {
throw new Error('unexpected capacity');
}
expect(second.task.createdAt).toBeGreaterThan(first.task.createdAt);
} finally {
nowSpy.mockRestore();
}
});
it('is idempotent within the same run (never double-dispatches on replay)', () => {
const registry = new BackgroundTaskRegistryClass();
const first = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_dup',
toolName: 'search_mcp_docs',
runId: 'run-A',
});
const second = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_dup',
toolName: 'search_mcp_docs',
runId: 'run-A',
});
if ('atCapacity' in first || 'atCapacity' in second) {
throw new Error('unexpected capacity');
}
expect(second.isNew).toBe(false);
expect(second.task.id).toBe(first.task.id);
});
it('does NOT collide when the same provider toolCallId repeats in a later run/turn', () => {
const registry = new BackgroundTaskRegistryClass();
const turn1 = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_0',
toolName: 'search_mcp_docs',
runId: 'run-turn-1',
});
const turn2 = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_0',
toolName: 'search_mcp_docs',
runId: 'run-turn-2',
});
if ('atCapacity' in turn1 || 'atCapacity' in turn2) {
throw new Error('unexpected capacity');
}
expect(turn2.isNew).toBe(true);
expect(turn2.task.id).not.toBe(turn1.task.id);
});
it('does NOT collide when two agents in the same run emit the same toolCallId', () => {
const registry = new BackgroundTaskRegistryClass();
const agentA = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_0',
toolName: 'search_mcp_docs',
runId: 'run-1',
agentId: 'agent-A',
});
const agentB = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_0',
toolName: 'search_mcp_docs',
runId: 'run-1',
agentId: 'agent-B',
});
if ('atCapacity' in agentA || 'atCapacity' in agentB) {
throw new Error('unexpected capacity');
}
expect(agentB.isNew).toBe(true);
expect(agentB.task.id).not.toBe(agentA.task.id);
});
it('records failures', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_err',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.fail('u1', 'c1', created.task.id, 'boom');
expect(registry.get('u1', 'c1', created.task.id)?.status).toBe('error');
expect(registry.get('u1', 'c1', created.task.id)?.error).toBe('boom');
});
it('holds a completed artifact and claims it exactly once', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_art',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u1', 'c1', created.task.id, {
content: 'DONE',
artifact: { files: ['a.png'] },
});
expect(registry.get('u1', 'c1', created.task.id)?.artifact).toEqual({ files: ['a.png'] });
const claimed = registry.claimArtifact('u1', 'c1', created.task.id);
expect(claimed).toEqual({
toolName: 'search_mcp_docs',
toolCallId: 'call_art',
artifact: { files: ['a.png'] },
content: 'DONE',
});
// second claim yields nothing (delivered once), and the artifact is freed
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
expect(registry.get('u1', 'c1', created.task.id)?.artifact).toBeUndefined();
});
it('keeps harvest state (messageId, attachments) independent of the one-shot artifact claim', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_code',
toolName: 'execute_code',
messageId: 'dispatch-msg',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u1', 'c1', created.task.id, {
content: 'stdout',
artifact: { session_id: 'exec-1', files: [{ id: 'f1' }] },
harvestStarted: true,
});
registry.finishHarvest('u1', 'c1', created.task.id);
const claimed = registry.claimArtifact('u1', 'c1', created.task.id);
expect(claimed).toEqual({
toolName: 'execute_code',
toolCallId: 'call_code',
messageId: 'dispatch-msg',
harvestStarted: true,
artifact: { session_id: 'exec-1', files: [{ id: 'f1' }] },
content: 'stdout',
});
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
/** Attachments can land AFTER the artifact was claimed (harvest is
* detached) and stay retrievable on every later poll. */
const attachments = [{ file_id: 'f1', toolCallId: 'call_code' }];
registry.attachHarvest('u1', 'c1', created.task.id, attachments);
expect(registry.get('u1', 'c1', created.task.id)?.attachments).toEqual(attachments);
});
it('releases claimed artifact capacity before detached harvest attachments arrive', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u-artifact-budget',
conversationId: 'c-artifact-budget',
toolCallId: 'call_code_budget',
toolName: 'execute_code',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u-artifact-budget', 'c-artifact-budget', created.task.id, {
content: 'stdout',
artifact: { payload: 'a'.repeat(9_000_000) },
});
expect(
registry.claimArtifact('u-artifact-budget', 'c-artifact-budget', created.task.id),
).toBeDefined();
const attachments = [{ payload: 'b'.repeat(8_000_000) }];
registry.attachHarvest('u-artifact-budget', 'c-artifact-budget', created.task.id, attachments);
expect(
registry.get('u-artifact-budget', 'c-artifact-budget', created.task.id)?.attachments,
).toBe(attachments);
});
it('replaces retained attachments without double-counting their payload', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u-attachment-replace',
conversationId: 'c-attachment-replace',
toolCallId: 'call_attachment_replace',
toolName: 'execute_code',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u-attachment-replace', 'c-attachment-replace', created.task.id, {
content: 'stdout',
});
const first = [{ payload: 'a'.repeat(9_000_000) }];
const replacement = [{ payload: 'b'.repeat(9_000_000) }];
registry.attachHarvest('u-attachment-replace', 'c-attachment-replace', created.task.id, first);
registry.attachHarvest(
'u-attachment-replace',
'c-attachment-replace',
created.task.id,
replacement,
);
expect(
registry.get('u-attachment-replace', 'c-attachment-replace', created.task.id)?.attachments,
).toBe(replacement);
});
it('revokeHarvest hands a pending artifact to the fallback path', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_code',
toolName: 'execute_code',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const artifact = { session_id: 'exec-1', files: [{ id: 'f1' }] };
registry.complete('u1', 'c1', created.task.id, {
content: 'stdout',
artifact,
harvestStarted: true,
});
/** Pending inspection prevents poll delivery until the harvest settles. */
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
/** A transient harvest failure unlocks the artifact for the legacy
* fallback and clears the suppression flag. */
registry.revokeHarvest('u1', 'c1', created.task.id, artifact);
const task = registry.get('u1', 'c1', created.task.id);
expect(task?.harvestStarted).toBeUndefined();
expect(task?.artifact).toEqual(artifact);
expect(registry.claimArtifact('u1', 'c1', created.task.id)?.harvestStarted).toBeUndefined();
});
it('keeps a policy-blocked artifact terminal across later registry mutations', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_code_blocked',
toolName: 'execute_code',
harvestStarted: true,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const artifact = {
session_id: 'exec-blocked',
files: [{ id: 'f1', opaqueBytes: 'PROTECTED-REGISTRY-BYTES' }],
};
registry.complete('u1', 'c1', created.task.id, {
content: 'safe stdout',
artifact,
harvestStarted: true,
});
registry.blockArtifact(
'u1',
'c1',
created.task.id,
'Submitted content could not be completely inspected before processing.',
);
registry.restoreArtifact('u1', 'c1', created.task.id, artifact);
registry.revokeHarvest('u1', 'c1', created.task.id, artifact);
registry.finishHarvest('u1', 'c1', created.task.id, [{ opaqueBytes: artifact }]);
registry.attachHarvest('u1', 'c1', created.task.id, [{ opaqueBytes: artifact }]);
registry.complete('u1', 'c1', created.task.id, {
content: 'unsafe replacement',
artifact,
harvestStarted: true,
});
registry.fail('u1', 'c1', created.task.id, 'raw failure');
const task = registry.get('u1', 'c1', created.task.id);
expect(task).toEqual(
expect.objectContaining({
status: 'error',
error: 'Submitted content could not be completely inspected before processing.',
artifactBlocked: true,
}),
);
expect(task?.result).toBeUndefined();
expect(task?.artifact).toBeUndefined();
expect(task?.attachments).toBeUndefined();
expect(task?.harvestStarted).toBeUndefined();
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
expect(JSON.stringify(task)).not.toContain('PROTECTED-REGISTRY-BYTES');
expect(JSON.stringify(task)).not.toContain('raw failure');
});
it('does not account payloads from rejected late completion updates', () => {
const registry = new BackgroundTaskRegistryClass();
const blocked = registry.create({
userId: 'u-blocked-accounting',
conversationId: 'c-blocked',
toolCallId: 'call_blocked',
toolName: 'execute_code',
});
if ('atCapacity' in blocked) {
throw new Error('unexpected capacity');
}
registry.blockArtifact('u-blocked-accounting', 'c-blocked', blocked.task.id, 'blocked');
registry.complete('u-blocked-accounting', 'c-blocked', blocked.task.id, {
content: 'late',
artifact: { payload: 'a'.repeat(10_000_000 - 20) },
});
const next = registry.create({
userId: 'u-blocked-accounting',
conversationId: 'c-next',
toolCallId: 'call_next',
toolName: 'execute_code',
});
if ('atCapacity' in next) {
throw new Error('unexpected capacity');
}
registry.complete('u-blocked-accounting', 'c-next', next.task.id, {
content: 'next',
artifact: { payload: 'b'.repeat(8_000_000) },
});
expect(registry.get('u-blocked-accounting', 'c-blocked', blocked.task.id)?.error).toBe(
'blocked',
);
});
it('keeps abort-resistant tasks nonterminal instead of exposing false timeout evidence', () => {
jest.useFakeTimers();
try {
const created = backgroundTaskRegistry.create({
userId: 'reap_user',
conversationId: 'reap_convo',
toolCallId: 'call_reaped',
toolName: 'execute_code',
messageId: 'dispatch-msg',
harvestStarted: true,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
/** The invocation owner may have requested abort, but registry age alone
* cannot prove that an external side effect stopped. */
jest.advanceTimersByTime(31 * 60 * 1000);
const delivery = getBackgroundCodeDelivery({
userId: 'reap_user',
conversationId: 'reap_convo',
args: { background_task_id: created.task.id },
});
expect(delivery).toEqual(
expect.objectContaining({
status: 'running',
toolCallId: 'call_reaped',
messageId: 'dispatch-msg',
}),
);
} finally {
jest.useRealTimers();
}
});
it('fail() can mark a task harvested so failed code tasks join the heal path', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_code_err',
toolName: 'execute_code',
messageId: 'dispatch-msg',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.fail('u1', 'c1', created.task.id, 'Execution error:\n\nboom', {
harvestStarted: true,
});
const task = registry.get('u1', 'c1', created.task.id);
expect(task?.status).toBe('error');
expect(task?.harvestStarted).toBe(true);
});
it('truncates an oversized stored result with an explicit marker (not a silent cut)', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_big',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u1', 'c1', created.task.id, { content: 'x'.repeat(150_000) });
const stored = registry.get('u1', 'c1', created.task.id)?.result ?? '';
expect(stored.length).toBeLessThanOrEqual(100_000);
expect(stored).toContain('[truncated: 150000 chars exceeded 100000 limit]');
});
it('drops artifacts whose JSON serialization returns undefined', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u-unmeasurable',
conversationId: 'c-unmeasurable',
toolCallId: 'call_unmeasurable',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u-unmeasurable', 'c-unmeasurable', created.task.id, {
content: 'done',
artifact: { payload: 'x'.repeat(1_000_000), toJSON: () => undefined },
});
expect(registry.get('u-unmeasurable', 'c-unmeasurable', created.task.id)?.artifact).toBe(
undefined,
);
});
it('retains only an artifact JSON projection without hidden object state', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u-hidden-artifact',
conversationId: 'c-hidden-artifact',
toolCallId: 'call_hidden_artifact',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const artifact = { visible: 'safe' };
Object.defineProperty(artifact, 'hidden', {
value: 'x'.repeat(1_000_000),
enumerable: false,
});
registry.complete('u-hidden-artifact', 'c-hidden-artifact', created.task.id, {
content: 'done',
artifact,
});
const stored = registry.get(
'u-hidden-artifact',
'c-hidden-artifact',
created.task.id,
)?.artifact;
expect(stored).toEqual({ visible: 'safe' });
expect(stored).not.toBe(artifact);
});
it('restores a claimed artifact after a failed delivery so a later claim retries', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_art_retry',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u1', 'c1', created.task.id, {
content: 'DONE',
artifact: { files: ['a.png'] },
});
const claimed = registry.claimArtifact('u1', 'c1', created.task.id);
expect(claimed?.artifact).toEqual({ files: ['a.png'] });
// delivery failed: restore, then a fresh claim gets the same artifact once
registry.restoreArtifact('u1', 'c1', created.task.id, claimed?.artifact);
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toEqual({
toolName: 'search_mcp_docs',
toolCallId: 'call_art_retry',
artifact: { files: ['a.png'] },
content: 'DONE',
});
expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
});
it('does not reap an abort-resistant running task by wall clock alone', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_stuck',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
// Backdate past the abort deadline; only invocation settlement is terminal proof.
created.task.createdAt = Date.now() - 31 * 60 * 1000;
registry.list('u1', 'c1');
expect(created.task.status).toBe('running');
expect(created.task.error).toBeUndefined();
});
it('sweeps an expired completed task on direct get() (no indefinite retention)', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_old',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u1', 'c1', created.task.id, { content: 'X' });
// backdate completion past the 1-hour completed TTL
created.task.updatedAt = Date.now() - 61 * 60 * 1000;
expect(registry.get('u1', 'c1', created.task.id)).toBeUndefined();
});
it.each(['completed', 'error', 'cancelled', 'blocked'] as const)(
'preserves pending %s results through both TTLs and releases protection afterward',
async (status) => {
jest.useFakeTimers();
try {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u',
conversationId: 'c',
toolCallId: 'call',
toolName: 'execute_code',
harvestStarted: true,
});
if ('atCapacity' in created) throw new Error('Unexpected capacity rejection');
if (status === 'cancelled') registry.cancel('u', 'c', created.task.id, 'cancelled');
else if (status === 'error') registry.fail('u', 'c', created.task.id, 'failed');
else
registry.complete('u', 'c', created.task.id, { content: 'result', harvestStarted: true });
registry.markCompletionPersistencePending('u', 'c', created.task.id);
registry.finishHarvest('u', 'c', created.task.id, [{ file_id: 'file' }]);
if (status === 'blocked') registry.blockArtifact('u', 'c', created.task.id, 'blocked');
registry.claimResult('u', 'c', created.task.id, { kind: 'manual', claimId: 'poll' });
await jest.advanceTimersByTimeAsync(7 * 60 * 60_000);
expect(registry.get('u', 'c', created.task.id)).toMatchObject({
completionPersistencePending: true,
});
registry.markCompletionPersistenceFinished('u', 'c', created.task.id);
expect(
registry.get('u', 'c', created.task.id)?.completionPersistencePending,
).toBeUndefined();
if (status === 'blocked')
expect(registry.get('u', 'c', created.task.id)).toMatchObject({
artifactBlocked: true,
artifact: undefined,
});
if (status === 'completed')
expect(registry.get('u', 'c', created.task.id)).toMatchObject({
result: 'result',
resultClaim: { kind: 'manual', claimId: 'poll' },
});
await jest.advanceTimersByTimeAsync(61 * 60_000);
expect(registry.get('u', 'c', created.task.id)).toBeUndefined();
} finally {
jest.useRealTimers();
}
},
);
it('caps concurrent running tasks per conversation', () => {
const registry = new BackgroundTaskRegistryClass();
let atCapacity = false;
for (let i = 0; i < 25; i++) {
const created = registry.create({
userId: 'u1',
conversationId: 'c-cap',
toolCallId: `call_${i}`,
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
atCapacity = true;
break;
}
}
expect(atCapacity).toBe(true);
});
it('caps concurrent running tasks per user across conversations', () => {
const registry = new BackgroundTaskRegistryClass();
for (let i = 0; i < 40; i++) {
const created = registry.create({
userId: 'u-cap',
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 'search_mcp_docs',
});
expect('atCapacity' in created).toBe(false);
}
expect(
registry.create({
userId: 'u-cap',
conversationId: 'c-rejected',
toolCallId: 'call_rejected',
toolName: 'search_mcp_docs',
}),
).toEqual({ atCapacity: true, scope: 'user_running' });
});
it('describes aggregate capacity rejections without blaming the conversation', () => {
const content = JSON.parse(buildBackgroundCapacityContent('search', 'user_running')) as {
scope: string;
message: string;
};
expect(content.scope).toBe('user_running');
expect(content.message).toContain('for this user');
expect(content.message).not.toContain('in this conversation');
});
it('caps concurrent running tasks process-wide', () => {
const registry = new BackgroundTaskRegistryClass();
for (let i = 0; i < 200; i++) {
const created = registry.create({
userId: `u-${i}`,
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 'search_mcp_docs',
});
expect('atCapacity' in created).toBe(false);
}
expect(
registry.create({
userId: 'u-rejected',
conversationId: 'c-rejected',
toolCallId: 'call_rejected',
toolName: 'search_mcp_docs',
}),
).toEqual({ atCapacity: true, scope: 'global_running' });
});
it('holds capacity permits before task registration and releases them explicitly', () => {
const registry = new BackgroundTaskRegistryClass();
const permits = Array.from({ length: 10 }, (_, index) =>
registry.reserveCapacity({
userId: 'u1',
conversationId: 'c-permits',
toolCallId: `call_${index}`,
runId: 'run-1',
}),
);
expect(permits.every((result) => 'permit' in result)).toBe(true);
expect(
registry.reserveCapacity({
userId: 'u1',
conversationId: 'c-permits',
toolCallId: 'call_rejected',
runId: 'run-1',
}),
).toEqual({ atCapacity: true, scope: 'conversation_running' });
const first = permits[0];
if (!('permit' in first)) {
throw new Error('expected capacity permit');
}
registry.releaseCapacity(first.permit);
const replacement = registry.reserveCapacity({
userId: 'u1',
conversationId: 'c-permits',
toolCallId: 'call_replacement',
runId: 'run-1',
});
if (!('permit' in replacement)) {
throw new Error('expected replacement permit');
}
const created = registry.create({
userId: 'u1',
conversationId: 'c-permits',
toolCallId: 'call_replacement',
toolName: 'search_mcp_docs',
runId: 'run-1',
capacityPermit: replacement.permit,
});
expect('atCapacity' in created).toBe(false);
});
it('retains an in-flight capacity permit until durable reservation completes', () => {
const now = jest.spyOn(Date, 'now').mockReturnValue(1_787_000_000_000);
const registry = new BackgroundTaskRegistryClass();
const admission = registry.reserveCapacity({
userId: 'u1',
conversationId: 'c-slow-reservation',
toolCallId: 'call_slow',
runId: 'run-1',
});
if (!('permit' in admission)) {
throw new Error('expected capacity permit');
}
/** Cross both the former one-minute permit timeout and idle-bucket TTL.
* A slow durable reservation still owns this slot until its caller
* consumes or releases it. */
now.mockReturnValue(1_787_000_000_000 + 7 * 60 * 60 * 1000);
const created = registry.create({
userId: 'u1',
conversationId: 'c-slow-reservation',
toolCallId: 'call_slow',
toolName: 'search_mcp_docs',
runId: 'run-1',
capacityPermit: admission.permit,
});
expect('atCapacity' in created).toBe(false);
now.mockRestore();
});
it('evicts oldest settled tasks instead of blocking when the total cap is full', () => {
const registry = new BackgroundTaskRegistryClass();
for (let i = 0; i < 200; i++) {
const created = registry.create({
userId: 'u1',
conversationId: 'c-full',
toolCallId: `call_${i}`,
toolName: 't',
runId: 'r',
agentId: 'a',
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${i}`);
}
registry.complete('u1', 'c-full', created.task.id, { content: 'x' });
}
// bucket now holds the max number of settled tasks; a new dispatch must
// succeed by evicting the oldest settled task, not be rejected.
const next = registry.create({
userId: 'u1',
conversationId: 'c-full',
toolCallId: 'call_new',
toolName: 't',
runId: 'r',
agentId: 'a',
});
expect('atCapacity' in next).toBe(false);
if ('atCapacity' in next) {
return;
}
expect(next.isNew).toBe(true);
// total held stays bounded (one evicted, one added)
expect(registry.list('u1', 'c-full')).toHaveLength(200);
});
it('evicts oldest settled tasks at the per-user cap across conversations', () => {
const registry = new BackgroundTaskRegistryClass();
let firstTaskId = '';
let latestTaskId = '';
for (let i = 0; i <= 400; i++) {
const created = registry.create({
userId: 'u-aggregate',
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${i}`);
}
firstTaskId ||= created.task.id;
latestTaskId = created.task.id;
registry.complete('u-aggregate', `c-${i}`, created.task.id, { content: 'x' });
}
expect(registry.get('u-aggregate', 'c-0', firstTaskId)).toBeUndefined();
expect(registry.get('u-aggregate', 'c-400', latestTaskId)?.status).toBe('completed');
});
it('recreates a target bucket when aggregate eviction removes it', () => {
const registry = new BackgroundTaskRegistryClass();
for (let i = 0; i < 400; i++) {
const created = registry.create({
userId: 'u-reused-bucket',
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${i}`);
}
registry.complete('u-reused-bucket', `c-${i}`, created.task.id, { content: 'x' });
}
const replacement = registry.create({
userId: 'u-reused-bucket',
conversationId: 'c-0',
toolCallId: 'call_replacement',
toolName: 't',
});
if ('atCapacity' in replacement) {
throw new Error('unexpected replacement capacity');
}
registry.complete('u-reused-bucket', 'c-0', replacement.task.id, { content: 'replacement' });
expect(registry.get('u-reused-bucket', 'c-0', replacement.task.id)?.result).toBe('replacement');
});
it('uses one local eviction to satisfy bucket and aggregate task caps', () => {
const registry = new BackgroundTaskRegistryClass();
let otherOldestId = '';
let targetOldestId = '';
for (let i = 0; i < 200; i++) {
const other = registry.create({
userId: 'u-local-first',
conversationId: 'c-other',
toolCallId: `call_other_${i}`,
toolName: 't',
});
if ('atCapacity' in other) {
throw new Error(`unexpected other capacity at ${i}`);
}
otherOldestId ||= other.task.id;
registry.complete('u-local-first', 'c-other', other.task.id, { content: 'other' });
}
for (let i = 0; i < 200; i++) {
const target = registry.create({
userId: 'u-local-first',
conversationId: 'c-target',
toolCallId: `call_target_${i}`,
toolName: 't',
});
if ('atCapacity' in target) {
throw new Error(`unexpected target capacity at ${i}`);
}
targetOldestId ||= target.task.id;
registry.complete('u-local-first', 'c-target', target.task.id, { content: 'target' });
}
const replacement = registry.create({
userId: 'u-local-first',
conversationId: 'c-target',
toolCallId: 'call_replacement',
toolName: 't',
});
expect('atCapacity' in replacement).toBe(false);
expect(registry.get('u-local-first', 'c-other', otherOldestId)).toBeDefined();
expect(registry.get('u-local-first', 'c-target', targetOldestId)).toBeUndefined();
});
it('evicts by settlement time instead of dispatch time', () => {
const registry = new BackgroundTaskRegistryClass();
let now = Date.now();
const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => now);
try {
const slow = registry.create({
userId: 'u-settlement-order',
conversationId: 'c-slow',
toolCallId: 'call_slow',
toolName: 't',
});
if ('atCapacity' in slow) {
throw new Error('unexpected slow-task capacity');
}
let oldestSettledId = '';
for (let i = 0; i < 399; i++) {
now++;
const fast = registry.create({
userId: 'u-settlement-order',
conversationId: `c-fast-${i}`,
toolCallId: `call_fast_${i}`,
toolName: 't',
});
if ('atCapacity' in fast) {
throw new Error(`unexpected fast-task capacity at ${i}`);
}
oldestSettledId ||= fast.task.id;
registry.complete('u-settlement-order', `c-fast-${i}`, fast.task.id, {
content: 'fast',
});
}
now += 1_000;
registry.complete('u-settlement-order', 'c-slow', slow.task.id, { content: 'slow' });
now++;
const replacement = registry.create({
userId: 'u-settlement-order',
conversationId: 'c-replacement',
toolCallId: 'call_replacement',
toolName: 't',
});
expect('atCapacity' in replacement).toBe(false);
expect(registry.get('u-settlement-order', 'c-slow', slow.task.id)?.result).toBe('slow');
expect(registry.get('u-settlement-order', 'c-fast-0', oldestSettledId)).toBeUndefined();
} finally {
nowSpy.mockRestore();
}
});
it('evicts oldest settled tasks at the process-wide cap', () => {
const registry = new BackgroundTaskRegistryClass();
let firstTaskId = '';
let latestTaskId = '';
for (let i = 0; i <= 2_000; i++) {
const created = registry.create({
userId: `u-${i}`,
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${i}`);
}
firstTaskId ||= created.task.id;
latestTaskId = created.task.id;
registry.complete(`u-${i}`, `c-${i}`, created.task.id, { content: 'x' });
}
expect(registry.get('u-0', 'c-0', firstTaskId)).toBeUndefined();
expect(registry.get('u-2000', 'c-2000', latestTaskId)?.status).toBe('completed');
});
it('bounds retained payloads per user across conversations', () => {
const registry = new BackgroundTaskRegistryClass();
let firstTaskId = '';
let latestTaskId = '';
for (let i = 0; i < 18; i++) {
const created = registry.create({
userId: 'u-payload',
conversationId: `c-${i}`,
toolCallId: `call_${i}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${i}`);
}
firstTaskId ||= created.task.id;
latestTaskId = created.task.id;
registry.complete('u-payload', `c-${i}`, created.task.id, {
content: 'x',
artifact: { payload: 'x'.repeat(1_000_000) },
});
}
expect(registry.get('u-payload', 'c-0', firstTaskId)).toBeUndefined();
expect(registry.get('u-payload', 'c-17', latestTaskId)?.artifact).toBeDefined();
});
it('does not evict a completed task while its harvest is pending', () => {
const registry = new BackgroundTaskRegistryClass();
const first = registry.create({
userId: 'u-pending-harvest',
conversationId: 'c-first',
toolCallId: 'call_first',
toolName: 'execute_code',
harvestStarted: true,
});
const second = registry.create({
userId: 'u-pending-harvest',
conversationId: 'c-second',
toolCallId: 'call_second',
toolName: 'execute_code',
harvestStarted: true,
});
if ('atCapacity' in first || 'atCapacity' in second) {
throw new Error('unexpected capacity');
}
registry.complete('u-pending-harvest', 'c-first', first.task.id, {
content: 'first',
artifact: { payload: 'a'.repeat(9_000_000) },
harvestStarted: true,
});
registry.complete('u-pending-harvest', 'c-second', second.task.id, {
content: 'second',
artifact: { payload: 'b'.repeat(9_000_000) },
harvestStarted: true,
});
expect(registry.get('u-pending-harvest', 'c-first', first.task.id)?.artifact).toBeDefined();
expect(registry.get('u-pending-harvest', 'c-second', second.task.id)?.artifact).toBeUndefined();
expect(registry.get('u-pending-harvest', 'c-second', second.task.id)?.result).toBeUndefined();
});
it('does not evict an ordinary task while completion persistence is pending', () => {
const registry = new BackgroundTaskRegistryClass();
const first = registry.create({
userId: 'u-pending-persistence',
conversationId: 'c-first',
toolCallId: 'call_first',
toolName: 'search_mcp_docs',
});
const second = registry.create({
userId: 'u-pending-persistence',
conversationId: 'c-second',
toolCallId: 'call_second',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in first || 'atCapacity' in second) {
throw new Error('unexpected capacity');
}
registry.complete('u-pending-persistence', 'c-first', first.task.id, {
content: 'first',
artifact: { payload: 'a'.repeat(9_000_000) },
});
registry.markCompletionPersistencePending('u-pending-persistence', 'c-first', first.task.id);
registry.complete('u-pending-persistence', 'c-second', second.task.id, {
content: 'second',
artifact: { payload: 'b'.repeat(9_000_000) },
});
expect(registry.get('u-pending-persistence', 'c-first', first.task.id)).toBeDefined();
expect(
registry.get('u-pending-persistence', 'c-second', second.task.id)?.result,
).toBeUndefined();
});
it('skips zero-byte records when evicting retained payloads', () => {
const registry = new BackgroundTaskRegistryClass();
const empty = registry.create({
userId: 'u-zero-byte',
conversationId: 'c-empty',
toolCallId: 'call_empty',
toolName: 't',
});
const retained = registry.create({
userId: 'u-zero-byte',
conversationId: 'c-retained',
toolCallId: 'call_retained',
toolName: 't',
});
const incoming = registry.create({
userId: 'u-zero-byte',
conversationId: 'c-incoming',
toolCallId: 'call_incoming',
toolName: 't',
});
if ('atCapacity' in empty || 'atCapacity' in retained || 'atCapacity' in incoming) {
throw new Error('unexpected capacity');
}
registry.complete('u-zero-byte', 'c-empty', empty.task.id, { content: '' });
registry.complete('u-zero-byte', 'c-retained', retained.task.id, {
content: 'retained',
artifact: { payload: 'a'.repeat(9_000_000) },
});
registry.complete('u-zero-byte', 'c-incoming', incoming.task.id, {
content: 'incoming',
artifact: { payload: 'b'.repeat(8_000_000) },
});
expect(registry.get('u-zero-byte', 'c-empty', empty.task.id)).toBeDefined();
expect(registry.get('u-zero-byte', 'c-retained', retained.task.id)).toBeUndefined();
expect(registry.get('u-zero-byte', 'c-incoming', incoming.task.id)?.artifact).toBeDefined();
});
it('does not partially evict global tasks when user retention cannot be satisfied', () => {
const registry = new BackgroundTaskRegistryClass();
for (let index = 0; index < 400; index++) {
const conversationId = `c-atomic-${Math.floor(index / 200)}`;
const created = registry.create({
userId: 'u-atomic',
conversationId,
toolCallId: `call_atomic_${index}`,
toolName: 't',
harvestStarted: true,
});
if ('atCapacity' in created) {
throw new Error(`unexpected capacity at ${index}: ${created.scope}`);
}
registry.complete('u-atomic', conversationId, created.task.id, {
content: '',
harvestStarted: true,
});
}
let oldestGlobalTask: { userId: string; conversationId: string; taskId: string } | undefined;
for (let userIndex = 0; userIndex < 8; userIndex++) {
for (let taskIndex = 0; taskIndex < 200; taskIndex++) {
const userId = `u-global-${userIndex}`;
const conversationId = `c-global-${userIndex}`;
const created = registry.create({
userId,
conversationId,
toolCallId: `call_global_${userIndex}_${taskIndex}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete(userId, conversationId, created.task.id, { content: '' });
oldestGlobalTask ??= { userId, conversationId, taskId: created.task.id };
}
}
const rejected = registry.create({
userId: 'u-atomic',
conversationId: 'c-atomic-new',
toolCallId: 'call_atomic_rejected',
toolName: 't',
});
expect(rejected).toEqual({ atCapacity: true, scope: 'user_retention' });
if (oldestGlobalTask == null) {
throw new Error('expected a global eviction candidate');
}
expect(
registry.get(
oldestGlobalTask.userId,
oldestGlobalTask.conversationId,
oldestGlobalTask.taskId,
),
).toBeDefined();
});
it('does not partially evict global payloads when user payload retention cannot be satisfied', () => {
const registry = new BackgroundTaskRegistryClass();
for (let index = 0; index < 2; index++) {
const conversationId = `c-payload-protected-${index}`;
const created = registry.create({
userId: 'u-payload-atomic',
conversationId,
toolCallId: `call_payload_protected_${index}`,
toolName: 't',
harvestStarted: true,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete('u-payload-atomic', conversationId, created.task.id, {
content: 'protected',
artifact: { payload: 'p'.repeat(7_999_000) },
harvestStarted: true,
});
}
let oldestGlobalTask: { userId: string; conversationId: string; taskId: string } | undefined;
for (let index = 0; index < 6; index++) {
const userId = `u-payload-global-${index}`;
const conversationId = `c-payload-global-${index}`;
const created = registry.create({
userId,
conversationId,
toolCallId: `call_payload_global_${index}`,
toolName: 't',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
registry.complete(userId, conversationId, created.task.id, {
content: 'global',
artifact: { payload: 'g'.repeat(7_999_000) },
});
oldestGlobalTask ??= { userId, conversationId, taskId: created.task.id };
}
const incoming = registry.create({
userId: 'u-payload-atomic',
conversationId: 'c-payload-incoming',
toolCallId: 'call_payload_incoming',
toolName: 't',
});
if ('atCapacity' in incoming) {
throw new Error('unexpected capacity');
}
registry.complete('u-payload-atomic', 'c-payload-incoming', incoming.task.id, {
content: 'incoming',
artifact: { payload: 'i'.repeat(20_000) },
});
expect(registry.get('u-payload-atomic', 'c-payload-incoming', incoming.task.id)?.result).toBe(
undefined,
);
if (oldestGlobalTask == null) {
throw new Error('expected a global payload eviction candidate');
}
expect(
registry.get(
oldestGlobalTask.userId,
oldestGlobalTask.conversationId,
oldestGlobalTask.taskId,
),
).toBeDefined();
});
it('drops terminal errors when non-evictable payloads exhaust the user budget', () => {
const registry = new BackgroundTaskRegistryClass();
const first = registry.create({
userId: 'u-error-budget',
conversationId: 'c-first',
toolCallId: 'call_first',
toolName: 'execute_code',
harvestStarted: true,
});
const second = registry.create({
userId: 'u-error-budget',
conversationId: 'c-second',
toolCallId: 'call_second',
toolName: 'execute_code',
harvestStarted: true,
});
const failing = registry.create({
userId: 'u-error-budget',
conversationId: 'c-failing',
toolCallId: 'call_failing',
toolName: 'execute_code',
});
if ('atCapacity' in first || 'atCapacity' in second || 'atCapacity' in failing) {
throw new Error('unexpected capacity');
}
registry.complete('u-error-budget', 'c-first', first.task.id, {
content: 'a',
artifact: { payload: 'a'.repeat(9_000_000) },
harvestStarted: true,
});
registry.complete('u-error-budget', 'c-second', second.task.id, {
content: 'b',
artifact: { payload: 'b'.repeat(6_999_900) },
harvestStarted: true,
});
registry.fail('u-error-budget', 'c-failing', failing.task.id, 'e'.repeat(100_000));
const failed = registry.get('u-error-budget', 'c-failing', failing.task.id);
expect(failed?.status).toBe('error');
expect(failed?.error).toBeUndefined();
});
it('finishes an empty harvest without evicting payload capacity', () => {
const registry = new BackgroundTaskRegistryClass();
const first = registry.create({
userId: 'u-empty-harvest',
conversationId: 'c-first',
toolCallId: 'call_first',
toolName: 'execute_code',
});
const second = registry.create({
userId: 'u-empty-harvest',
conversationId: 'c-second',
toolCallId: 'call_second',
toolName: 'execute_code',
});
const empty = registry.create({
userId: 'u-empty-harvest',
conversationId: 'c-empty',
toolCallId: 'call_empty',
toolName: 'execute_code',
harvestStarted: true,
});
if ('atCapacity' in first || 'atCapacity' in second || 'atCapacity' in empty) {
throw new Error('unexpected capacity');
}
registry.complete('u-empty-harvest', 'c-first', first.task.id, {
content: 'a',
artifact: { payload: 'a'.repeat(9_000_000) },
});
registry.complete('u-empty-harvest', 'c-second', second.task.id, {
content: 'b',
artifact: { payload: 'b'.repeat(6_999_970) },
});
registry.complete('u-empty-harvest', 'c-empty', empty.task.id, {
content: '',
harvestStarted: true,
});
registry.finishHarvest('u-empty-harvest', 'c-empty', empty.task.id);
expect(registry.get('u-empty-harvest', 'c-first', first.task.id)).toBeDefined();
expect(registry.get('u-empty-harvest', 'c-empty', empty.task.id)?.harvestPending).toBe(false);
});
it('scopes tasks by user and conversation', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_scope',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
expect(registry.get('u2', 'c1', created.task.id)).toBeUndefined();
expect(registry.get('u1', 'c2', created.task.id)).toBeUndefined();
expect(registry.list('u2', 'c1')).toHaveLength(0);
});
});
describe('getBackgroundCodeDelivery (singleton)', () => {
it('exposes harvest state for a settled task and stays available across polls', () => {
const created = backgroundTaskRegistry.create({
userId: 'delivery_user',
conversationId: 'delivery_convo',
toolCallId: 'call_code',
toolName: 'execute_code',
messageId: 'dispatch-msg',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('delivery_user', 'delivery_convo', created.task.id, {
content: 'stdout',
artifact: { session_id: 'exec-1' },
harvestStarted: true,
});
backgroundTaskRegistry.finishHarvest('delivery_user', 'delivery_convo', created.task.id, [
{ file_id: 'f1' },
]);
const args = { background_task_id: created.task.id };
const first = getBackgroundCodeDelivery({
userId: 'delivery_user',
conversationId: 'delivery_convo',
args,
});
expect(first).toEqual(
expect.objectContaining({
status: 'completed',
toolName: 'execute_code',
toolCallId: 'call_code',
messageId: 'dispatch-msg',
result: 'stdout',
attachments: [{ file_id: 'f1' }],
backgroundTask: expect.objectContaining({
taskId: created.task.id,
status: 'completed',
}),
}),
);
/** Not one-shot: a later poll can still re-emit / re-anchor. */
expect(
getBackgroundCodeDelivery({
userId: 'delivery_user',
conversationId: 'delivery_convo',
args,
})?.attachments,
).toEqual([{ file_id: 'f1' }]);
});
it('returns undefined for tasks without a harvest (non-code tools)', () => {
const created = backgroundTaskRegistry.create({
userId: 'delivery_user',
conversationId: 'delivery_convo2',
toolCallId: 'call_mcp',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('delivery_user', 'delivery_convo2', created.task.id, {
content: 'RESULT',
});
expect(
getBackgroundCodeDelivery({
userId: 'delivery_user',
conversationId: 'delivery_convo2',
args: { background_task_id: created.task.id },
}),
).toBeUndefined();
});
});
describe('runCheckBackgroundTask (singleton)', () => {
it('returns not_found for an unknown id', async () => {
const content = await runCheckBackgroundTask({
userId: 'poll_user',
conversationId: 'poll_convo',
args: { background_task_id: 'nope' },
});
expect(JSON.parse(content)).toEqual(
expect.objectContaining({ status: 'not_found', background_task_id: 'nope' }),
);
});
it('keeps ordinary cancellation disabled unless the deployment opts in', async () => {
const requestCancellation = jest.fn();
const created = backgroundTaskRegistry.create({
userId: 'disabled-cancel-user',
conversationId: 'disabled-cancel-conversation',
toolCallId: 'disabled-cancel-call',
toolName: 'bash_tool',
requestCancellation,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'disabled-cancel-user',
conversationId: 'disabled-cancel-conversation',
args: { background_task_id: created.task.id, action: 'cancel' },
}),
);
expect(result).toMatchObject({ status: 'invalid', background_task_id: created.task.id });
expect(requestCancellation).not.toHaveBeenCalled();
backgroundTaskRegistry.fail(
'disabled-cancel-user',
'disabled-cancel-conversation',
created.task.id,
'test cleanup',
);
});
it('uses normal durable claim arbitration when cancellation loses the settlement race', async () => {
const created = backgroundTaskRegistry.create({
userId: 'cancel-race-user',
conversationId: 'cancel-race-conversation',
toolCallId: 'cancel-race-call',
toolName: 'bash_tool',
messageId: 'cancel-race-message',
requestCancellation: jest.fn(),
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.markCompletionWakeup(
'cancel-race-user',
'cancel-race-conversation',
created.task.id,
{
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
},
);
backgroundTaskRegistry.complete(
'cancel-race-user',
'cancel-race-conversation',
created.task.id,
{ content: 'settled result' },
);
const claimBackgroundToolResult = jest.fn(async () => ({
status: 'claimed' as const,
claim: { kind: 'wakeup' as const, claimId: 'automatic-delivery' },
}));
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'cancel-race-user',
conversationId: 'cancel-race-conversation',
args: { background_task_id: created.task.id, action: 'cancel' },
ordinaryToolCancellation: true,
claimBackgroundToolResult,
}),
);
expect(result).toMatchObject({
status: 'delivery_scheduled',
background_task_id: created.task.id,
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(1);
});
it('rejects an oversized task id before local or cross-replica lookup', async () => {
const store = Object.assign(new InMemorySubagentTaskStore(), {
claimTask: jest.fn(),
controlTask: jest.fn(),
listTasks: jest.fn(),
});
const content = await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: 'x'.repeat(257) },
subagentTasks: { store, scopeId: 'owner:parent-thread' },
});
expect(JSON.parse(content)).toEqual({
status: 'invalid',
message: 'A background_task_id cannot exceed 256 characters.',
});
expect(store.claimTask).not.toHaveBeenCalled();
expect(store.controlTask).not.toHaveBeenCalled();
expect(store.listTasks).not.toHaveBeenCalled();
});
it('returns a single task by id and lists all when omitted', async () => {
const created = backgroundTaskRegistry.create({
userId: 'poll_user',
conversationId: 'poll_convo2',
toolCallId: 'call_poll',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('poll_user', 'poll_convo2', created.task.id, {
content: 'RESULT',
});
const single = JSON.parse(
await runCheckBackgroundTask({
userId: 'poll_user',
conversationId: 'poll_convo2',
args: { background_task_id: created.task.id },
}),
);
expect(single).toEqual(
expect.objectContaining({
status: 'completed',
result: 'RESULT',
background_task_id: created.task.id,
}),
);
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'poll_user',
conversationId: 'poll_convo2',
args: {},
}),
);
expect(listed.tasks).toHaveLength(1);
expect(listed.tasks[0].background_task_id).toBe(created.task.id);
// list path must NOT dump full results (context-overflow guard); metadata only
expect(listed.tasks[0].result).toBeUndefined();
expect(listed.tasks[0]).toEqual(
expect.objectContaining({ status: 'completed', result_available: true, result_chars: 6 }),
);
// stringified args must still resolve the specific task (with its full result)
const singleFromString = JSON.parse(
await runCheckBackgroundTask({
userId: 'poll_user',
conversationId: 'poll_convo2',
args: `{"background_task_id":"${created.task.id}"}`,
}),
);
expect(singleFromString).toEqual(
expect.objectContaining({ status: 'completed', result: 'RESULT' }),
);
});
it('reports ISO dispatch and settlement stamps with the elapsed span', async () => {
const nowSpy = jest.spyOn(Date, 'now');
try {
const created = backgroundTaskRegistry.create({
userId: 'timing_user',
conversationId: 'timing_convo',
toolCallId: 'call_timing',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
/** The dispatch stamp is monotonic per process, so it is whatever the registry
* assigned rather than the clock at this instant; drive the clock from it. */
const dispatchedAt = created.task.createdAt;
nowSpy.mockReturnValue(dispatchedAt + 90_000);
const running = JSON.parse(
await runCheckBackgroundTask({
userId: 'timing_user',
conversationId: 'timing_convo',
args: { background_task_id: created.task.id },
}),
);
expect(running).toMatchObject({
status: 'running',
started_at: new Date(dispatchedAt).toISOString(),
elapsed_ms: 90_000,
});
/** A running task has not settled, so it must not claim a terminal stamp. */
expect(running.settled_at).toBeUndefined();
nowSpy.mockReturnValue(dispatchedAt + 120_000);
backgroundTaskRegistry.complete('timing_user', 'timing_convo', created.task.id, {
content: 'RESULT',
});
nowSpy.mockReturnValue(dispatchedAt + 600_000);
const settled = JSON.parse(
await runCheckBackgroundTask({
userId: 'timing_user',
conversationId: 'timing_convo',
args: { background_task_id: created.task.id },
}),
);
/** The span freezes at settlement instead of growing with every later poll. */
expect(settled).toMatchObject({
status: 'completed',
started_at: new Date(dispatchedAt).toISOString(),
settled_at: new Date(dispatchedAt + 120_000).toISOString(),
elapsed_ms: 120_000,
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'timing_user',
conversationId: 'timing_convo',
args: {},
}),
);
expect(listed.tasks[0]).toMatchObject({
started_at: new Date(dispatchedAt).toISOString(),
settled_at: new Date(dispatchedAt + 120_000).toISOString(),
elapsed_ms: 120_000,
});
} finally {
nowSpy.mockRestore();
}
});
it('lets a later-generation poll collect a receipt without inheriting an abandoned local claim', async () => {
const created = backgroundTaskRegistry.create({
userId: 'claim_user',
conversationId: 'claim_convo',
toolCallId: 'call_claim',
toolName: 'search_mcp_docs',
messageId: 'response-claim',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('claim_user', 'claim_convo', created.task.id, {
content: 'CLAIMED RESULT',
});
const retire = jest.fn(async () => true);
backgroundTaskRegistry.markCompletionWakeup('claim_user', 'claim_convo', created.task.id, {
renew: jest.fn(async () => true),
retire,
});
const claimBackgroundToolResult = jest
.fn()
.mockResolvedValueOnce({ status: 'not_ready' })
.mockResolvedValueOnce({ status: 'not_ready' })
.mockResolvedValueOnce({ status: 'not_ready' })
.mockResolvedValueOnce({ status: 'acquired', results: [] });
const request = {
userId: 'claim_user',
conversationId: 'claim_convo',
args: { background_task_id: created.task.id },
agentId: 'agent_parent_1',
runId: 'poll-run',
generationId: 'response-later-poll',
claimBackgroundToolResult,
};
const persisting = JSON.parse(
await runCheckBackgroundTask({ ...request, toolCallId: 'poll-call-1' }),
);
expect(persisting).toMatchObject({ status: 'result_persisting' });
expect(JSON.stringify(persisting)).not.toContain('CLAIMED RESULT');
expect(
backgroundTaskRegistry.get('claim_user', 'claim_convo', created.task.id)?.resultClaim,
).toBeUndefined();
const laterPoll = JSON.parse(
await runCheckBackgroundTask({ ...request, toolCallId: 'poll-call-2' }),
);
expect(laterPoll).toMatchObject({ status: 'completed', result: 'CLAIMED RESULT' });
expect(
backgroundTaskRegistry.get('claim_user', 'claim_convo', created.task.id)?.resultClaim,
).toMatchObject({ kind: 'manual', generationId: 'response-later-poll' });
expect(retire).toHaveBeenCalledTimes(1);
expect(retire).toHaveBeenCalledWith('completion claimed by same-generation manual poll', {
onlyIfUnclaimed: true,
});
expect(claimBackgroundToolResult).toHaveBeenLastCalledWith(
expect.objectContaining({
messageId: 'response-claim',
taskId: created.task.id,
kind: 'manual',
generationId: 'response-later-poll',
allowUnfinished: true,
}),
);
});
it('delivers a completed result inside its originating generation before the response row finalizes', async () => {
const created = backgroundTaskRegistry.create({
userId: 'originating_user',
conversationId: 'originating_convo',
toolCallId: 'call_originating',
toolName: 'search_mcp_docs',
messageId: 'response-originating',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('originating_user', 'originating_convo', created.task.id, {
content: 'ORIGINATING RESULT',
});
const retire = jest.fn(async () => true);
backgroundTaskRegistry.markCompletionWakeup(
'originating_user',
'originating_convo',
created.task.id,
{ renew: jest.fn(async () => true), retire },
);
const claimBackgroundToolResult = jest.fn(async () => ({ status: 'not_ready' as const }));
const request = {
userId: 'originating_user',
conversationId: 'originating_convo',
args: { background_task_id: created.task.id },
toolCallId: 'poll-originating',
runId: 'originating-run',
generationId: 'response-originating',
claimBackgroundToolResult,
};
const result = JSON.parse(await runCheckBackgroundTask(request));
const replay = JSON.parse(await runCheckBackgroundTask(request));
expect(result).toMatchObject({ status: 'completed', result: 'ORIGINATING RESULT' });
expect(replay).toMatchObject({ status: 'completed', result: 'ORIGINATING RESULT' });
expect(retire).toHaveBeenCalledTimes(1);
expect(retire).toHaveBeenCalledWith('completion claimed by same-generation manual poll', {
onlyIfUnclaimed: true,
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(2);
expect(
backgroundTaskRegistry.get('originating_user', 'originating_convo', created.task.id)
?.resultClaim,
).toMatchObject({
kind: 'manual',
generationId: 'response-originating',
});
});
it('reclaims a dead manual delivery after its owning generation is gone', async () => {
const claimBackgroundToolResult = jest
.fn()
.mockResolvedValueOnce({
status: 'claimed',
messageId: 'response-recovered',
claim: {
kind: 'manual',
claimId: 'abandoned-poll',
generationId: 'response-abandoned',
},
})
.mockResolvedValueOnce({
status: 'acquired',
messageId: 'response-recovered',
results: [
{
taskId: 'task-recovered-manual',
toolCallId: 'call-recovered-manual',
toolName: 'mutating_tool',
status: 'completed',
output: 'mutation already completed',
},
],
});
const recoverDeadBackgroundToolClaim = jest.fn(async () => true);
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'recovered_user',
conversationId: 'recovered_convo',
args: { background_task_id: 'task-recovered-manual' },
toolCallId: 'replacement-poll',
runId: 'replacement-run',
generationId: 'response-replacement',
claimBackgroundToolResult,
recoverDeadBackgroundToolClaim,
}),
);
expect(result).toMatchObject({
status: 'completed',
background_task_id: 'task-recovered-manual',
result: 'mutation already completed',
});
expect(recoverDeadBackgroundToolClaim).toHaveBeenCalledWith({
userId: 'recovered_user',
conversationId: 'recovered_convo',
messageId: 'response-recovered',
claimId: 'abandoned-poll',
kind: 'manual',
generationId: 'response-abandoned',
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(2);
});
it('delivers a mandatory live-artifact poll without waiting for its dispatch row', async () => {
const created = backgroundTaskRegistry.create({
userId: 'artifact_poll_user',
conversationId: 'artifact_poll_convo',
toolCallId: 'call_artifact_poll',
toolName: 'artifact_tool',
messageId: 'response-artifact-poll',
liveArtifactPollRequired: true,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('artifact_poll_user', 'artifact_poll_convo', created.task.id, {
content: 'CONTENT WITH LIVE ARTIFACT',
artifact: { type: 'test-artifact' },
});
const retire = jest.fn(async () => true);
backgroundTaskRegistry.markCompletionWakeup(
'artifact_poll_user',
'artifact_poll_convo',
created.task.id,
{ renew: jest.fn(async () => true), retire },
);
const claimBackgroundToolResult = jest.fn(async () => ({ status: 'not_ready' as const }));
const request = {
userId: 'artifact_poll_user',
conversationId: 'artifact_poll_convo',
args: { background_task_id: created.task.id },
toolCallId: 'poll-live-artifact',
runId: 'dispatch-run',
claimBackgroundToolResult,
};
const result = JSON.parse(await runCheckBackgroundTask(request));
const replay = JSON.parse(await runCheckBackgroundTask(request));
expect(result).toMatchObject({ status: 'completed', result: 'CONTENT WITH LIVE ARTIFACT' });
expect(replay).toMatchObject({ status: 'completed', result: 'CONTENT WITH LIVE ARTIFACT' });
expect(retire).toHaveBeenCalledWith('completion claimed by same-generation manual poll', {
onlyIfUnclaimed: true,
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(2);
expect(
backgroundTaskRegistry.get('artifact_poll_user', 'artifact_poll_convo', created.task.id)
?.resultClaim,
).toMatchObject({ kind: 'manual' });
});
it('does not expose a result already assigned to an automatic continuation', async () => {
const created = backgroundTaskRegistry.create({
userId: 'scheduled_user',
conversationId: 'scheduled_convo',
toolCallId: 'call_scheduled',
toolName: 'search_mcp_docs',
messageId: 'response-scheduled',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('scheduled_user', 'scheduled_convo', created.task.id, {
content: 'PRIVATE UNTIL CONTINUATION',
});
backgroundTaskRegistry.markCompletionWakeup(
'scheduled_user',
'scheduled_convo',
created.task.id,
);
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'scheduled_user',
conversationId: 'scheduled_convo',
args: { background_task_id: created.task.id },
claimBackgroundToolResult: async () => ({ status: 'claimed' }),
}),
);
expect(result).toMatchObject({ status: 'delivery_scheduled' });
expect(JSON.stringify(result)).not.toContain('PRIVATE UNTIL CONTINUATION');
});
it.each([
{ status: 'completed' as const, field: 'result', output: 'RECOVERED RESULT' },
{ status: 'error' as const, field: 'error', output: 'RECOVERED FAILURE' },
])('recovers a durable $status receipt after process-local state is lost', async (terminal) => {
const settledAt = new Date('2026-09-22T09:00:00.000Z');
const claimBackgroundToolResult = jest.fn(async () => ({
status: 'acquired' as const,
messageId: 'response-recovered',
results: [
{
taskId: 'task-recovered',
toolCallId: 'call-recovered',
toolName: 'slow_tool',
status: terminal.status,
output: terminal.output,
settledAt,
},
],
}));
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'recovered_user',
conversationId: 'recovered_convo',
args: { background_task_id: 'task-recovered' },
toolCallId: 'recovery-poll',
runId: 'recovery-run',
claimBackgroundToolResult,
}),
);
expect(result).toMatchObject({
status: terminal.status,
background_task_id: 'task-recovered',
[terminal.field]: terminal.output,
/** The receipt records settlement only, so a recovered poll reports no span. */
settled_at: settledAt.toISOString(),
});
expect(result.started_at).toBeUndefined();
expect(result.elapsed_ms).toBeUndefined();
expect(claimBackgroundToolResult).toHaveBeenCalledWith(
expect.not.objectContaining({ messageId: expect.anything() }),
);
});
it('reports a lost executor without implying that a mutating task is safe to retry', async () => {
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'unknown_user',
conversationId: 'unknown_convo',
args: { background_task_id: 'task-unknown' },
toolCallId: 'unknown-poll',
runId: 'unknown-run',
claimBackgroundToolResult: async () => ({
status: 'outcome_unknown',
toolName: 'mutating_tool',
}),
}),
);
expect(result).toMatchObject({
status: 'outcome_unknown',
background_task_id: 'task-unknown',
tool: 'mutating_tool',
});
expect(result.message).toContain('Do not repeat a mutating operation automatically');
});
it('recovers a result through its dead batch-owner claim', async () => {
const created = backgroundTaskRegistry.create({
userId: 'dead_claim_user',
conversationId: 'dead_claim_convo',
toolCallId: 'call_dead_claim',
toolName: 'search_mcp_docs',
messageId: 'response-dead-claim',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('dead_claim_user', 'dead_claim_convo', created.task.id, {
content: 'RECOVERED CLAIMED RESULT',
});
backgroundTaskRegistry.markCompletionWakeup(
'dead_claim_user',
'dead_claim_convo',
created.task.id,
);
const claimBackgroundToolResult = jest
.fn()
.mockResolvedValueOnce({
status: 'claimed',
claim: { kind: 'wakeup', claimId: 'sibling-batch-root' },
})
.mockResolvedValueOnce({ status: 'acquired', results: [] });
const recoverDeadBackgroundToolClaim = jest.fn(async () => true);
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'dead_claim_user',
conversationId: 'dead_claim_convo',
args: { background_task_id: created.task.id },
toolCallId: 'poll-dead-claim',
runId: 'poll-run',
claimBackgroundToolResult,
recoverDeadBackgroundToolClaim,
}),
);
expect(result).toMatchObject({ status: 'completed', result: 'RECOVERED CLAIMED RESULT' });
expect(recoverDeadBackgroundToolClaim).toHaveBeenCalledWith({
userId: 'dead_claim_user',
conversationId: 'dead_claim_convo',
messageId: 'response-dead-claim',
claimId: 'sibling-batch-root',
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(2);
});
it('does not expose a local result after its automatic resolver owns the lease', async () => {
const created = backgroundTaskRegistry.create({
userId: 'retire_user',
conversationId: 'retire_convo',
toolCallId: 'call_retire',
toolName: 'search_mcp_docs',
messageId: 'response-retire',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('retire_user', 'retire_convo', created.task.id, {
content: 'DO NOT DUPLICATE',
});
const retire = jest.fn(async () => false);
backgroundTaskRegistry.markCompletionWakeup('retire_user', 'retire_convo', created.task.id, {
renew: jest.fn(async () => true),
retire,
});
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'retire_user',
conversationId: 'retire_convo',
args: { background_task_id: created.task.id },
toolCallId: 'poll-retire',
runId: 'poll-run',
claimBackgroundToolResult: async () => ({ status: 'not_ready' }),
}),
);
expect(result).toMatchObject({ status: 'result_persisting' });
expect(JSON.stringify(result)).not.toContain('DO NOT DUPLICATE');
expect(
backgroundTaskRegistry.get('retire_user', 'retire_convo', created.task.id)?.resultClaim,
).toBeUndefined();
expect(retire).toHaveBeenCalledWith('completion claimed by same-generation manual poll', {
onlyIfUnclaimed: true,
});
expect(retire).toHaveBeenCalledWith(
'dead completion recovered by same-generation manual poll',
{
onlyIfDead: true,
},
);
});
it('recovers a dead automatic completion into process-local polling', async () => {
const created = backgroundTaskRegistry.create({
userId: 'dead_user',
conversationId: 'dead_convo',
toolCallId: 'call_dead',
toolName: 'search_mcp_docs',
messageId: 'response-dead',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('dead_user', 'dead_convo', created.task.id, {
content: 'RECOVERED RESULT',
});
const retire = jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true);
backgroundTaskRegistry.markCompletionWakeup('dead_user', 'dead_convo', created.task.id, {
renew: jest.fn(async () => true),
retire,
});
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'dead_user',
conversationId: 'dead_convo',
args: { background_task_id: created.task.id },
toolCallId: 'poll-dead',
runId: 'poll-run',
claimBackgroundToolResult: async () => ({ status: 'not_ready' }),
}),
);
expect(result).toMatchObject({ status: 'completed', result: 'RECOVERED RESULT' });
expect(retire).toHaveBeenNthCalledWith(1, 'completion claimed by same-generation manual poll', {
onlyIfUnclaimed: true,
});
expect(retire).toHaveBeenNthCalledWith(
2,
'dead completion recovered by same-generation manual poll',
{ onlyIfDead: true },
);
expect(
backgroundTaskRegistry.get('dead_user', 'dead_convo', created.task.id)
?.completionPersistenceFailed,
).toBe(true);
});
it('preserves local task lists when cross-replica subagent discovery is unavailable', async () => {
const ordinary = backgroundTaskRegistry.create({
userId: 'partial-list-owner',
conversationId: 'partial-list-parent',
toolCallId: 'ordinary-call',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in ordinary) {
throw new Error('unexpected capacity');
}
const store = new InMemorySubagentTaskStore();
const started = store.start({
scopeId: 'partial-list-owner:partial-list-parent',
idempotencyKey: 'partial-list-run:parent-agent:subagent-call',
parentRunId: 'partial-list-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'subagent-call',
input: 'Keep working locally.',
subagentKind: 'agent',
subagentType: 'researcher',
run: async () => ({ content: 'local result' }),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
await waitForSubagentTaskToSettle(
store,
'partial-list-owner:partial-list-parent',
started.task.taskId,
);
const routedStore = Object.assign(store, {
claimTask: jest.fn(),
controlTask: jest.fn(),
listTasks: jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()),
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'partial-list-owner',
conversationId: 'partial-list-parent',
args: {},
subagentTasks: {
store: routedStore,
scopeId: 'partial-list-owner:partial-list-parent',
},
}),
);
expect(listed).toEqual(
expect.objectContaining({
partial: true,
warning:
'Cross-replica subagent tasks could not be listed: The process running this subagent task is temporarily unavailable.',
}),
);
expect(
listed.tasks.map((task: { background_task_id: string }) => task.background_task_id),
).toEqual(expect.arrayContaining([ordinary.task.id, started.task.taskId]));
});
it('retrieves a task across turns: the poll is keyed only by id, not the dispatch run/turn', async () => {
// Turn 1 dispatches under run-turn-1 and the result lands after the turn.
const dispatched = backgroundTaskRegistry.create({
userId: 'poll_user',
conversationId: 'poll_xturn',
toolCallId: 'call_xturn',
toolName: 'search_mcp_docs',
runId: 'run-turn-1',
agentId: 'agent-A',
});
if ('atCapacity' in dispatched) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.complete('poll_user', 'poll_xturn', dispatched.task.id, {
content: 'XTURN_RESULT',
});
// Turn 2 (a later run) polls with just the id; get/list carry no run/turn scope.
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'poll_user',
conversationId: 'poll_xturn',
args: { background_task_id: dispatched.task.id },
}),
);
expect(polled).toEqual(
expect.objectContaining({
status: 'completed',
result: 'XTURN_RESULT',
background_task_id: dispatched.task.id,
}),
);
});
it('polls and one-shot claims a detached subagent result', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: SubagentTaskConfig = { store, scopeId: 'owner:parent-thread' };
const claimBackgroundToolResult = jest.fn(async () => {
throw new Error('message recovery unavailable');
});
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:call-1',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-1',
input: 'Research this.',
subagentKind: 'agent',
subagentType: 'researcher',
run: async () => ({ content: 'finished research' }),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
await waitForSubagentTaskToSettle(store, subagentTasks.scopeId, started.task.taskId);
const first = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: started.task.taskId },
subagentTasks,
claimBackgroundToolResult,
}),
);
expect(first).toEqual(
expect.objectContaining({
background_task_id: started.task.taskId,
subagent_thread_id: started.task.threadId,
tool: 'subagent',
status: 'completed',
result: 'finished research',
}),
);
const second = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: started.task.taskId },
subagentTasks,
claimBackgroundToolResult,
}),
);
expect(second).toEqual(expect.objectContaining({ status: 'claimed', result_claimed: true }));
expect(second.result).toBeUndefined();
expect(claimBackgroundToolResult).not.toHaveBeenCalled();
/** A subagent task reports the same timings as an ordinary one. */
for (const polled of [first, second]) {
expect(Number.isNaN(Date.parse(polled.started_at))).toBe(false);
expect(Date.parse(polled.settled_at)).toBeGreaterThanOrEqual(Date.parse(polled.started_at));
expect(polled.elapsed_ms).toBe(Date.parse(polled.settled_at) - Date.parse(polled.started_at));
}
});
it('falls through cleanly when neither background store recognizes a poll id', async () => {
const store = new InMemorySubagentTaskStore();
const claimBackgroundToolResult = jest.fn(async () => ({ status: 'not_found' as const }));
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: 'unknown-task' },
subagentTasks: { store, scopeId: 'owner:parent-thread' },
claimBackgroundToolResult,
}),
);
expect(result).toEqual({
status: 'not_found',
background_task_id: 'unknown-task',
message: 'No background task with that id exists in this thread.',
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(1);
});
it('recovers an ordinary durable result even when the subagent store is unavailable', async () => {
const store = Object.assign(new InMemorySubagentTaskStore(), {
claimTask: jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()),
});
const claimBackgroundToolResult = jest.fn(async () => ({
status: 'acquired' as const,
results: [
{
taskId: 'ordinary-task',
toolCallId: 'ordinary-call',
toolName: 'mutating_tool',
status: 'completed' as const,
output: 'ordinary result',
},
],
}));
const result = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: 'ordinary-task' },
subagentTasks: { store, scopeId: 'owner:parent-thread' },
claimBackgroundToolResult,
}),
);
expect(result).toMatchObject({
status: 'completed',
background_task_id: 'ordinary-task',
result: 'ordinary result',
});
expect(claimBackgroundToolResult).toHaveBeenCalledTimes(1);
});
it('counts a finished subagent as outstanding until its result is delivered', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: HostSubagentTaskConfig = {
store,
scopeId: 'owner:settled-subagent-parent',
completionDelivery: SUBAGENT_COMPLETION_DELIVERY,
};
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:call-settled',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-settled',
input: 'Research this.',
subagentKind: 'agent',
subagentType: 'researcher',
run: async () => ({ content: 'research done' }),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
for (
let i = 0;
i < 50 && store.get(subagentTasks.scopeId, started.task.taskId)?.status === 'running';
i++
) {
await new Promise((resolve) => setImmediate(resolve));
}
const listWithWakeups = async (subagentWakeups: string[]) =>
JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'settled-subagent-parent',
agentId: 'agent_parent',
args: {},
subagentTasks,
pendingCompletions: {
list: jest.fn(async () => ({ completions: [], dead: [], complete: true })),
listSubagentWakeups: jest.fn(async () => ({
taskIds: subagentWakeups,
complete: true,
})),
discard: jest.fn(async () => 'not_pending' as const),
settleClaimed: jest.fn(async () => false),
},
}),
);
/** No durable wake-up (admitted poll-only): nothing will arrive, so nothing is pending. */
const pollOnly = await listWithWakeups([]);
expect(pollOnly.tasks[0].delivery).toBeUndefined();
expect(pollOnly.outstanding).toBe(0);
const listed = await listWithWakeups([started.task.taskId]);
expect(listed.tasks[0]).toEqual(
expect.objectContaining({ status: 'completed', result_available: true, delivery: 'pending' }),
);
expect(listed.outstanding).toBe(1);
expect(listed.message).toContain('Some finished subagents have not been delivered yet');
expect(listed.message).not.toContain('cancel');
});
it('tells a wakeup-enabled parent to yield on an unchanged running subagent', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: HostSubagentTaskConfig = {
store,
scopeId: 'owner:wakeup-parent',
completionDelivery: SUBAGENT_COMPLETION_DELIVERY,
};
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:call-wakeup',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-wakeup',
input: 'Research this.',
subagentKind: 'agent',
subagentType: 'researcher',
run: (runtime: SubagentTaskRuntime) =>
new Promise((_, reject) => {
runtime.signal.addEventListener('abort', () => reject(runtime.signal.reason), {
once: true,
});
}),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'wakeup-parent',
agentId: 'agent_parent',
args: { background_task_id: started.task.taskId },
subagentTasks,
}),
);
expect(polled).toMatchObject({
status: 'running',
message: SUBAGENT_POLL_WAKEUP_GUIDANCE,
next_check_s: 30,
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'wakeup-parent',
agentId: 'agent_parent',
args: {},
subagentTasks,
}),
);
expect(listed.message).toBe(SUBAGENT_WAKEUP_GUIDANCE);
expect(listed.tasks[0].message).toBeUndefined();
const ephemeralPoll = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'wakeup-parent',
agentId: 'openAI__gpt-4o',
args: { background_task_id: started.task.taskId },
subagentTasks,
}),
);
expect(ephemeralPoll.status).toBe('running');
expect(ephemeralPoll.message).toBe(SUBAGENT_POLL_GUIDANCE);
store.control(subagentTasks.scopeId, started.task.taskId, { action: 'cancel' });
});
it('preserves poll-first running status when automatic delivery is disabled', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: SubagentTaskConfig = { store, scopeId: 'owner:manual-parent' };
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:call-manual',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-manual',
input: 'Research this.',
subagentKind: 'agent',
subagentType: 'researcher',
run: (runtime: SubagentTaskRuntime) =>
new Promise((_, reject) => {
runtime.signal.addEventListener('abort', () => reject(runtime.signal.reason), {
once: true,
});
}),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'manual-parent',
args: { background_task_id: started.task.taskId },
subagentTasks,
}),
);
expect(polled).toMatchObject({
status: 'running',
message: SUBAGENT_POLL_GUIDANCE,
next_check_s: 30,
});
expect(polled.message).not.toContain('resumes you automatically');
store.control(subagentTasks.scopeId, started.task.taskId, { action: 'cancel' });
});
it('routes parent control actions only to detached subagent tasks', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: SubagentTaskConfig = { store, scopeId: 'owner:parent-thread' };
let finish = (_value: { content: string }): void => undefined;
const result = new Promise<{ content: string }>((resolve) => {
finish = resolve;
});
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:call-2',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-2',
input: 'Keep working.',
subagentKind: 'agent',
subagentType: 'researcher',
run: async () => result,
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
await Promise.resolve();
const queued = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: {
background_task_id: started.task.taskId,
action: 'queue',
message: 'Also verify the source.',
},
subagentTasks,
}),
);
expect(queued).toEqual(
expect.objectContaining({ status: 'accepted', control_id: expect.any(String) }),
);
const cancelledMessage = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: {
background_task_id: started.task.taskId,
action: 'cancel_message',
control_id: queued.control_id,
},
subagentTasks,
}),
);
expect(cancelledMessage.status).toBe('accepted');
const cancelledTask = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: started.task.taskId, action: 'cancel' },
subagentTasks,
}),
);
expect(cancelledTask.status).toBe('cancelled');
finish({ content: 'late result' });
});
it('derives a bounded control invocation identity from the tool call', async () => {
const controlTask = jest.fn().mockResolvedValue({
status: 'not_running',
task: {
taskId: 'remote-task',
subagentType: 'researcher',
status: 'completed',
createdAt: 1,
updatedAt: 2,
resultAvailable: false,
resultClaimed: true,
pendingControls: 0,
},
});
const store = Object.assign(new InMemorySubagentTaskStore(), {
claimTask: jest.fn(),
controlTask,
listTasks: jest.fn(),
});
const control = (toolCallId: string | undefined) =>
runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: {
background_task_id: 'remote-task',
action: 'queue',
message: 'Check one more source.',
},
toolCallId,
subagentTasks: { store, scopeId: 'owner:parent-thread' },
});
/** Replaying one tool call keeps its identity, so routing can replay the result. */
await control('call_abc');
await control('call_abc');
const [firstInvocation, replayedInvocation] = controlTask.mock.calls.map((call) => call[3]);
expect(firstInvocation).toBe(replayedInvocation);
expect(firstInvocation).toHaveLength(32);
/** A separate tool call is a separate command even with an identical payload. */
await control('call_def');
expect(controlTask.mock.calls[2][3]).not.toBe(firstInvocation);
/** The same provider id in another run or agent is a different command. */
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: {
background_task_id: 'remote-task',
action: 'queue',
message: 'Check one more source.',
},
toolCallId: 'call_abc',
runId: 'run-2:0',
subagentTasks: { store, scopeId: 'owner:parent-thread' },
});
expect(controlTask.mock.calls[3][3]).not.toBe(firstInvocation);
/** A provider id far past the protocol bound still routes as a bounded identity. */
const longToolCallId = `call_${'x'.repeat(200)}`;
await control(longToolCallId);
await control(longToolCallId);
const [longInvocation, replayedLongInvocation] = controlTask.mock.calls
.slice(4)
.map((call) => call[3]);
expect(longInvocation).toHaveLength(32);
expect(replayedLongInvocation).toBe(longInvocation);
/** Without a tool-call id each invocation stays distinct rather than colliding. */
await control(undefined);
await control(undefined);
const [fallback, otherFallback] = controlTask.mock.calls.slice(6).map((call) => call[3]);
expect(fallback).not.toBe(otherFallback);
expect(fallback.length).toBeLessThanOrEqual(128);
});
it('reports an unreachable remote subagent owner without pretending the task is missing', async () => {
const store = Object.assign(new InMemorySubagentTaskStore(), {
claimTask: jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()),
controlTask: jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()),
listTasks: jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()),
});
const content = await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'parent-thread',
args: { background_task_id: 'remote-task' },
subagentTasks: { store, scopeId: 'owner:parent-thread' },
});
expect(JSON.parse(content)).toEqual({
status: 'unavailable',
background_task_id: 'remote-task',
message: 'The process running this subagent task is temporarily unavailable.',
});
});
});
describe('stripBackgroundFromToolRegistry', () => {
it('drops the poll entry and the injected param without mutating the input', () => {
const searchDef = mcpDef('search_mcp_docs');
const registry: LCToolRegistry = new Map([['search_mcp_docs', { ...searchDef }]]);
applyBackgroundToolCalls({
toolDefinitions: [searchDef],
toolRegistry: registry,
toolOptions: { search_mcp_docs: { run_in_background: true } },
});
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
const stripped = stripBackgroundFromToolRegistry(registry, ['search_mcp_docs']);
expect(stripped?.has(CHECK_BACKGROUND_TASK_NAME)).toBe(false);
expect(
(stripped?.get('search_mcp_docs')?.parameters as { properties: Record<string, unknown> })
.properties[RUN_IN_BACKGROUND_ARG],
).toBeUndefined();
// original untouched (parent still needs background)
expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
});
});
describe('buildBackgroundHandleContent', () => {
it.each([{}, { completionWakeup: true }, { liveArtifactPollRequired: true }])(
'keeps the server handle compatible with the client parser: %j',
(options) => {
const content = buildBackgroundHandleContent(
{ id: '2a6b05c3-327d-43f4-8196-73a6c8d88706', toolName: 'bash_tool', status: 'running' },
options,
);
expect(parseBackgroundHandle(content)).toEqual(JSON.parse(content));
},
);
it('produces a running handle carrying the id and poll instruction', () => {
const registry = new BackgroundTaskRegistryClass();
const created = registry.create({
userId: 'u1',
conversationId: 'c1',
toolCallId: 'call_h',
toolName: 'search_mcp_docs',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const parsed = JSON.parse(buildBackgroundHandleContent(created.task));
expect(parsed.background_task_id).toBe(created.task.id);
expect(parsed.status).toBe('running');
expect(parsed.message).toContain(CHECK_BACKGROUND_TASK_NAME);
expect(Object.keys(parsed).sort()).toEqual(['background_task_id', 'message', 'status', 'tool']);
expect(JSON.parse(parsed.message.split('Status request: ')[1])).toEqual({
name: CHECK_BACKGROUND_TASK_NAME,
arguments: { background_task_id: created.task.id },
});
});
it('requires polling when the tool can return a process-local live artifact', () => {
const parsed = JSON.parse(
buildBackgroundHandleContent(
{ id: 'artifact-task', toolName: 'artifact_tool', status: 'running' },
{ completionWakeup: true, liveArtifactPollRequired: true },
),
);
expect(parsed.message).toContain('must call check_background_task');
expect(parsed.message).toContain('do not end the turn');
});
});
describe('toolOptionsSchema', () => {
it('preserves run_in_background alongside the existing options', () => {
const parsed = toolOptionsSchema.parse({
defer_loading: true,
run_in_background: true,
allowed_callers: ['direct'],
});
expect(parsed.run_in_background).toBe(true);
expect(parsed.defer_loading).toBe(true);
});
it('strips unknown keys but keeps run_in_background', () => {
const parsed = toolOptionsSchema.parse({
run_in_background: true,
bogus: 'x',
} as Record<string, unknown>);
expect(parsed).toEqual({ run_in_background: true });
});
});
describe('runCheckBackgroundTask delivery semantics', () => {
const pendingControls = (
overrides: {
list?: () => Promise<unknown[]>;
complete?: boolean;
dead?: unknown[];
subagentWakeups?: string[];
discard?: () => Promise<string>;
} = {},
) =>
({
list: jest.fn(async () => ({
completions: await (overrides.list ?? (async () => []))(),
dead: overrides.dead ?? [],
complete: overrides.complete ?? true,
})),
listSubagentWakeups: jest.fn(async () => ({
taskIds: overrides.subagentWakeups ?? [],
complete: true,
})),
discard: jest.fn(overrides.discard ?? (async () => 'not_pending')),
settleClaimed: jest.fn(async () => true),
}) as never;
function completedWithWakeup(userId: string, conversationId: string, toolCallId: string) {
const created = backgroundTaskRegistry.create({
userId,
conversationId,
toolCallId,
toolName: 'bash_tool',
messageId: `${toolCallId}-message`,
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
backgroundTaskRegistry.markCompletionWakeup(userId, conversationId, created.task.id, {
renew: jest.fn(async () => true),
retire: jest.fn(async () => true),
});
backgroundTaskRegistry.complete(userId, conversationId, created.task.id, {
content: 'finished output',
});
return created.task.id;
}
it('counts a finished task as outstanding until its result is delivered', async () => {
const taskId = completedWithWakeup('outstanding-user', 'outstanding-convo', 'outstanding-call');
const before = JSON.parse(
await runCheckBackgroundTask({
userId: 'outstanding-user',
conversationId: 'outstanding-convo',
args: {},
}),
);
expect(before.tasks[0]).toEqual(
expect.objectContaining({
background_task_id: taskId,
status: 'completed',
delivery: 'pending',
}),
);
expect(before.outstanding).toBe(1);
expect(before.message).toContain('have not been delivered yet');
expect(
backgroundTaskRegistry.claimResult('outstanding-user', 'outstanding-convo', taskId, {
kind: 'wakeup',
claimId: 'automatic-delivery',
}),
).toBe('acquired');
const after = JSON.parse(
await runCheckBackgroundTask({
userId: 'outstanding-user',
conversationId: 'outstanding-convo',
args: {},
}),
);
expect(after.tasks[0].delivery).toBe('delivered');
expect(after.outstanding).toBe(0);
expect(after.message).toBeUndefined();
});
it('counts running work as outstanding without claiming undelivered results', async () => {
const created = backgroundTaskRegistry.create({
userId: 'running-user',
conversationId: 'running-convo',
toolCallId: 'running-call',
toolName: 'bash_tool',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'running-user',
conversationId: 'running-convo',
args: {},
}),
);
expect(listed.tasks[0]).toEqual(expect.objectContaining({ status: 'running' }));
expect(listed.tasks[0].delivery).toBeUndefined();
expect(listed.outstanding).toBe(1);
expect(listed.message).toBeUndefined();
});
it('lists undelivered results the process-local registry no longer holds', async () => {
const localTaskId = completedWithWakeup('durable-user', 'durable-convo', 'durable-local');
const pendingCompletions = pendingControls({
list: async () => [
{
taskId: localTaskId,
toolCallId: `call-${localTaskId}`,
toolName: 'bash_tool',
dispatchedAt: new Date('2026-09-24T12:00:00Z'),
result: { status: 'completed', settledAt: new Date('2026-09-24T12:01:00Z') },
claimedByWakeup: false,
},
{
taskId: 'earlier-turn-task',
toolCallId: 'call-earlier-turn-task',
toolName: 'slow_task',
dispatchedAt: new Date('2026-09-24T11:00:00Z'),
result: { status: 'error', settledAt: new Date('2026-09-24T11:05:00Z') },
claimedByWakeup: false,
},
{
taskId: 'other-replica-task',
toolCallId: 'call-other-replica-task',
toolName: 'slow_task',
dispatchedAt: new Date('2026-09-24T11:30:00Z'),
claimedByWakeup: false,
},
],
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'durable-user',
conversationId: 'durable-convo',
args: {},
pendingCompletions,
}),
);
expect(
listed.tasks.map((task: { background_task_id: string }) => task.background_task_id),
).toEqual([localTaskId, 'earlier-turn-task', 'other-replica-task']);
expect(listed.tasks[1]).toEqual(
expect.objectContaining({
status: 'error',
delivery: 'pending',
started_at: '2026-09-24T11:00:00.000Z',
settled_at: '2026-09-24T11:05:00.000Z',
}),
);
expect(listed.tasks[2]).toEqual(
expect.objectContaining({ status: 'running', delivery: 'pending', progress: 0 }),
);
expect(listed.tasks[1].result).toBeUndefined();
expect(listed.outstanding).toBe(3);
});
it('keeps listing local work when the durable view is unavailable', async () => {
const taskId = completedWithWakeup('degraded-user', 'degraded-convo', 'degraded-call');
const pendingCompletions = pendingControls({
list: async () => {
throw new Error('delivery store unavailable');
},
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'degraded-user',
conversationId: 'degraded-convo',
args: {},
pendingCompletions,
}),
);
expect(
listed.tasks.map((task: { background_task_id: string }) => task.background_task_id),
).toEqual([taskId]);
expect(listed.partial).toBe(true);
expect(listed.warning).toContain('Undelivered results from earlier turns could not be listed');
});
it.each([
['discarded', 'cancelled', 'will not arrive as a new turn'],
['running', 'unavailable', 'cannot be stopped from here'],
['delivering', 'delivery_scheduled', 'already being delivered'],
])(
'reports a %s undelivered completion this process does not hold',
async (outcome, status, message) => {
const pendingCompletions = pendingControls({ discard: async () => outcome });
const cancelled = JSON.parse(
await runCheckBackgroundTask({
userId: 'discard-user',
conversationId: 'discard-convo',
args: { background_task_id: 'earlier-turn-task', action: 'cancel' },
pendingCompletions,
}),
);
expect(cancelled).toEqual(
expect.objectContaining({ status, background_task_id: 'earlier-turn-task' }),
);
expect(cancelled.message).toContain(message);
},
);
it('reports a local task delivered once the durable store no longer holds its delivery', async () => {
const delivered = completedWithWakeup('reconcile-user', 'reconcile-convo', 'reconcile-done');
const waiting = completedWithWakeup('reconcile-user', 'reconcile-convo', 'reconcile-waiting');
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'reconcile-user',
conversationId: 'reconcile-convo',
args: {},
pendingCompletions: pendingControls({
list: async () => [
{
taskId: waiting,
toolCallId: `call-${waiting}`,
toolName: 'bash_tool',
dispatchedAt: new Date('2026-09-24T12:00:00Z'),
result: { status: 'completed', settledAt: new Date('2026-09-24T12:01:00Z') },
claimedByWakeup: false,
},
],
}),
}),
);
const byId = new Map(
listed.tasks.map((task: { background_task_id: string; delivery?: string }) => [
task.background_task_id,
task.delivery,
]),
);
expect(byId.get(delivered)).toBe('delivered');
expect(byId.get(waiting)).toBe('pending');
expect(listed.outstanding).toBe(1);
});
it('reports a local task whose automatic delivery dead-lettered as failed, not delivered', async () => {
const taskId = completedWithWakeup('dead-user', 'dead-convo', 'dead-call');
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'dead-user',
conversationId: 'dead-convo',
args: {},
pendingCompletions: pendingControls({
dead: [
{
taskId,
toolCallId: `call-${taskId}`,
toolName: 'bash_tool',
dispatchedAt: new Date('2026-09-24T12:00:00Z'),
claimedByWakeup: false,
},
{
taskId: 'restored-dead-task',
toolCallId: 'call-restored-dead-task',
toolName: 'slow_task',
dispatchedAt: new Date('2026-09-24T11:00:00Z'),
result: { status: 'completed', settledAt: new Date('2026-09-24T11:01:00Z') },
claimedByWakeup: false,
},
],
}),
}),
);
expect(listed.tasks[0]).toEqual(
expect.objectContaining({ background_task_id: taskId, delivery: 'failed' }),
);
/** A dead letter this process no longer holds is listed from the durable store. */
expect(listed.tasks[1]).toEqual(
expect.objectContaining({
background_task_id: 'restored-dead-task',
status: 'completed',
delivery: 'failed',
}),
);
expect(listed.outstanding).toBe(2);
expect(listed.message).toContain('Automatic delivery failed');
});
it('retires the pending delivery when a local poll claims the durable result', async () => {
const created = backgroundTaskRegistry.create({
userId: 'local-claim-user',
conversationId: 'local-claim-convo',
toolCallId: 'local-claim-call',
toolName: 'bash_tool',
messageId: 'local-claim-message',
});
if ('atCapacity' in created) {
throw new Error('unexpected capacity');
}
const retire = jest.fn(async () => true);
backgroundTaskRegistry.markCompletionWakeup(
'local-claim-user',
'local-claim-convo',
created.task.id,
{
renew: jest.fn(async () => true),
retire,
},
);
backgroundTaskRegistry.complete('local-claim-user', 'local-claim-convo', created.task.id, {
content: 'finished output',
});
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'local-claim-user',
conversationId: 'local-claim-convo',
args: { background_task_id: created.task.id },
claimBackgroundToolResult: jest.fn(async () => ({
status: 'acquired' as const,
results: [],
})) as never,
}),
);
expect(polled.status).toBe('completed');
expect(retire).toHaveBeenCalledWith('completion claimed by manual poll', {
onlyIfUnclaimed: true,
});
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'local-claim-user',
conversationId: 'local-claim-convo',
args: {},
}),
);
expect(listed.tasks[0].delivery).toBe('delivered');
expect(listed.outstanding).toBe(0);
});
it('keeps the local view and warns when the durable listing is incomplete', async () => {
const taskId = completedWithWakeup('truncated-user', 'truncated-convo', 'truncated-call');
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'truncated-user',
conversationId: 'truncated-convo',
args: {},
pendingCompletions: pendingControls({ complete: false }),
}),
);
expect(listed.tasks[0]).toEqual(
expect.objectContaining({ background_task_id: taskId, delivery: 'pending' }),
);
expect(listed.outstanding).toBe(1);
expect(listed.partial).toBe(true);
expect(listed.warning).toContain('result list may be incomplete');
});
it('lets a finished local task be cancelled without the live-cancellation policy', async () => {
const taskId = completedWithWakeup(
'settled-cancel-user',
'settled-cancel-convo',
'settled-cancel',
);
const cancelled = JSON.parse(
await runCheckBackgroundTask({
userId: 'settled-cancel-user',
conversationId: 'settled-cancel-convo',
args: { background_task_id: taskId, action: 'cancel' },
}),
);
expect(cancelled.status).not.toBe('invalid');
expect(cancelled).toEqual(
expect.objectContaining({ background_task_id: taskId, status: 'completed' }),
);
});
it('retires the pending delivery of a remote task a manual poll just claimed', async () => {
const pendingCompletions = pendingControls();
const claimBackgroundToolResult = jest.fn(async () => ({
status: 'acquired' as const,
results: [
{
taskId: 'remote-task',
toolName: 'slow_task',
status: 'completed' as const,
output: 'remote result',
settledAt: new Date('2026-09-24T12:00:00Z'),
},
],
}));
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'remote-user',
conversationId: 'remote-convo',
args: { background_task_id: 'remote-task' },
claimBackgroundToolResult: claimBackgroundToolResult as never,
pendingCompletions,
}),
);
expect(polled).toEqual(
expect.objectContaining({ status: 'completed', result: 'remote result' }),
);
expect(
(pendingCompletions as unknown as { settleClaimed: jest.Mock }).settleClaimed,
).toHaveBeenCalledWith({
userId: 'remote-user',
conversationId: 'remote-convo',
taskId: 'remote-task',
});
});
it('reports a failed discard lookup only when nothing else claims the task', async () => {
const cancelled = JSON.parse(
await runCheckBackgroundTask({
userId: 'discard-user',
conversationId: 'discard-convo',
args: { background_task_id: 'unknown-task', action: 'cancel' },
pendingCompletions: pendingControls({
discard: async () => {
throw new Error('delivery store unavailable');
},
}),
}),
);
expect(cancelled).toEqual(expect.objectContaining({ status: 'unavailable' }));
expect(cancelled.message).toContain('could not be discarded right now');
});
it('falls through to the ordinary lookup when nothing is pending for the task', async () => {
const pendingCompletions = pendingControls({ discard: async () => 'not_pending' });
const cancelled = JSON.parse(
await runCheckBackgroundTask({
userId: 'discard-user',
conversationId: 'discard-convo',
args: { background_task_id: 'unknown-task', action: 'cancel' },
pendingCompletions,
}),
);
expect(cancelled).toEqual(expect.objectContaining({ status: 'not_found' }));
});
});
describe('runCheckBackgroundTask subagent activity', () => {
/** The host task store decorates claims and lists with the owner's progress tree;
* this store does the same over the SDK store so the poll path runs end to end. */
class ActivityTaskStore extends InMemorySubagentTaskStore {
readonly recorders = new Map<string, ActivityRecorder>();
override claim(scopeId: string, taskId: string): SubagentTaskClaim {
const claim = super.claim(scopeId, taskId);
const recorder = this.recorders.get(taskId);
if (claim.status === 'not_found' || recorder == null) {
return claim;
}
const task: ActivitySnapshot = { ...claim.task, activity: recorder.snapshot() };
return { ...claim, task };
}
override list(scopeId: string): SubagentTaskSnapshot[] {
return super.list(scopeId).map((task): ActivitySnapshot => {
const recorder = this.recorders.get(task.taskId);
return recorder == null ? task : { ...task, activitySummary: recorder.summary() };
});
}
}
const update = (phase: SubagentUpdateEvent['phase'], data: unknown): SubagentUpdateEvent => ({
runId: 'root-run',
subagentRunId: 'child-run',
subagentType: 'pr-reviewer',
subagentAgentId: 'agent-reviewer',
phase,
data,
timestamp: new Date().toISOString(),
});
const toolCall = (id: string, name: string, intent: string) =>
update('run_step', {
id: `step-${id}`,
stepDetails: {
type: 'tool_calls',
tool_calls: [{ id, name, args: { intent, secret: 'sk-1' } }],
},
});
const toolResult = (id: string, name: string, output: string) =>
update('run_step_completed', {
result: { type: 'tool_call', tool_call: { id, name, output } },
});
let reviewers = 0;
function startReviewer(release?: Promise<{ content: string }>) {
const store = new ActivityTaskStore();
const subagentTasks: HostSubagentTaskConfig = {
store,
scopeId: 'owner:digest-parent',
completionDelivery: SUBAGENT_COMPLETION_DELIVERY,
};
const recorder = new ActivityRecorder();
reviewers += 1;
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: `parent-run:parent-agent:reviewer-${reviewers}`,
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-reviewer',
input: 'Review the PR.',
subagentKind: 'agent',
subagentType: 'pr-reviewer',
run: (runtime: SubagentTaskRuntime) =>
release ??
new Promise((_, reject) => {
runtime.signal.addEventListener('abort', () => reject(runtime.signal.reason), {
once: true,
});
}),
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
store.recorders.set(started.task.taskId, recorder);
for (let index = 1; index <= 8; index++) {
const name = index % 2 === 1 ? 'bash_tool' : 'read_file';
recorder.record(toolCall(`call-${index}`, name, `Step ${index}`));
recorder.record(
toolResult(
`call-${index}`,
name,
index === 3 ? 'Error: tool call failed: exit 1' : 'API_KEY=leak',
),
);
}
recorder.record(toolCall('call-9', 'bash_tool', 'Running the jest suite'));
const poll = async (args: Record<string, unknown> = {}) =>
JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'digest-parent',
agentId: 'agent_parent',
args: { background_task_id: started.task.taskId, ...args },
subagentTasks,
}),
);
return { store, subagentTasks, recorder, taskId: started.task.taskId, poll };
}
const paths = (digest: { nodes: Array<{ path: string }> }): string[] =>
digest.nodes.map((node) => node.path);
it('returns a folded, navigable digest for a running subagent', async () => {
const { store, subagentTasks, taskId, poll, recorder } = startReviewer();
const polled = await poll();
expect(polled).toMatchObject({
status: 'running',
message: SUBAGENT_POLL_WAKEUP_GUIDANCE,
next_check_s: 30,
activity: { turns: 9, tools: 9, errors: 1, active: '9.1', cursor: '8.1' },
});
expect(polled.progress_detail).toBeUndefined();
expect(paths(polled.activity)).toEqual(['1-3', '4', '5', '6', '7', '8', '9', '9.1']);
expect(JSON.stringify(polled)).not.toContain('leak');
expect(JSON.stringify(polled)).not.toContain('sk-1');
const unchanged = await poll({ since: polled.activity.cursor });
expect(paths(unchanged.activity)).toEqual(['9', '9.1']);
recorder.record(toolResult('call-9', 'bash_tool', 'PASS'));
recorder.record(toolCall('call-10', 'read_file', 'Reading the diff'));
const advanced = await poll({ since: unchanged.activity.cursor });
expect(advanced.activity).toMatchObject({ since: '8.1', cursor: '9.1', active: '10.1' });
expect(paths(advanced.activity)).toEqual(['9', '9.1', '10', '10.1']);
const expanded = await poll({ expand: '1-3' });
expect(expanded.activity.expanded).toBe('1-3');
expect(expanded.activity.nodes).toEqual([
expect.objectContaining({ path: '1', summary: 'bash_tool' }),
expect.objectContaining({ path: '2', summary: 'read_file' }),
expect.objectContaining({ path: '3', status: 'error', errors: 1 }),
]);
const display = parseBackgroundTaskOutput(JSON.stringify(polled));
expect(display?.kind === 'task' ? display.task.activity?.nodes : undefined).toHaveLength(8);
store.control(subagentTasks.scopeId, taskId, { action: 'cancel' });
});
it('rejects malformed navigation without touching the task', async () => {
const { store, subagentTasks, taskId, poll } = startReviewer();
expect(await poll({ expand: 'turn three' })).toEqual({
status: 'invalid',
background_task_id: taskId,
message: expect.stringContaining('expand must be a node path'),
});
expect(await poll({ since: '1', expand: '2' })).toMatchObject({ status: 'invalid' });
expect(store.get(subagentTasks.scopeId, taskId)?.status).toBe('running');
store.control(subagentTasks.scopeId, taskId, { action: 'cancel' });
});
it('lists running subagents with counts and only the node in flight', async () => {
const { store, subagentTasks, taskId } = startReviewer();
const listed = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'digest-parent',
agentId: 'agent_parent',
args: {},
subagentTasks,
}),
);
expect(listed.tasks[0].activity).toEqual({
turns: 9,
tools: 9,
errors: 1,
active: '9.1',
nodes: [
expect.objectContaining({
path: '9.1',
name: 'bash_tool',
label: 'Running the jest suite',
status: 'running',
}),
],
});
expect(listed.message).toBe(SUBAGENT_WAKEUP_GUIDANCE);
store.control(subagentTasks.scopeId, taskId, { action: 'cancel' });
});
it('returns the result with its activity when a finished, undelivered task is polled', async () => {
let finish = (_value: { content: string }): void => undefined;
const release = new Promise<{ content: string }>((resolve) => (finish = resolve));
const { store, subagentTasks, taskId, poll, recorder } = startReviewer(release);
recorder.record(toolResult('call-9', 'bash_tool', 'PASS'));
recorder.settle('completed');
finish({ content: 'Two findings.' });
await waitForSubagentTaskToSettle(store, subagentTasks.scopeId, taskId);
const collected = await poll();
expect(collected).toMatchObject({
status: 'completed',
result: 'Two findings.',
activity: { turns: 9, tools: 9, errors: 1, cursor: '9.1' },
});
expect(collected.activity.active).toBeUndefined();
expect(collected.activity.idle_ms).toBeUndefined();
expect(collected.next_check_s).toBeUndefined();
expect(collected.message).toBeUndefined();
});
it('keeps the legacy progress label when the owner sends no activity', async () => {
const store = new InMemorySubagentTaskStore();
const subagentTasks: SubagentTaskConfig = { store, scopeId: 'owner:legacy-parent' };
const started = store.start({
scopeId: subagentTasks.scopeId,
idempotencyKey: 'parent-run:parent-agent:legacy',
parentRunId: 'parent-run',
parentAgentId: 'parent-agent',
parentToolCallId: 'call-legacy',
input: 'Research this.',
subagentKind: 'agent',
subagentType: 'researcher',
run: (runtime: SubagentTaskRuntime) => {
runtime.reportProgress(update('message_delta', { delta: { content: [] } }));
return new Promise((_, reject) => {
runtime.signal.addEventListener('abort', () => reject(runtime.signal.reason), {
once: true,
});
});
},
});
if (!started.accepted) {
throw new Error('Expected subagent task to start.');
}
await Promise.resolve();
const polled = JSON.parse(
await runCheckBackgroundTask({
userId: 'owner',
conversationId: 'legacy-parent',
args: { background_task_id: started.task.taskId, since: '3' },
subagentTasks,
}),
);
expect(polled.activity).toBeUndefined();
expect(polled.progress_detail).toMatchObject({ phase: 'message_delta' });
store.control(subagentTasks.scopeId, started.task.taskId, { action: 'cancel' });
});
});