Skip to content

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

🧵 feat: Background Tool Calls for Agents & Model Specs (#14197)

Danny Avila520af663bc94
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 9045e0055c..6c9eb0a0ff 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -335,6 +335,7 @@ const OpenAIChatCompletionController = async (req, res) => {
ephemeralSkillsToggle,
}),
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
@@ -415,6 +416,7 @@ const OpenAIChatCompletionController = async (req, res) => {
defaultActiveOnShare,
/** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
@@ -500,6 +502,7 @@ const OpenAIChatCompletionController = async (req, res) => {
agent: ctx.agent ?? agent,
signal: abortController.signal,
toolRegistry: ctx.toolRegistry,
+ backgroundToolNames: ctx.backgroundToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
index a0d40195c5..a9551ff66d 100644
--- a/api/server/controllers/agents/responses.js
+++ b/api/server/controllers/agents/responses.js
@@ -459,6 +459,7 @@ const createResponse = async (req, res) => {
ephemeralSkillsToggle,
}),
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
@@ -539,6 +540,7 @@ const createResponse = async (req, res) => {
defaultActiveOnShare,
/** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+ backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
@@ -720,6 +722,7 @@ const createResponse = async (req, res) => {
agent: ctx.agent ?? agent,
signal: abortController.signal,
toolRegistry: ctx.toolRegistry,
+ backgroundToolNames: ctx.backgroundToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
@@ -900,6 +903,7 @@ const createResponse = async (req, res) => {
agent: ctx.agent ?? agent,
signal: abortController.signal,
toolRegistry: ctx.toolRegistry,
+ backgroundToolNames: ctx.backgroundToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
diff --git a/api/server/services/Endpoints/agents/addedConvo.js b/api/server/services/Endpoints/agents/addedConvo.js
index 91ea170d34..09fad7a67f 100644
--- a/api/server/services/Endpoints/agents/addedConvo.js
+++ b/api/server/services/Endpoints/agents/addedConvo.js
@@ -81,6 +81,7 @@ const processAddedConvo = async ({
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
}) => {
@@ -177,6 +178,7 @@ const processAddedConvo = async ({
ephemeralSkillsToggle,
}),
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
skillStates,
diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js
index 2a7e026486..d94f48d6f6 100644
--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@@ -149,6 +149,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities);
const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
const codeEnvAvailable = enabledCapabilities.has(AgentCapabilities.execute_code);
+ const backgroundToolsAvailable = enabledCapabilities.has(AgentCapabilities.run_in_background);
const statefulSessionsAvailable = enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
);
@@ -230,6 +231,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
toolNames,
agent: ctx.agent,
toolRegistry: ctx.toolRegistry,
+ backgroundToolNames: ctx.backgroundToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
@@ -408,6 +410,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
accessibleSkillIds: primaryScopedSkillIds,
skillAuthoringAvailable: primarySkillAuthoringAvailable,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
skillStates,
@@ -485,6 +488,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
},
@@ -558,6 +562,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
});
@@ -698,6 +703,11 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
* false`, so `bash_tool` / `read_file` sandbox fallback are
* silently gated off even though the seed walk found it. */
codeEnvAvailable,
+ /* Background tool calls are intentionally NOT enabled for pure
+ * subagents (spawn-tool child graphs): their tools don't reach the
+ * host ON_TOOL_EXECUTE background interceptor, so injecting the
+ * schema would advertise a poll tool the host can't honor. Backgrounding
+ * subagent work is the durable follow-up. */
statefulSessionsAvailable,
memoryAvailable,
skillStates,
diff --git a/api/server/services/Endpoints/agents/skillDeps.js b/api/server/services/Endpoints/agents/skillDeps.js
index 7154c1d52b..8a9098551c 100644
--- a/api/server/services/Endpoints/agents/skillDeps.js
+++ b/api/server/services/Endpoints/agents/skillDeps.js
@@ -278,6 +278,7 @@ function buildAgentToolContext({ agent, config }) {
* the producing agent's config in multi-endpoint graphs. */
endpointTokenConfig: config.endpointTokenConfig,
toolRegistry: config.toolRegistry,
+ backgroundToolNames: config.backgroundToolNames,
mcpAvailableTools: config.mcpAvailableTools,
requestScopedConnections: config.requestScopedConnections,
userMCPAuthMap: config.userMCPAuthMap,
diff --git a/api/server/services/MCP.js b/api/server/services/MCP.js
index 46971a416e..f6fc35f1ed 100644
--- a/api/server/services/MCP.js
+++ b/api/server/services/MCP.js
@@ -887,6 +887,14 @@ function createToolInstance({
});
toolInstance.mcp = true;
toolInstance.mcpRawServerName = serverName;
+ // Ephemeral request-scoped servers (runtime body placeholders) tear their
+ // connection down at request end, so they must never be backgrounded. A
+ // missing/stale config means the server's lifetime is unknowable, so fail
+ // closed (foreground) rather than risk a detached call against a torn-down
+ // connection.
+ toolInstance.mcpRequiresEphemeralConnection = capturedServerConfig
+ ? requiresEphemeralUserConnection(capturedServerConfig)
+ : true;
// On Google/Vertex, propagate the union-flattened schema so definitions extracted
// from this instance don't reach the Gemini converter with unsupported unions.
toolInstance.mcpJsonSchema = isGoogle ? schema : parameters;
diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.js
index ffc0993d1e..be67b60fa7 100644
--- a/api/server/services/ToolService.js
+++ b/api/server/services/ToolService.js
@@ -1450,6 +1450,7 @@ async function loadToolsForExecution({
agent,
toolNames,
toolRegistry,
+ backgroundToolNames,
mcpAvailableTools,
requestScopedConnections,
userMCPAuthMap,
@@ -1461,6 +1462,12 @@ async function loadToolsForExecution({
const allLoadedTools = [];
const mcpRequestScopedConnections = requestScopedConnections ?? getMCPRequestContext(req, res);
const configurable = { userMCPAuthMap, requestScopedConnections: mcpRequestScopedConnections };
+ /** Per-agent set of tools that received the injected `run_in_background`
+ * param; the event-driven executor gates background dispatch and the
+ * `check_background_task` poll tool on this reliable per-agent channel. */
+ if (backgroundToolNames?.length) {
+ configurable.backgroundToolNames = backgroundToolNames;
+ }
const isToolSearch = toolNames.includes(AgentConstants.TOOL_SEARCH);
const ptcToolNames = [
diff --git a/client/src/components/SidePanel/Agents/MCPToolItem.tsx b/client/src/components/SidePanel/Agents/MCPToolItem.tsx
index d3a4930839..b82fc11797 100644
--- a/client/src/components/SidePanel/Agents/MCPToolItem.tsx
+++ b/client/src/components/SidePanel/Agents/MCPToolItem.tsx
@@ -1,7 +1,7 @@
import { useState } from 'react';
-import { TooltipAnchor } from '@librechat/client';
-import { Check, Clock, Code2, Info } from 'lucide-react';
+import { Check, Clock, Code2, Info, Zap } from 'lucide-react';
import type { AgentToolType } from 'librechat-data-provider';
+import OptionToggle from './OptionToggle';
import { useLocalize } from '~/hooks';
import { cn } from '~/utils';
@@ -10,11 +10,14 @@ interface MCPToolItemProps {
isSelected: boolean;
isDeferred: boolean;
isProgrammatic: boolean;
+ isBackground: boolean;
deferredToolsEnabled: boolean;
programmaticToolsEnabled: boolean;
+ backgroundToolsEnabled: boolean;
onToggleSelect: () => void;
onToggleDefer: () => void;
onToggleProgrammatic: () => void;
+ onToggleBackground: () => void;
}
const iconButton =
@@ -28,8 +31,11 @@ export default function MCPToolItem({
onToggleSelect,
isProgrammatic,
onToggleProgrammatic,
+ isBackground,
+ onToggleBackground,
deferredToolsEnabled,
programmaticToolsEnabled,
+ backgroundToolsEnabled,
}: MCPToolItemProps) {
const localize = useLocalize();
const [expanded, setExpanded] = useState(false);
@@ -65,45 +71,33 @@ export default function MCPToolItem({
</button>
<div className="flex shrink-0 items-center gap-0.5">
{deferredToolsEnabled && (
- <TooltipAnchor
- description={localize('com_ui_mcp_click_to_defer')}
- side="top"
- render={
- <button
- type="button"
- onClick={onToggleDefer}
- aria-pressed={isDeferred}
- aria-label={localize('com_ui_mcp_defer_loading')}
- className={cn(
- iconButton,
- isDeferred ? 'text-amber-500' : 'text-text-secondary hover:text-text-primary',
- )}
- >
- <Clock className="size-4" aria-hidden="true" />
- </button>
- }
+ <OptionToggle
+ icon={Clock}
+ pressed={isDeferred}
+ label={localize('com_ui_mcp_defer_loading')}
+ tooltip={localize('com_ui_mcp_click_to_defer')}
+ activeClass="text-amber-500"
+ onToggle={onToggleDefer}
/>
)}
{programmaticToolsEnabled && (
- <TooltipAnchor
- description={localize('com_ui_mcp_click_to_programmatic')}
- side="top"
- render={
- <button
- type="button"
- onClick={onToggleProgrammatic}
- aria-pressed={isProgrammatic}
- aria-label={localize('com_ui_mcp_programmatic')}
- className={cn(
- iconButton,
- isProgrammatic
- ? 'text-violet-500'
- : 'text-text-secondary hover:text-text-primary',
- )}
- >
- <Code2 className="size-4" aria-hidden="true" />
- </button>
- }
+ <OptionToggle
+ icon={Code2}
+ pressed={isProgrammatic}
+ label={localize('com_ui_mcp_programmatic')}
+ tooltip={localize('com_ui_mcp_click_to_programmatic')}
+ activeClass="text-violet-500"
+ onToggle={onToggleProgrammatic}
+ />
+ )}
+ {backgroundToolsEnabled && (
+ <OptionToggle
+ icon={Zap}
+ pressed={isBackground}
+ label={localize('com_ui_mcp_background')}
+ tooltip={localize('com_ui_mcp_click_to_background')}
+ activeClass="text-sky-500"
+ onToggle={onToggleBackground}
/>
)}
<button
diff --git a/client/src/components/SidePanel/Agents/OptionToggle.tsx b/client/src/components/SidePanel/Agents/OptionToggle.tsx
new file mode 100644
index 0000000000..6f71eb80a9
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/OptionToggle.tsx
@@ -0,0 +1,51 @@
+import { TooltipAnchor } from '@librechat/client';
+import type { LucideIcon } from 'lucide-react';
+import { cn } from '~/utils';
+
+interface OptionToggleProps {
+ icon: LucideIcon;
+ pressed: boolean;
+ label: string;
+ /** Defaults to `label` (bulk toggles use the same text for both). */
+ tooltip?: string;
+ /** Text color applied when pressed (e.g. `text-amber-500`). */
+ activeClass: string;
+ onToggle: () => void;
+ size?: 'sm' | 'md';
+}
+
+/**
+ * Icon toggle for a per-tool option (defer / programmatic / background), shared
+ * between the per-tool row (`sm`) and the section-header bulk action (`md`).
+ */
+export default function OptionToggle({
+ icon: Icon,
+ pressed,
+ label,
+ tooltip,
+ activeClass,
+ onToggle,
+ size = 'sm',
+}: OptionToggleProps) {
+ return (
+ <TooltipAnchor
+ description={tooltip ?? label}
+ side="top"
+ render={
+ <button
+ type="button"
+ onClick={onToggle}
+ aria-pressed={pressed}
+ aria-label={label}
+ className={cn(
+ 'flex items-center justify-center rounded-md transition-colors hover:bg-surface-hover focus:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary',
+ size === 'sm' ? 'size-6' : 'size-7',
+ pressed ? activeClass : 'text-text-secondary hover:text-text-primary',
+ )}
+ >
+ <Icon className="size-4" aria-hidden="true" />
+ </button>
+ }
+ />
+ );
+}
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/McpSection.spec.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/McpSection.spec.tsx
index 0cd6fd2aca..22d528e12b 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/McpSection.spec.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/McpSection.spec.tsx
@@ -44,12 +44,16 @@ jest.mock('~/hooks', () => ({
useMCPToolOptions: () => ({
isToolDeferred: () => false,
isToolProgrammatic: () => false,
+ isToolBackground: () => false,
toggleToolDefer: jest.fn(),
toggleToolProgrammatic: jest.fn(),
+ toggleToolBackground: jest.fn(),
areAllToolsDeferred: () => false,
areAllToolsProgrammatic: () => false,
+ areAllToolsBackground: () => false,
toggleDeferAll: jest.fn(),
toggleProgrammaticAll: jest.fn(),
+ toggleBackgroundAll: jest.fn(),
}),
}));
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/McpSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/McpSection.tsx
index 3009662b61..a56fc5fb0f 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/McpSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/McpSection.tsx
@@ -1,7 +1,7 @@
import { useState, useMemo, useEffect, useCallback } from 'react';
-import { Clock, Code2 } from 'lucide-react';
+import { Clock, Code2, Zap } from 'lucide-react';
import { useFormContext, useWatch } from 'react-hook-form';
-import { Button, Spinner, Checkbox, Skeleton, TooltipAnchor } from '@librechat/client';
+import { Button, Spinner, Checkbox, Skeleton } from '@librechat/client';
import type { MouseEvent } from 'react';
import type { TranslationKeys } from '~/hooks/useLocalize';
import type { McpItem } from '../../items/types';
@@ -18,6 +18,7 @@ import MCPConfigDialog from '~/components/MCP/MCPConfigDialog';
import McpOAuthDialog from '~/components/MCP/McpOAuthDialog';
import { useAgentPanelContext } from '~/Providers';
import { getIconForItem } from '../../items/icons';
+import OptionToggle from '../../../OptionToggle';
import MCPToolItem from '../../../MCPToolItem';
import { Collapse } from '~/components/ui';
import { useLocalize } from '~/hooks';
@@ -75,18 +76,21 @@ export default function McpSection({ item }: Props) {
const [autoSelectPending, setAutoSelectPending] = useState(false);
const { mcpServersMap, mcpToolsLoading } = useAgentPanelContext();
const { agentsConfig } = useGetAgentsConfig();
- const { deferredToolsEnabled, programmaticToolsEnabled } = useAgentCapabilities(
- agentsConfig?.capabilities,
- );
+ const { deferredToolsEnabled, programmaticToolsEnabled, backgroundToolsEnabled } =
+ useAgentCapabilities(agentsConfig?.capabilities);
const {
isToolDeferred,
isToolProgrammatic,
+ isToolBackground,
toggleToolDefer,
toggleToolProgrammatic,
+ toggleToolBackground,
areAllToolsDeferred,
areAllToolsProgrammatic,
+ areAllToolsBackground,
toggleDeferAll,
toggleProgrammaticAll,
+ toggleBackgroundAll,
} = useMCPToolOptions();
const serverName = item.server.serverName;
@@ -149,6 +153,7 @@ export default function McpSection({ item }: Props) {
const allSelected = hasTools && selectedTools.length === tools.length;
const allDeferred = areAllToolsDeferred(tools);
const allProgrammatic = areAllToolsProgrammatic(tools);
+ const allBackground = areAllToolsBackground(tools);
const statusIconProps = getServerStatusIconProps(serverName);
const configDialogProps = getConfigDialogProps();
const connectionState = statusIconProps?.serverStatus?.connectionState;
@@ -246,7 +251,9 @@ export default function McpSection({ item }: Props) {
return (
<div className="flex flex-col gap-5">
{item.description && (
- <p className="text-sm leading-relaxed text-text-secondary">{item.description}</p>
+ <p className="max-h-40 overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed text-text-secondary">
+ {item.description}
+ </p>
)}
<div className="flex flex-col">
@@ -297,68 +304,42 @@ export default function McpSection({ item }: Props) {
{hasTools && (
<div className="flex items-center gap-0.5">
{deferredToolsEnabled && (
- <TooltipAnchor
- description={
- allDeferred
- ? localize('com_ui_mcp_undefer_all')
- : localize('com_ui_mcp_defer_all')
- }
- side="top"
- render={
- <button
- type="button"
- onClick={() => toggleDeferAll(tools)}
- aria-pressed={allDeferred}
- aria-label={
- allDeferred
- ? localize('com_ui_mcp_undefer_all')
- : localize('com_ui_mcp_defer_all')
- }
- className={cn(
- 'flex size-7 items-center justify-center rounded-md transition-colors',
- 'hover:bg-surface-hover focus:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary',
- allDeferred
- ? 'text-amber-600 dark:text-amber-500'
- : 'text-text-secondary hover:text-text-primary',
- )}
- >
- <Clock className="size-4" aria-hidden="true" />
- </button>
- }
+ <OptionToggle
+ icon={Clock}
+ size="md"
+ pressed={allDeferred}
+ label={localize(allDeferred ? 'com_ui_mcp_undefer_all' : 'com_ui_mcp_defer_all')}
+ activeClass="text-amber-600 dark:text-amber-500"
+ onToggle={() => toggleDeferAll(tools)}
/>
)}
{programmaticToolsEnabled && (
- <TooltipAnchor
- description={
+ <OptionToggle
+ icon={Code2}
+ size="md"
+ pressed={allProgrammatic}
+ label={localize(
allProgrammatic
- ? localize('com_ui_mcp_unprogrammatic_all')
- : localize('com_ui_mcp_programmatic_all')
- }
- side="top"
- render={
- <button
- type="button"
- onClick={() => toggleProgrammaticAll(tools)}
- aria-pressed={allProgrammatic}
- aria-label={
- allProgrammatic
- ? localize('com_ui_mcp_unprogrammatic_all')
- : localize('com_ui_mcp_programmatic_all')
- }
- className={cn(
- 'flex size-7 items-center justify-center rounded-md transition-colors',
- 'hover:bg-surface-hover focus:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary',
- allProgrammatic
- ? 'text-violet-600 dark:text-violet-500'
- : 'text-text-secondary hover:text-text-primary',
- )}
- >
- <Code2 className="size-4" aria-hidden="true" />
- </button>
- }
+ ? 'com_ui_mcp_unprogrammatic_all'
+ : 'com_ui_mcp_programmatic_all',
+ )}
+ activeClass="text-violet-600 dark:text-violet-500"
+ onToggle={() => toggleProgrammaticAll(tools)}
+ />
+ )}
+ {backgroundToolsEnabled && (
+ <OptionToggle
+ icon={Zap}
+ size="md"
+ pressed={allBackground}
+ label={localize(
+ allBackground ? 'com_ui_mcp_unbackground_all' : 'com_ui_mcp_background_all',
+ )}
+ activeClass="text-sky-600 dark:text-sky-500"
+ onToggle={() => toggleBackgroundAll(tools)}
/>
)}
- {(deferredToolsEnabled || programmaticToolsEnabled) && (
+ {(deferredToolsEnabled || programmaticToolsEnabled || backgroundToolsEnabled) && (
<span className="mx-1 h-4 w-px bg-border-light" aria-hidden="true" />
)}
<label className="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 text-xs text-text-secondary">
@@ -394,11 +375,14 @@ export default function McpSection({ item }: Props) {
isSelected={selectedTools.includes(tool.tool_id)}
isDeferred={deferredToolsEnabled && isToolDeferred(tool.tool_id)}
isProgrammatic={programmaticToolsEnabled && isToolProgrammatic(tool.tool_id)}
+ isBackground={backgroundToolsEnabled && isToolBackground(tool.tool_id)}
deferredToolsEnabled={deferredToolsEnabled}
programmaticToolsEnabled={programmaticToolsEnabled}
+ backgroundToolsEnabled={backgroundToolsEnabled}
onToggleSelect={() => toggleToolSelect(tool.tool_id)}
onToggleDefer={() => toggleToolDefer(tool.tool_id)}
onToggleProgrammatic={() => toggleToolProgrammatic(tool.tool_id)}
+ onToggleBackground={() => toggleToolBackground(tool.tool_id)}
/>
))}
</div>
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/SkillSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/SkillSection.tsx
index ee064f4c35..7606691624 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/SkillSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/SkillSection.tsx
@@ -10,7 +10,9 @@ export default function SkillSection({ item }: Props) {
return (
<div className="flex flex-col gap-5">
{item.description ? (
- <p className="text-sm leading-relaxed text-text-secondary">{item.description}</p>
+ <p className="max-h-40 overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed text-text-secondary">
+ {item.description}
+ </p>
) : (
<p className="text-sm italic text-text-tertiary">
{localize('com_ui_tools_no_description')}
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx
index c4e974ffa7..31616ec472 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx
@@ -62,7 +62,9 @@ export default function ToolSection({ item }: Props) {
return (
<div className="flex flex-col gap-5">
{item.description ? (
- <p className="text-sm leading-relaxed text-text-secondary">{item.description}</p>
+ <p className="max-h-40 overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed text-text-secondary">
+ {item.description}
+ </p>
) : (
<p className="text-sm italic text-text-tertiary">
{localize('com_ui_tools_no_description')}
diff --git a/client/src/components/SidePanel/Agents/__tests__/MCPToolItem.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/MCPToolItem.spec.tsx
index 6b6c131a4e..b18a3621ec 100644
--- a/client/src/components/SidePanel/Agents/__tests__/MCPToolItem.spec.tsx
+++ b/client/src/components/SidePanel/Agents/__tests__/MCPToolItem.spec.tsx
@@ -22,11 +22,14 @@ function setup(overrides: Partial<React.ComponentProps<typeof MCPToolItem>> = {}
isSelected: false,
isDeferred: false,
isProgrammatic: false,
+ isBackground: false,
deferredToolsEnabled: false,
programmaticToolsEnabled: false,
+ backgroundToolsEnabled: false,
onToggleSelect: jest.fn(),
onToggleDefer: jest.fn(),
onToggleProgrammatic: jest.fn(),
+ onToggleBackground: jest.fn(),
...overrides,
};
render(<MCPToolItem {...props} />);
@@ -91,4 +94,16 @@ describe('MCPToolItem', () => {
fireEvent.click(programmaticButton);
expect(props.onToggleProgrammatic).toHaveBeenCalledTimes(1);
});
+
+ test('background is an inline button rendered only when enabled', () => {
+ const props = setup({ backgroundToolsEnabled: true });
+ const backgroundButton = screen.getByRole('button', { name: 'com_ui_mcp_background' });
+ fireEvent.click(backgroundButton);
+ expect(props.onToggleBackground).toHaveBeenCalledTimes(1);
+ });
+
+ test('background button is absent when background tools are disabled', () => {
+ setup();
+ expect(screen.queryByRole('button', { name: 'com_ui_mcp_background' })).not.toBeInTheDocument();
+ });
});
diff --git a/client/src/hooks/Agents/useAgentCapabilities.ts b/client/src/hooks/Agents/useAgentCapabilities.ts
index 431fc1358d..077a443fec 100644
--- a/client/src/hooks/Agents/useAgentCapabilities.ts
+++ b/client/src/hooks/Agents/useAgentCapabilities.ts
@@ -14,6 +14,7 @@ interface AgentCapabilitiesResult {
memoryEnabled: boolean;
deferredToolsEnabled: boolean;
programmaticToolsEnabled: boolean;
+ backgroundToolsEnabled: boolean;
}
export default function useAgentCapabilities(
@@ -79,6 +80,11 @@ export default function useAgentCapabilities(
[capabilities],
);
+ const backgroundToolsEnabled = useMemo(
+ () => capabilities?.includes(AgentCapabilities.run_in_background) ?? false,
+ [capabilities],
+ );
+
return {
ocrEnabled,
codeEnabled,
@@ -92,5 +98,6 @@ export default function useAgentCapabilities(
fileSearchEnabled,
deferredToolsEnabled,
programmaticToolsEnabled,
+ backgroundToolsEnabled,
};
}
diff --git a/client/src/hooks/Agents/useMCPToolOptions.ts b/client/src/hooks/Agents/useMCPToolOptions.ts
index 68cfb8f91b..d0a260b7f1 100644
--- a/client/src/hooks/Agents/useMCPToolOptions.ts
+++ b/client/src/hooks/Agents/useMCPToolOptions.ts
@@ -1,60 +1,127 @@
import { useCallback } from 'react';
import { useFormContext, useWatch } from 'react-hook-form';
import type { AgentToolOptions, AllowedCaller, AgentToolType } from 'librechat-data-provider';
+import type { UseFormGetValues, UseFormSetValue } from 'react-hook-form';
import type { AgentForm } from '~/common';
+type BooleanToolOptionKey = 'defer_loading' | 'run_in_background';
+
+interface BooleanOptionHandlers {
+ isSet: (toolId: string) => boolean;
+ toggle: (toolId: string) => void;
+ areAllSet: (tools: AgentToolType[]) => boolean;
+ toggleAll: (tools: AgentToolType[]) => void;
+}
+
+interface ToolOptionsFormContext {
+ formToolOptions: AgentToolOptions | undefined;
+ getValues: UseFormGetValues<AgentForm>;
+ setValue: UseFormSetValue<AgentForm>;
+}
+
interface UseMCPToolOptionsReturn {
formToolOptions: AgentToolOptions | undefined;
isToolDeferred: (toolId: string) => boolean;
isToolProgrammatic: (toolId: string) => boolean;
+ isToolBackground: (toolId: string) => boolean;
toggleToolDefer: (toolId: string) => void;
toggleToolProgrammatic: (toolId: string) => void;
+ toggleToolBackground: (toolId: string) => void;
areAllToolsDeferred: (tools: AgentToolType[]) => boolean;
areAllToolsProgrammatic: (tools: AgentToolType[]) => boolean;
+ areAllToolsBackground: (tools: AgentToolType[]) => boolean;
toggleDeferAll: (tools: AgentToolType[]) => void;
toggleProgrammaticAll: (tools: AgentToolType[]) => void;
+ toggleBackgroundAll: (tools: AgentToolType[]) => void;
}
-export default function useMCPToolOptions(): UseMCPToolOptionsReturn {
- const { getValues, setValue, control } = useFormContext<AgentForm>();
- const formToolOptions = useWatch({ control, name: 'tool_options' });
-
- const isToolDeferred = useCallback(
- (toolId: string): boolean => formToolOptions?.[toolId]?.defer_loading === true,
- [formToolOptions],
- );
+/**
+ * Sets or clears a boolean flag on one tool's options without mutating the
+ * previous objects (react-hook-form still holds them); dropping the last flag
+ * removes the tool's entry entirely.
+ */
+function withBooleanOption(
+ options: AgentToolOptions,
+ toolId: string,
+ key: BooleanToolOptionKey,
+ set: boolean,
+): AgentToolOptions {
+ const updatedOptions: AgentToolOptions = { ...options };
+ const currentToolOptions = updatedOptions[toolId];
+ if (set) {
+ updatedOptions[toolId] = { ...currentToolOptions, [key]: true };
+ return updatedOptions;
+ }
+ if (!currentToolOptions) {
+ return updatedOptions;
+ }
+ const { [key]: _omit, ...restOptions } = currentToolOptions;
+ if (Object.keys(restOptions).length === 0) {
+ delete updatedOptions[toolId];
+ } else {
+ updatedOptions[toolId] = restOptions;
+ }
+ return updatedOptions;
+}
- const isToolProgrammatic = useCallback(
- (toolId: string): boolean =>
- formToolOptions?.[toolId]?.allowed_callers?.includes('code_execution') === true,
- [formToolOptions],
+/** Read/toggle handlers for one boolean per-tool option key (single + bulk). */
+function useBooleanToolOption(
+ key: BooleanToolOptionKey,
+ { formToolOptions, getValues, setValue }: ToolOptionsFormContext,
+): BooleanOptionHandlers {
+ const isSet = useCallback(
+ (toolId: string): boolean => formToolOptions?.[toolId]?.[key] === true,
+ [formToolOptions, key],
);
- const toggleToolDefer = useCallback(
+ const toggle = useCallback(
(toolId: string) => {
const currentOptions = getValues('tool_options') || {};
- const currentToolOptions = currentOptions[toolId] || {};
- const newDeferred = !currentToolOptions.defer_loading;
+ const set = currentOptions[toolId]?.[key] !== true;
+ setValue('tool_options', withBooleanOption(currentOptions, toolId, key, set), {
+ shouldDirty: true,
+ });
+ },
+ [getValues, setValue, key],
+ );
- const updatedOptions: AgentToolOptions = { ...currentOptions };
+ const areAllSet = useCallback(
+ (tools: AgentToolType[]): boolean =>
+ tools.length > 0 && tools.every((tool) => formToolOptions?.[tool.tool_id]?.[key] === true),
+ [formToolOptions, key],
+ );
- if (newDeferred) {
- updatedOptions[toolId] = {
- ...currentToolOptions,
- defer_loading: true,
- };
- } else {
- const { defer_loading: _, ...restOptions } = currentToolOptions;
- if (Object.keys(restOptions).length === 0) {
- delete updatedOptions[toolId];
- } else {
- updatedOptions[toolId] = restOptions;
- }
+ const toggleAll = useCallback(
+ (tools: AgentToolType[]) => {
+ if (tools.length === 0) {
+ return;
+ }
+ const set = !areAllSet(tools);
+ let updatedOptions = getValues('tool_options') || {};
+ for (const tool of tools) {
+ updatedOptions = withBooleanOption(updatedOptions, tool.tool_id, key, set);
}
-
setValue('tool_options', updatedOptions, { shouldDirty: true });
},
- [getValues, setValue],
+ [areAllSet, getValues, setValue, key],
+ );
+
+ return { isSet, toggle, areAllSet, toggleAll };
+}
+
+export default function useMCPToolOptions(): UseMCPToolOptionsReturn {
+ const { getValues, setValue, control } = useFormContext<AgentForm>();
+ const formToolOptions = useWatch({ control, name: 'tool_options' });
+ const formContext: ToolOptionsFormContext = { formToolOptions, getValues, setValue };
+
+ const defer = useBooleanToolOption('defer_loading', formContext);
+ const background = useBooleanToolOption('run_in_background', formContext);
+
+ /** `allowed_callers` is array-valued, so the programmatic family stays bespoke. */
+ const isToolProgrammatic = useCallback(
+ (toolId: string): boolean =>
+ formToolOptions?.[toolId]?.allowed_callers?.includes('code_execution') === true,
+ [formToolOptions],
);
const toggleToolProgrammatic = useCallback(
@@ -93,13 +160,6 @@ export default function useMCPToolOptions(): UseMCPToolOptionsReturn {
[getValues, setValue],
);
- const areAllToolsDeferred = useCallback(
- (tools: AgentToolType[]): boolean =>
- tools.length > 0 &&
- tools.every((tool) => formToolOptions?.[tool.tool_id]?.defer_loading === true),
- [formToolOptions],
- );
-
const areAllToolsProgrammatic = useCallback(
(tools: AgentToolType[]): boolean =>
tools.length > 0 &&
@@ -110,57 +170,33 @@ export default function useMCPToolOptions(): UseMCPToolOptionsReturn {
[formToolOptions],
);
- const toggleDeferAll = useCallback(
- (tools: AgentToolType[]) => {
- if (tools.length === 0) return;
-
- const shouldDefer = !areAllToolsDeferred(tools);
- const currentOptions = getValues('tool_options') || {};
- const updatedOptions: AgentToolOptions = { ...currentOptions };
-
- for (const tool of tools) {
- if (shouldDefer) {
- updatedOptions[tool.tool_id] = {
- ...(updatedOptions[tool.tool_id] || {}),
- defer_loading: true,
- };
- } else {
- if (updatedOptions[tool.tool_id]) {
- delete updatedOptions[tool.tool_id].defer_loading;
- if (Object.keys(updatedOptions[tool.tool_id]).length === 0) {
- delete updatedOptions[tool.tool_id];
- }
- }
- }
- }
-
- setValue('tool_options', updatedOptions, { shouldDirty: true });
- },
- [getValues, setValue, areAllToolsDeferred],
- );
-
const toggleProgrammaticAll = useCallback(
(tools: AgentToolType[]) => {
- if (tools.length === 0) return;
+ if (tools.length === 0) {
+ return;
+ }
const shouldBeProgrammatic = !areAllToolsProgrammatic(tools);
const currentOptions = getValues('tool_options') || {};
const updatedOptions: AgentToolOptions = { ...currentOptions };
for (const tool of tools) {
- const currentToolOptions = updatedOptions[tool.tool_id] || {};
+ const currentToolOptions = updatedOptions[tool.tool_id];
if (shouldBeProgrammatic) {
updatedOptions[tool.tool_id] = {
...currentToolOptions,
allowed_callers: ['code_execution'] as AllowedCaller[],
};
+ continue;
+ }
+ if (!currentToolOptions) {
+ continue;
+ }
+ const { allowed_callers: _, ...restOptions } = currentToolOptions;
+ if (Object.keys(restOptions).length === 0) {
+ delete updatedOptions[tool.tool_id];
} else {
- if (updatedOptions[tool.tool_id]) {
- delete updatedOptions[tool.tool_id].allowed_callers;
- if (Object.keys(updatedOptions[tool.tool_id]).length === 0) {
- delete updatedOptions[tool.tool_id];
- }
- }
+ updatedOptions[tool.tool_id] = restOptions;
}
}
@@ -171,13 +207,17 @@ export default function useMCPToolOptions(): UseMCPToolOptionsReturn {
return {
formToolOptions,
- isToolDeferred,
+ isToolDeferred: defer.isSet,
isToolProgrammatic,
- toggleToolDefer,
+ isToolBackground: background.isSet,
+ toggleToolDefer: defer.toggle,
toggleToolProgrammatic,
- areAllToolsDeferred,
+ toggleToolBackground: background.toggle,
+ areAllToolsDeferred: defer.areAllSet,
areAllToolsProgrammatic,
- toggleDeferAll,
+ areAllToolsBackground: background.areAllSet,
+ toggleDeferAll: defer.toggleAll,
toggleProgrammaticAll,
+ toggleBackgroundAll: background.toggleAll,
};
}
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index e549e63ccb..ca7d59afb5 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1321,6 +1321,9 @@
"com_ui_max_file_size": "PNG, JPG or JPEG (max {{0}})",
"com_ui_max_tags": "Maximum number allowed is {{0}}, using latest values.",
"com_ui_mcp_authenticated_success": "MCP server '{{0}}' authenticated successfully",
+ "com_ui_mcp_background": "Background",
+ "com_ui_mcp_background_all": "Mark all as background",
+ "com_ui_mcp_click_to_background": "Runs this tool in the background: it returns immediately and the agent polls for the result, so it can keep working while the tool runs.",
"com_ui_mcp_click_to_defer": "Loads this tool only when the agent needs it instead of keeping it active the whole time. Useful when a server has many tools.",
"com_ui_mcp_click_to_programmatic": "The agent calls this tool by writing code, not as a direct tool call. Best for tools meant to run in code.",
"com_ui_mcp_defer": "Defer",
@@ -1365,6 +1368,7 @@
"com_ui_mcp_transport": "Transport",
"com_ui_mcp_type_sse": "SSE",
"com_ui_mcp_type_streamable_http": "Streamable HTTPS",
+ "com_ui_mcp_unbackground_all": "Unmark all as background",
"com_ui_mcp_undefer": "Undefer",
"com_ui_mcp_undefer_all": "Undefer all tools",
"com_ui_mcp_unprogrammatic_all": "Unmark all as programmatic",
diff --git a/e2e/config/librechat.e2e.yaml b/e2e/config/librechat.e2e.yaml
index 96f10bb479..4edeca9c0a 100644
--- a/e2e/config/librechat.e2e.yaml
+++ b/e2e/config/librechat.e2e.yaml
@@ -41,6 +41,25 @@ mcpServers:
timeout: 30000
endpoints:
+ # Default capabilities plus run_in_background (off by default upstream) so the
+ # background tool-call e2e can opt an MCP tool into detached dispatch.
+ agents:
+ capabilities:
+ - deferred_tools
+ - execute_code
+ - file_search
+ - web_search
+ - artifacts
+ - subagents
+ - actions
+ - context
+ - skills
+ - memory
+ - ask_user_question
+ - tools
+ - chain
+ - ocr
+ - run_in_background
custom:
- name: 'Mock Provider A'
apiKey: 'e2e-mock-key-a'
diff --git a/e2e/setup/fake-mcp-server.js b/e2e/setup/fake-mcp-server.js
index 87419df88a..182d46bd80 100644
--- a/e2e/setup/fake-mcp-server.js
+++ b/e2e/setup/fake-mcp-server.js
@@ -43,6 +43,29 @@ server.registerTool(
}),
);
+server.registerTool(
+ 'slow_echo',
+ {
+ description:
+ 'Echoes text after a delay; used to verify background tool dispatch in mock e2e tests.',
+ inputSchema: {
+ text: z.string(),
+ delay_ms: z.number().optional(),
+ },
+ },
+ async ({ text, delay_ms = 1500 }) => {
+ await new Promise((resolve) => setTimeout(resolve, delay_ms));
+ return {
+ content: [
+ {
+ type: 'text',
+ text: `E2E slow echo: ${text}`,
+ },
+ ],
+ };
+ },
+);
+
async function main() {
await server.connect(new StdioServerTransport());
}
diff --git a/e2e/setup/fake-model.js b/e2e/setup/fake-model.js
index 4464fd4f8d..5c0f6b0b66 100644
--- a/e2e/setup/fake-model.js
+++ b/e2e/setup/fake-model.js
@@ -29,6 +29,8 @@ const SLOW_COUNTED_REPLY_MARKER = 'E2E_SLOW_COUNTED_REPLY:';
const RESUME_ICON_REPLY_MARKER = 'E2E_RESUME_ICON_REPLY:';
const FORCED_ERROR_MARKER = 'E2E_FORCED_ERROR:';
const MARKDOWN_REPLY_MARKER = 'E2E_MARKDOWN_REPLY';
+const BACKGROUND_DISPATCH_MARKER = 'E2E_BACKGROUND_DISPATCH:';
+const BACKGROUND_COLLECT_MARKER = 'E2E_BACKGROUND_COLLECT:';
const CREATE_FILE_AUTHORING_FINAL_TEXT = 'E2E file authoring complete';
const EDIT_FILE_AUTHORING_FINAL_TEXT = 'E2E file edit complete';
const MODEL_SPEC_SKILL_ASSERTION_FINAL_TEXT = 'E2E model spec skill assertion passed';
@@ -45,6 +47,10 @@ const BASH_TOOL_NAME = 'bash_tool';
const SKILL_TOOL_NAME = 'skill';
const CREATE_SKILL_TOOL_CALL_ID = 'call_e2e_create_skill';
const EDIT_SKILL_TOOL_CALL_ID = 'call_e2e_edit_skill';
+const BACKGROUND_TOOL_NAME = 'slow_echo_mcp_e2e-memory';
+const CHECK_BACKGROUND_TASK_TOOL_NAME = 'check_background_task';
+const BACKGROUND_DISPATCH_TOOL_CALL_ID = 'call_e2e_background_dispatch';
+const BACKGROUND_COLLECT_TOOL_CALL_ID = 'call_e2e_background_collect';
const MODEL_SPEC_ACCESSIBLE_SKILL = 'e2e-model-spec-allowed';
const MODEL_SPEC_MISSING_SKILL = 'e2e-model-spec-missing';
const MODEL_SPEC_INACCESSIBLE_SKILL = 'e2e-model-spec-inaccessible';
@@ -593,6 +599,112 @@ function fileAuthoringResponses(operation, toolNames) {
};
}
+function findLastToolMessageText(messages, requiredToken) {
+ for (let index = (messages ?? []).length - 1; index >= 0; index--) {
+ const message = messages[index];
+ if (!message || messageType(message) !== 'tool') {
+ continue;
+ }
+ const content = getContentText(message.content);
+ if (content.includes(requiredToken)) {
+ return content;
+ }
+ }
+ return '';
+}
+
+/**
+ * Turn 1 of the background e2e: emit the MCP tool call with the injected
+ * `run_in_background: true` arg, then (second model invocation, after the
+ * executor returned the synthetic handle) acknowledge the handle. Streaming
+ * `status=running` from the handle proves the dispatch returned before the
+ * tool finished — the non-blocking contract — without timing assertions.
+ */
+function backgroundDispatchResponses(name, toolNames) {
+ if (!toolNames.has(BACKGROUND_TOOL_NAME)) {
+ return {
+ responses: [`E2E background unavailable: ${BACKGROUND_TOOL_NAME} was not advertised.`],
+ };
+ }
+ if (!toolNames.has(CHECK_BACKGROUND_TASK_TOOL_NAME)) {
+ return {
+ responses: [
+ `E2E background unavailable: ${CHECK_BACKGROUND_TASK_TOOL_NAME} was not advertised.`,
+ ],
+ };
+ }
+ return {
+ responses: ['', ''],
+ toolCalls: [
+ {
+ id: BACKGROUND_DISPATCH_TOOL_CALL_ID,
+ name: BACKGROUND_TOOL_NAME,
+ args: { text: `bg-${name}`, delay_ms: 1500, run_in_background: true },
+ type: 'tool_call',
+ },
+ ],
+ resolveOnStream: (streamMessages) => {
+ const handleText = findLastToolMessageText(streamMessages, 'background_task_id');
+ if (!handleText) {
+ return null;
+ }
+ const taskId = handleText.match(/"background_task_id":"([^"]+)"/)?.[1] ?? 'missing';
+ const status = handleText.match(/"status":"(\w+)"/)?.[1] ?? 'missing';
+ return { responses: [`E2E background dispatched id=${taskId} status=${status}`] };
+ },
+ };
+}
+
+/**
+ * Turn 2 of the background e2e: recover the task id from the replayed turn-1
+ * handle in history, poll `check_background_task` with it, and stream the
+ * collected status + echoed text — proving the detached result survived turn
+ * end and was retrieved cross-turn.
+ */
+function backgroundCollectResponses(messages, toolNames) {
+ if (!toolNames.has(CHECK_BACKGROUND_TASK_TOOL_NAME)) {
+ return {
+ responses: [
+ `E2E background unavailable: ${CHECK_BACKGROUND_TASK_TOOL_NAME} was not advertised.`,
+ ],
+ };
+ }
+ const historyText = collectPromptText((messages ?? []).map((message) => message?.content)).join(
+ '\n',
+ );
+ const taskIds = [...historyText.matchAll(/"background_task_id":"([^"]+)"/g)].map(
+ (match) => match[1],
+ );
+ const taskId = taskIds[taskIds.length - 1];
+ if (!taskId) {
+ return {
+ responses: ['E2E background collect failed: no background_task_id found in history.'],
+ };
+ }
+ return {
+ responses: ['', ''],
+ toolCalls: [
+ {
+ id: BACKGROUND_COLLECT_TOOL_CALL_ID,
+ name: CHECK_BACKGROUND_TASK_TOOL_NAME,
+ args: { background_task_id: taskId },
+ type: 'tool_call',
+ },
+ ],
+ resolveOnStream: (streamMessages) => {
+ /** Only the poll result (`serializeTask`) carries a `progress` key — the
+ * replayed dispatch handle in history does not. */
+ const pollText = findLastToolMessageText(streamMessages, '"progress"');
+ if (!pollText) {
+ return null;
+ }
+ const status = pollText.match(/"status":"(\w+)"/)?.[1] ?? 'missing';
+ const echo = pollText.match(/E2E slow echo: (bg-[\w-]+)/)?.[1] ?? 'missing';
+ return { responses: [`E2E background collected status=${status} echo=${echo}`] };
+ },
+ };
+}
+
function resolveResponses({ agents, messages, text, toolNames }) {
const reply = replyResponses(text);
if (reply) {
@@ -635,6 +747,15 @@ function resolveResponses({ agents, messages, text, toolNames }) {
);
}
+ const backgroundDispatchName = getMarkerValue(text, BACKGROUND_DISPATCH_MARKER);
+ if (backgroundDispatchName) {
+ return backgroundDispatchResponses(backgroundDispatchName, toolNames);
+ }
+
+ if (text.includes(BACKGROUND_COLLECT_MARKER)) {
+ return backgroundCollectResponses(messages, toolNames);
+ }
+
const editSkillName = getRequestedSkillName(text, EDIT_SKILL_MARKER);
if (editSkillName) {
return fileAuthoringResponses(
diff --git a/e2e/specs/mock/background-tools.spec.ts b/e2e/specs/mock/background-tools.spec.ts
new file mode 100644
index 0000000000..21c6f00b38
--- /dev/null
+++ b/e2e/specs/mock/background-tools.spec.ts
@@ -0,0 +1,114 @@
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import type { AgentDetail } from './agents.helpers';
+import { cleanupAgent, openAgentBuilder, uniqueAgentName } from './agents.helpers';
+import {
+ MOCK_ENDPOINTS,
+ fetchJson,
+ getAccessToken,
+ messagesView,
+ requestJson,
+ sendMessage,
+} from './helpers';
+
+const MCP_SERVER_NAME = 'e2e-memory';
+const BACKGROUND_TOOL_ID = `slow_echo_mcp_${MCP_SERVER_NAME}`;
+const MCP_SERVER_TOOL_ID = `sys__server__sys_mcp_${MCP_SERVER_NAME}`;
+const DESCRIPTION = 'Verifies background (detached) MCP tool calls in mock e2e tests.';
+
+type MCPToolsResponse = {
+ servers?: Record<string, { tools?: Array<{ pluginKey: string }> }>;
+};
+
+async function waitForBackgroundTool(page: Page) {
+ const token = await getAccessToken(page);
+ let latestTools: MCPToolsResponse | null = null;
+
+ for (let attempt = 0; attempt < 20; attempt++) {
+ latestTools = await fetchJson<MCPToolsResponse>(page, '/api/mcp/tools', token);
+ const serverTools = latestTools.servers?.[MCP_SERVER_NAME]?.tools ?? [];
+ if (serverTools.some((tool) => tool.pluginKey === BACKGROUND_TOOL_ID)) {
+ return;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 500));
+ }
+
+ expect(
+ latestTools?.servers?.[MCP_SERVER_NAME]?.tools,
+ `Expected ${MCP_SERVER_NAME} to expose ${BACKGROUND_TOOL_ID}`,
+ ).toEqual(expect.arrayContaining([expect.objectContaining({ pluginKey: BACKGROUND_TOOL_ID })]));
+}
+
+test.describe('background tool calls', () => {
+ test('dispatches a tool in the background and collects its result on a later turn', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await page.goto('/c/new', { timeout: 10000 });
+
+ const agentName = uniqueAgentName('E2E Background Agent');
+ const runToken = `${Date.now()}-${Math.floor(Math.random() * 1e4)}`;
+ let createdAgentId: string | undefined;
+
+ try {
+ await waitForBackgroundTool(page);
+
+ /** The opt-in contract under test lives in `tool_options`, so the agent is
+ * created through the same API the builder uses; the toggle UI itself is
+ * covered by the MCPToolItem jest suite. */
+ const token = await getAccessToken(page);
+ const createdAgent = await requestJson<AgentDetail>(page, {
+ path: '/api/agents',
+ token,
+ method: 'POST',
+ body: {
+ name: agentName,
+ description: DESCRIPTION,
+ instructions: 'Reply through the mock e2e model.',
+ provider: MOCK_ENDPOINTS[0].label,
+ model: MOCK_ENDPOINTS[0].model,
+ tools: [MCP_SERVER_TOOL_ID, BACKGROUND_TOOL_ID],
+ tool_options: { [BACKGROUND_TOOL_ID]: { run_in_background: true } },
+ },
+ });
+ createdAgentId = createdAgent.id;
+ expect(createdAgent.tools).toEqual(expect.arrayContaining([BACKGROUND_TOOL_ID]));
+
+ const form = await openAgentBuilder(page);
+ await form.getByRole('combobox', { name: 'Agent', exact: true }).click();
+ await page.getByRole('option', { name: agentName }).click();
+ await expect(form.getByLabel('Agent name')).toHaveValue(agentName);
+ await form.getByRole('button', { name: 'Select Agent' }).click();
+
+ /** Turn 1: the model requests the tool with `run_in_background: true`; the
+ * executor must return a synthetic handle immediately. The fake model
+ * echoes the handle it saw — `status=running` proves the dispatch did not
+ * block on the tool (which sleeps 1.5s). */
+ const dispatch = await sendMessage(page, `E2E_BACKGROUND_DISPATCH:${runToken}`);
+ expect(dispatch.ok()).toBeTruthy();
+ const dispatchAck = messagesView(page).getByText(
+ /E2E background dispatched id=[\w-]+ status=running/,
+ );
+ await expect(dispatchAck).toBeVisible({ timeout: 30000 });
+ await expect(page).toHaveURL(/\/c\/(?!new)/, { timeout: 15000 });
+
+ /** The tool finishes ~1.5s after dispatch, past the end of turn 1 — the
+ * detached promise survives its originating turn. Give it time to land
+ * in the registry before the collect turn polls. */
+ await page.waitForTimeout(2500);
+
+ /** Turn 2: the fake model recovers the task id from turn-1 history, calls
+ * `check_background_task` with it, and echoes what the poll returned —
+ * status + the tool's output retrieved from the cross-turn registry. */
+ const collect = await sendMessage(page, `E2E_BACKGROUND_COLLECT:${runToken}`);
+ expect(collect.ok()).toBeTruthy();
+ await expect(
+ messagesView(page).getByText(
+ new RegExp(`E2E background collected status=completed echo=bg-${runToken}`),
+ ),
+ ).toBeVisible({ timeout: 30000 });
+ } finally {
+ await cleanupAgent(page, createdAgentId);
+ }
+ });
+});
diff --git a/packages/api/src/agents/__tests__/load.spec.ts b/packages/api/src/agents/__tests__/load.spec.ts
index 2604b5fe63..deeebc5ce5 100644
--- a/packages/api/src/agents/__tests__/load.spec.ts
+++ b/packages/api/src/agents/__tests__/load.spec.ts
@@ -389,6 +389,89 @@ describe('loadAgent', () => {
expect(withoutFlag?.tools).not.toContain('ask_user_question');
});
+ test('synthesizes background tool_options for eligible MCP tools from the ephemeralAgent flag', async () => {
+ const { EPHEMERAL_AGENT_ID } = Constants;
+ mockGetMCPServerTools.mockResolvedValue({ crm_lookup: { name: 'crm_lookup' } });
+
+ const result = await loadAgent(
+ {
+ req: {
+ user: { id: 'user123' },
+ body: {
+ ephemeralAgent: {
+ mcp: ['crm'],
+ web_search: true,
+ execute_code: true,
+ run_in_background: true,
+ } as TEphemeralAgent,
+ },
+ },
+ agent_id: EPHEMERAL_AGENT_ID as string,
+ endpoint: 'openai',
+ model_parameters: { model: 'gpt-4' } as unknown as AgentModelParameters,
+ },
+ deps,
+ );
+
+ // eligible MCP tool opts in; excluded built-ins (web_search, execute_code) do not
+ expect(result?.tool_options?.crm_lookup).toEqual({ run_in_background: true });
+ expect(result?.tool_options?.web_search).toBeUndefined();
+ expect(result?.tool_options?.execute_code).toBeUndefined();
+ });
+
+ test('synthesizes background tool_options from a model spec (runInBackground: true), and not without it', async () => {
+ const { EPHEMERAL_AGENT_ID } = Constants;
+ mockGetMCPServerTools.mockResolvedValue({ crm_lookup: { name: 'crm_lookup' } });
+
+ const buildReq = (specName: string, runInBackground: boolean): LoadAgentParams['req'] =>
+ ({
+ user: { id: 'user123' },
+ body: {},
+ config: {
+ config: {},
+ fileStrategy: FileSources.local,
+ imageOutputType: 'png',
+ modelSpecs: {
+ list: [
+ {
+ name: specName,
+ label: specName,
+ preset: { endpoint: 'openai', model: 'gpt-4' },
+ webSearch: true,
+ mcpServers: ['crm'],
+ runInBackground,
+ },
+ ],
+ },
+ },
+ }) as unknown as LoadAgentParams['req'];
+
+ const withFlag = await loadAgent(
+ {
+ req: buildReq('bg-on', true),
+ spec: 'bg-on',
+ agent_id: EPHEMERAL_AGENT_ID as string,
+ endpoint: 'openai',
+ model_parameters: { model: 'gpt-4' } as unknown as AgentModelParameters,
+ },
+ deps,
+ );
+ expect(withFlag?.tool_options?.crm_lookup).toEqual({ run_in_background: true });
+ expect(withFlag?.tool_options?.web_search).toBeUndefined();
+
+ const withoutFlag = await loadAgent(
+ {
+ req: buildReq('bg-off', false),
+ spec: 'bg-off',
+ agent_id: EPHEMERAL_AGENT_ID as string,
+ endpoint: 'openai',
+ model_parameters: { model: 'gpt-4' } as unknown as AgentModelParameters,
+ },
+ deps,
+ );
+ expect(withoutFlag?.tool_options).toBeUndefined();
+ });
+
test('should enable full skill scope for ephemeral model spec with skills true', async () => {
const { EPHEMERAL_AGENT_ID } = Constants;
diff --git a/packages/api/src/agents/added.ts b/packages/api/src/agents/added.ts
index cf07ce1ff1..3146547bf1 100644
--- a/packages/api/src/agents/added.ts
+++ b/packages/api/src/agents/added.ts
@@ -7,9 +7,10 @@ import {
appendAgentIdSuffix,
encodeEphemeralAgentId,
} from 'librechat-data-provider';
-import type { Agent, TConversation, TModelSpec } from 'librechat-data-provider';
+import type { Agent, AgentToolOptions, TConversation, TModelSpec } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import { ASK_USER_QUESTION_TOOL_NAME } from '~/agents/hitl/askUserQuestionTool';
+import { synthesizeBackgroundToolOptions } from '~/agents/background';
import { requiresEphemeralUserConnection } from '~/mcp/utils';
import { getCustomEndpointConfig } from '~/app/config';
@@ -119,6 +120,7 @@ export async function loadAddedAgent(
artifacts?: unknown;
memory?: boolean;
ask_user_question?: boolean;
+ run_in_background?: boolean;
}
| undefined;
@@ -156,6 +158,11 @@ export async function loadAddedAgent(
};
applyModelSpecSkills(result, modelSpec);
applyModelSpecSubagents(result, modelSpec);
+ const primaryBackgroundToolOptions: AgentToolOptions | undefined =
+ synthesizeBackgroundToolOptions(result.tools as string[], { ephemeralAgent, modelSpec });
+ if (primaryBackgroundToolOptions) {
+ result.tool_options = primaryBackgroundToolOptions;
+ }
return result as unknown as Agent;
}
@@ -267,5 +274,13 @@ export async function loadAddedAgent(
applyModelSpecSubagents(result, modelSpec);
applyModelSpecSkills(result, modelSpec);
+ const backgroundToolOptions: AgentToolOptions | undefined = synthesizeBackgroundToolOptions(
+ tools,
+ { ephemeralAgent, modelSpec },
+ );
+ if (backgroundToolOptions) {
+ result.tool_options = backgroundToolOptions;
+ }
+
return result as unknown as Agent;
}
diff --git a/packages/api/src/agents/background.spec.ts b/packages/api/src/agents/background.spec.ts
new file mode 100644
index 0000000000..7038b39f0f
--- /dev/null
+++ b/packages/api/src/agents/background.spec.ts
@@ -0,0 +1,766 @@
+import type { LCTool, LCToolRegistry } from '@librechat/agents';
+import {
+ isBackgroundEligibleToolName,
+ isBackgroundRequested,
+ stripRunInBackgroundArg,
+ injectRunInBackgroundParam,
+ stripBackgroundFromToolDefinitions,
+ stripBackgroundFromToolRegistry,
+ applyBackgroundToolCalls,
+ synthesizeBackgroundToolOptions,
+ registerBackgroundTaskTool,
+ buildBackgroundHandleContent,
+ runCheckBackgroundTask,
+ backgroundTaskRegistry,
+ BackgroundTaskRegistryClass,
+ CHECK_BACKGROUND_TASK_NAME,
+ RUN_IN_BACKGROUND_ARG,
+} from './background';
+import { toolOptionsSchema } from './validation';
+
+const mcpDef = (name: string): LCTool =>
+ ({
+ name,
+ description: `${name} description`,
+ parameters: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+ }) as unknown as LCTool;
+
+describe('isBackgroundEligibleToolName', () => {
+ it('excludes direct-path, host-special, code-session, and machinery tools', () => {
+ for (const name of [
+ 'execute_code',
+ 'bash_tool',
+ '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);
+ }
+ });
+});
+
+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('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('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,
+ );
+ });
+});
+
+describe('synthesizeBackgroundToolOptions', () => {
+ it('returns undefined when neither the ephemeral toggle nor the model spec enables it', () => {
+ expect(synthesizeBackgroundToolOptions(['search_mcp_docs'], {})).toBeUndefined();
+ expect(
+ synthesizeBackgroundToolOptions(['search_mcp_docs'], {
+ ephemeralAgent: { run_in_background: false },
+ modelSpec: { runInBackground: false },
+ }),
+ ).toBeUndefined();
+ });
+
+ it('marks only eligible tools (excludes code/HITL/attachment built-ins)', () => {
+ const options = synthesizeBackgroundToolOptions(
+ ['search_mcp_docs', 'execute_code', 'ask_user_question', 'web_search', 'lookup_customer'],
+ { ephemeralAgent: { run_in_background: true } },
+ );
+ expect(options).toEqual({
+ search_mcp_docs: { run_in_background: true },
+ lookup_customer: { run_in_background: true },
+ });
+ });
+
+ it('returns undefined when nothing is eligible', () => {
+ expect(
+ synthesizeBackgroundToolOptions(['execute_code', 'skill'], {
+ modelSpec: { runInBackground: true },
+ }),
+ ).toBeUndefined();
+ });
+});
+
+describe('BackgroundTaskRegistryClass', () => {
+ 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('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',
+ 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('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('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',
+ artifact: { files: ['a.png'] },
+ content: 'DONE',
+ });
+ expect(registry.claimArtifact('u1', 'c1', created.task.id)).toBeUndefined();
+ });
+
+ it('reaps a stuck running task past the running TTL (frees the slot)', () => {
+ 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 creation past the 30-min running TTL, then trigger a sweep
+ created.task.createdAt = Date.now() - 31 * 60 * 1000;
+ registry.list('u1', 'c1');
+ expect(created.task.status).toBe('error');
+ expect(created.task.error).toBe('Background task timed out');
+ });
+
+ 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('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('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('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('runCheckBackgroundTask (singleton)', () => {
+ it('returns not_found for an unknown id', () => {
+ const content = 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('returns a single task by id and lists all when omitted', () => {
+ 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(
+ 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(
+ 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(
+ runCheckBackgroundTask({
+ userId: 'poll_user',
+ conversationId: 'poll_convo2',
+ args: `{"background_task_id":"${created.task.id}"}`,
+ }),
+ );
+ expect(singleFromString).toEqual(
+ expect.objectContaining({ status: 'completed', result: 'RESULT' }),
+ );
+ });
+
+ it('retrieves a task across turns: the poll is keyed only by id, not the dispatch run/turn', () => {
+ // 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(
+ 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,
+ }),
+ );
+ });
+});
+
+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('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);
+ });
+});
+
+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 });
+ });
+});
diff --git a/packages/api/src/agents/background.ts b/packages/api/src/agents/background.ts
new file mode 100644
index 0000000000..474c745209
--- /dev/null
+++ b/packages/api/src/agents/background.ts
@@ -0,0 +1,860 @@
+/**
+ * @fileoverview Background tool calls.
+ *
+ * Lets the model dispatch an eligible (event-driven) tool call detached: the
+ * host executor returns a synthetic handle immediately so the graph superstep
+ * resolves, while the real work runs as a floating promise whose result lands
+ * in an in-process registry. The model retrieves it via the
+ * `check_background_task` poll tool. No `@librechat/agents` change is required —
+ * a backgrounded call and the poll call are both synchronous from the graph's
+ * view.
+ *
+ * Scope: cross-turn parallelism on a single Node process. The run's abort
+ * signal does not reach the detached invoke (the graph forwards only
+ * `configurable`/`metadata` to the tool-execute handler, never `signal`), so
+ * the floating promise keeps running past turn completion and its result stays
+ * in the in-process registry for a later turn to poll. Two boundaries: results
+ * are lost on restart and are not shared across replicas (durable follow-up),
+ * and ephemeral request-scoped MCP tools (runtime `{{LIBRECHAT_BODY_*}}`
+ * placeholders) are never backgrounded — their connection is torn down at
+ * request end, so the executor runs them in the foreground instead.
+ *
+ * Opt-in mirrors `deferred_tools`: an admin capability
+ * (`AgentCapabilities.run_in_background`) gates the feature, and a per-tool
+ * `tool_options[name].run_in_background` flag turns it on for a given tool,
+ * which injects a `run_in_background` boolean into that tool's schema.
+ *
+ * @module packages/api/src/agents/background
+ */
+
+import { randomUUID } from 'node:crypto';
+import { logger } from '@librechat/data-schemas';
+import { Constants as AgentConstants } from '@librechat/agents';
+import { Tools, Constants, imageGenTools } from 'librechat-data-provider';
+import type { LCTool, LCToolRegistry, JsonSchemaType } from '@librechat/agents';
+import type { AgentToolOptions } from 'librechat-data-provider';
+import { SET_MEMORY_TOOL_NAME, DELETE_MEMORY_TOOL_NAME } from './memory';
+import { ASK_USER_QUESTION_TOOL_NAME } from './hitl/askUserQuestionTool';
+import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from './tools';
+import { truncateMiddle } from '~/utils';
+
+/** Argument the model sets on a tool call to dispatch it in the background. */
+export const RUN_IN_BACKGROUND_ARG = 'run_in_background';
+
+/** Poll tool name (LibreChat host-special-cased, not an SDK tool). */
+export const CHECK_BACKGROUND_TASK_NAME: string = Constants.CHECK_BACKGROUND_TASK;
+
+/**
+ * Tools that must never be backgrounded — they either run through the SDK's
+ * direct/host-special path (so the host `ON_TOOL_EXECUTE` interception never
+ * sees them), depend on synchronous artifact/code-session continuity, or are
+ * the background machinery itself.
+ */
+const EXCLUDED_BACKGROUND_TOOL_NAMES: ReadonlySet<string> = new Set<string>([
+ AgentConstants.EXECUTE_CODE,
+ AgentConstants.BASH_TOOL,
+ AgentConstants.READ_FILE,
+ AgentConstants.SKILL_TOOL,
+ AgentConstants.TOOL_SEARCH,
+ AgentConstants.PROGRAMMATIC_TOOL_CALLING,
+ AgentConstants.BASH_PROGRAMMATIC_TOOL_CALLING,
+ AgentConstants.SUBAGENT,
+ CREATE_FILE_TOOL_NAME,
+ EDIT_FILE_TOOL_NAME,
+ SET_MEMORY_TOOL_NAME,
+ DELETE_MEMORY_TOOL_NAME,
+ ASK_USER_QUESTION_TOOL_NAME,
+ CHECK_BACKGROUND_TASK_NAME,
+ /**
+ * Built-ins whose results are turned into user-visible attachments/citations
+ * by the foreground `toolEndCallback`; a detached run stores only content, so
+ * backgrounding them would silently drop those sources/files. Image-generation
+ * tools are artifact-first — their files can't be reliably attached to an
+ * already-saved turn — so they're excluded rather than degraded. Sourced from
+ * the shared `imageGenTools` set plus the OAI toolkit ids it doesn't cover.
+ */
+ Tools.web_search,
+ Tools.file_search,
+ ...imageGenTools,
+ 'image_gen_oai',
+ 'image_edit_oai',
+]);
+
+/**
+ * Whether a tool may be dispatched in the background. Handoff tools
+ * (`lc_transfer_to_*`) run through the direct path and are excluded by prefix.
+ */
+export function isBackgroundEligibleToolName(name: string): boolean {
+ if (EXCLUDED_BACKGROUND_TOOL_NAMES.has(name)) {
+ return false;
+ }
+ return !name.startsWith(AgentConstants.LC_TRANSFER_TO_);
+}
+
+/**
+ * Coerces tool-call args to an object, parsing a stringified JSON object (some
+ * providers deliver args as a string). Returns undefined for non-object args.
+ */
+function coerceArgsObject(args: unknown): Record<string, unknown> | undefined {
+ if (typeof args === 'object' && args !== null && !Array.isArray(args)) {
+ return args as Record<string, unknown>;
+ }
+ if (typeof args === 'string' && args.trim().startsWith('{')) {
+ try {
+ const parsed = JSON.parse(args) as unknown;
+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+ return parsed as Record<string, unknown>;
+ }
+ } catch {
+ return undefined;
+ }
+ }
+ return undefined;
+}
+
+/** Whether tool-call args request background dispatch (handles stringified args). */
+export function isBackgroundRequested(args: unknown): boolean {
+ return coerceArgsObject(args)?.[RUN_IN_BACKGROUND_ARG] === true;
+}
+
+/** Whether tool-call args carry the `run_in_background` key at all (any value). */
+export function hasRunInBackgroundArg(args: unknown): boolean {
+ const obj = coerceArgsObject(args);
+ return obj != null && RUN_IN_BACKGROUND_ARG in obj;
+}
+
+/**
+ * Returns the args without the injected `run_in_background` key so the real
+ * tool never receives a parameter it doesn't declare. Parses stringified JSON
+ * object args; returns the value unchanged when the flag is absent.
+ */
+export function stripRunInBackgroundArg(args: unknown): unknown {
+ const obj = coerceArgsObject(args);
+ if (!obj || !(RUN_IN_BACKGROUND_ARG in obj)) {
+ return args;
+ }
+ const { [RUN_IN_BACKGROUND_ARG]: _omit, ...rest } = obj;
+ return rest;
+}
+
+const RUN_IN_BACKGROUND_PROPERTY: JsonSchemaType = Object.freeze<JsonSchemaType>({
+ type: 'boolean',
+ description:
+ 'Set true to run this tool call in the background: it returns immediately with a background_task_id instead of blocking, so you can keep working while it runs. Poll check_background_task with that id to collect the result. The task persists on this server, so you may collect it later in this turn or in a following turn (it does not survive a server restart). Use for a slow call whose result you do not need right away.',
+});
+
+/**
+ * Returns a copy of the tool definition with a `run_in_background` boolean
+ * added to its parameters. Never mutates the input (built-in defs are frozen
+ * and MCP defs may be shared), and is a no-op if the property already exists.
+ */
+export function injectRunInBackgroundParam(def: LCTool): LCTool {
+ const params = def.parameters;
+ const existingProps = params?.properties ?? {};
+ if (RUN_IN_BACKGROUND_ARG in existingProps) {
+ return def;
+ }
+ const nextParams: JsonSchemaType = {
+ ...params,
+ type: 'object',
+ properties: { ...existingProps, [RUN_IN_BACKGROUND_ARG]: RUN_IN_BACKGROUND_PROPERTY },
+ };
+ return { ...def, parameters: nextParams };
+}
+
+/**
+ * Whether the `run_in_background` param can be cleanly injected into a tool.
+ * False for non-object (e.g. string-input/DynamicTool) schemas — rewriting them
+ * to an object would break the tool's input contract — and for tools that
+ * already declare their own `run_in_background` parameter (which the executor
+ * would otherwise hijack/strip).
+ */
+function canInjectRunInBackgroundParam(def: LCTool): boolean {
+ const params = def.parameters;
+ if (params == null) {
+ return true;
+ }
+ if (params.type != null && params.type !== 'object') {
+ return false;
+ }
+ return !(params.properties != null && RUN_IN_BACKGROUND_ARG in params.properties);
+}
+
+/** Returns a copy of the def without the injected `run_in_background` property. */
+function removeRunInBackgroundParam(def: LCTool): LCTool {
+ const params = def.parameters;
+ if (params?.properties == null || !(RUN_IN_BACKGROUND_ARG in params.properties)) {
+ return def;
+ }
+ const { [RUN_IN_BACKGROUND_ARG]: _omit, ...restProps } = params.properties;
+ return { ...def, parameters: { ...params, properties: restProps } };
+}
+
+/**
+ * Removes the background additions (the injected param + the `check_background_task`
+ * def) from a tool-definition list. Used to sanitize a self-spawn subagent's
+ * inherited inputs so it doesn't advertise a background schema the isolated child
+ * path can't honor.
+ */
+export function stripBackgroundFromToolDefinitions(
+ toolDefinitions: LCTool[] | undefined,
+ backgroundToolNames: string[] | undefined,
+): LCTool[] {
+ const defs = toolDefinitions ?? [];
+ const bgSet = new Set(backgroundToolNames ?? []);
+ const next: LCTool[] = [];
+ let changed = false;
+ for (const def of defs) {
+ if (def.name === CHECK_BACKGROUND_TASK_NAME) {
+ changed = true;
+ continue;
+ }
+ const stripped = bgSet.size > 0 && bgSet.has(def.name) ? removeRunInBackgroundParam(def) : def;
+ if (stripped !== def) {
+ changed = true;
+ }
+ next.push(stripped);
+ }
+ return changed ? next : defs;
+}
+
+/**
+ * Registry counterpart of {@link stripBackgroundFromToolDefinitions}. Returns a
+ * NEW registry (never mutates the shared parent one) without the poll tool and
+ * with the injected param removed, so a self-spawn child that uses
+ * tool_search/deferred loading can't rediscover the host-only background schema.
+ */
+export function stripBackgroundFromToolRegistry(
+ toolRegistry: LCToolRegistry | undefined,
+ backgroundToolNames: string[] | undefined,
+): LCToolRegistry | undefined {
+ if (!toolRegistry) {
+ return toolRegistry;
+ }
+ const bgSet = new Set(backgroundToolNames ?? []);
+ if (bgSet.size === 0 && !toolRegistry.has(CHECK_BACKGROUND_TASK_NAME)) {
+ return toolRegistry;
+ }
+ const next: LCToolRegistry = new Map();
+ for (const [name, def] of toolRegistry) {
+ if (name === CHECK_BACKGROUND_TASK_NAME) {
+ continue;
+ }
+ next.set(name, bgSet.has(name) ? removeRunInBackgroundParam(def) : def);
+ }
+ return next;
+}
+
+const CHECK_BACKGROUND_TASK_DESCRIPTION = `Check the status and retrieve the result of tool calls previously dispatched in the background (with run_in_background: true).
+
+Provide a background_task_id to poll one task; omit it to list every background task in this conversation. A task is only finished when its status is "completed" or "error" — never assume completion without polling. Results are not pushed to you; you must call this tool to collect them. Background tasks persist on this server across turns, so you can collect a result in a later turn; they do not survive a server restart.`;
+
+const CHECK_BACKGROUND_TASK_PARAMETERS: JsonSchemaType = Object.freeze<JsonSchemaType>({
+ type: 'object',
+ properties: {
+ background_task_id: {
+ type: 'string',
+ description:
+ 'The id returned when the tool call was dispatched. Omit to list the status of all background tasks in this conversation.',
+ },
+ },
+ required: [],
+});
+
+const CHECK_BACKGROUND_TASK_DEF: LCTool = Object.freeze<LCTool>({
+ name: CHECK_BACKGROUND_TASK_NAME,
+ description: CHECK_BACKGROUND_TASK_DESCRIPTION,
+ parameters: CHECK_BACKGROUND_TASK_PARAMETERS,
+});
+
+/**
+ * Idempotently registers the `check_background_task` poll tool into the run's
+ * tool definitions and registry. Mirrors `registerCodeExecutionTools`.
+ */
+export function registerBackgroundTaskTool(params: {
+ toolRegistry: LCToolRegistry | undefined;
+ toolDefinitions: LCTool[] | undefined;
+}): { toolDefinitions: LCTool[] } {
+ const { toolRegistry, toolDefinitions } = params;
+ const defs = toolDefinitions ?? [];
+ const isOurs = (tool?: { description?: string }): boolean =>
+ tool?.description === CHECK_BACKGROUND_TASK_DESCRIPTION;
+
+ const existingDef = defs.find((d) => d.name === CHECK_BACKGROUND_TASK_NAME);
+ const existingRegistry = toolRegistry?.get(CHECK_BACKGROUND_TASK_NAME);
+
+ /** Already registered by us — idempotent no-op. */
+ if (isOurs(existingDef) || isOurs(existingRegistry)) {
+ return { toolDefinitions: defs };
+ }
+
+ /**
+ * The name is reserved: since the executor intercepts every
+ * `check_background_task` call in a background-enabled run, a user/MCP tool
+ * with the same name must not be advertised (its schema would mismatch the
+ * interception). Overwrite so the model sees the poll schema the host honors,
+ * and warn that the colliding tool is shadowed.
+ */
+ const collides = existingDef != null || existingRegistry != null;
+ if (collides) {
+ logger.warn(
+ `[background] A tool named "${CHECK_BACKGROUND_TASK_NAME}" collides with the reserved background poll tool; the host poll tool takes precedence and the colliding tool is shadowed for this run.`,
+ );
+ }
+ toolRegistry?.set(CHECK_BACKGROUND_TASK_NAME, {
+ name: CHECK_BACKGROUND_TASK_NAME,
+ description: CHECK_BACKGROUND_TASK_DESCRIPTION,
+ parameters: CHECK_BACKGROUND_TASK_PARAMETERS,
+ allowed_callers: ['direct'],
+ });
+ const withoutCollision = collides
+ ? defs.filter((d) => d.name !== CHECK_BACKGROUND_TASK_NAME)
+ : defs;
+ return { toolDefinitions: [...withoutCollision, CHECK_BACKGROUND_TASK_DEF] };
+}
+
+/**
+ * Injects the `run_in_background` param into every opted-in, eligible tool and
+ * registers the poll tool when at least one tool became backgroundable.
+ *
+ * Opt-in is per tool via `tool_options[name].run_in_background`. Both saved
+ * agents and ephemeral/model-spec agents reach this with `tool_options`
+ * populated, so the logic is written once.
+ */
+export function applyBackgroundToolCalls(params: {
+ toolDefinitions: LCTool[] | undefined;
+ toolRegistry: LCToolRegistry | undefined;
+ toolOptions: AgentToolOptions | undefined;
+ /**
+ * Extra host-context exclusion (e.g. tools of ephemeral request-scoped MCP
+ * servers, whose connection dies at request end): a `true` return skips the
+ * param injection entirely so the model is never shown an option the
+ * executor would silently downgrade to foreground.
+ */
+ excludeTool?: (toolName: string) => boolean;
+}): { toolDefinitions: LCTool[]; backgroundToolNames: string[] } {
+ const { toolRegistry, toolOptions, excludeTool } = params;
+ const defs = params.toolDefinitions ?? [];
+ if (!toolOptions || !Object.values(toolOptions).some((o) => o?.run_in_background === true)) {
+ return { toolDefinitions: defs, backgroundToolNames: [] };
+ }
+
+ const backgroundToolNames: string[] = [];
+ const nextDefs = defs.map((def) => {
+ const optedIn = toolOptions[def.name]?.run_in_background === true;
+ if (!optedIn || !isBackgroundEligibleToolName(def.name) || excludeTool?.(def.name) === true) {
+ return def;
+ }
+ if (!canInjectRunInBackgroundParam(def)) {
+ logger.warn(
+ `[background] Skipping run_in_background for "${def.name}": non-object schema or the tool already declares the parameter.`,
+ );
+ return def;
+ }
+ backgroundToolNames.push(def.name);
+ const injected = injectRunInBackgroundParam(def);
+ if (injected === def) {
+ return def;
+ }
+ const registryEntry = toolRegistry?.get(def.name);
+ if (registryEntry) {
+ toolRegistry?.set(def.name, { ...registryEntry, parameters: injected.parameters });
+ }
+ return injected;
+ });
+
+ if (backgroundToolNames.length === 0) {
+ return { toolDefinitions: defs, backgroundToolNames: [] };
+ }
+
+ const withPoll = registerBackgroundTaskTool({ toolRegistry, toolDefinitions: nextDefs });
+ return { toolDefinitions: withPoll.toolDefinitions, backgroundToolNames };
+}
+
+/**
+ * Builds `tool_options` marking each eligible tool as backgroundable. Ephemeral
+ * and model-spec agents carry no `tool_options`, so the blanket spec/ephemeral
+ * toggle is expanded per-tool here to reuse the same per-tool opt-in the saved
+ * agent path uses. Returns undefined when disabled or nothing is eligible.
+ *
+ * Note: MCP servers that expand lazily (via the `mcp_all` placeholder for
+ * overlay/user-connection servers) are not known by name at this point, so
+ * their tools are not marked; standard cached MCP servers push real names and
+ * are covered.
+ */
+export function synthesizeBackgroundToolOptions(
+ tools: string[],
+ sources: {
+ ephemeralAgent?: { run_in_background?: boolean } | null;
+ modelSpec?: { runInBackground?: boolean } | null;
+ },
+): AgentToolOptions | undefined {
+ const enabled =
+ sources.ephemeralAgent?.run_in_background === true ||
+ sources.modelSpec?.runInBackground === true;
+ if (!enabled) {
+ return undefined;
+ }
+ const toolOptions: AgentToolOptions = {};
+ for (const name of tools) {
+ if (isBackgroundEligibleToolName(name)) {
+ toolOptions[name] = { run_in_background: true };
+ }
+ }
+ return Object.keys(toolOptions).length > 0 ? toolOptions : undefined;
+}
+
+export type BackgroundTaskStatus = 'running' | 'completed' | 'error';
+
+export interface BackgroundTask {
+ id: string;
+ toolName: string;
+ toolCallId: string;
+ status: BackgroundTaskStatus;
+ /** Tool result content once completed. */
+ result?: string;
+ /**
+ * The completed tool's artifact, held until the poll turn collects it (a
+ * backgrounded call's own turn is finalized before the artifact resolves, so
+ * it can't ride that turn). Cleared once delivered to free memory.
+ */
+ artifact?: unknown;
+ /** True once the artifact has been handed to a live poll turn's callback. */
+ artifactDelivered?: boolean;
+ /** Error message when status === 'error'. */
+ error?: string;
+ createdAt: number;
+ updatedAt: number;
+}
+
+interface TaskBucket {
+ tasks: Map<string, BackgroundTask>;
+ /** toolCallId -> taskId, for dispatch idempotency across graph re-execution. */
+ byToolCall: Map<string, string>;
+ lastAccess: number;
+}
+
+const COMPLETED_TASK_TTL_MS = 60 * 60 * 1000;
+const IDLE_BUCKET_TTL_MS = 6 * 60 * 60 * 1000;
+/** Max wall-clock a task may stay `running` before being reaped as timed-out,
+ * so a detached call that never settles (hung network / lost MCP connection)
+ * can't hold a running slot and exhaust the per-conversation cap forever. */
+const RUNNING_TASK_TTL_MS = 30 * 60 * 1000;
+const MAX_RUNNING_PER_BUCKET = 10;
+const MAX_TASKS_PER_BUCKET = 200;
+const MAX_RESULT_CHARS = 100_000;
+const MAX_ARTIFACT_CHARS = 10_000_000;
+const GLOBAL_SWEEP_INTERVAL_MS = 60 * 1000;
+
+function toStoredContent(content: unknown): string {
+ const asString = typeof content === 'string' ? content : JSON.stringify(content ?? '');
+ return truncateMiddle(asString, MAX_RESULT_CHARS);
+}
+
+/**
+ * Bounds retained artifact memory: an artifact is held for up to the completed
+ * TTL, so a runaway payload (huge base64 blobs) is dropped rather than pinned.
+ * Measurement failures (circular refs) keep the artifact.
+ */
+function toStoredArtifact(taskId: string, artifact: unknown): unknown {
+ if (artifact == null) {
+ return undefined;
+ }
+ try {
+ const size = JSON.stringify(artifact)?.length ?? 0;
+ if (size > MAX_ARTIFACT_CHARS) {
+ logger.warn(
+ `[background] Dropping oversized artifact for task ${taskId} (${size} chars > ${MAX_ARTIFACT_CHARS}).`,
+ );
+ return undefined;
+ }
+ } catch {
+ /* unmeasurable artifact: keep it */
+ }
+ return artifact;
+}
+
+/**
+ * In-process store of background tool tasks, scoped per user + conversation.
+ *
+ * MVP scope: single Node process. A task's result survives across turns within
+ * the same server process (a floating promise keeps running on the event loop),
+ * but is lost on restart and is not shared across Redis replicas — a run resumed
+ * on another replica cannot see it. A Redis-backed store would slot in behind
+ * this same interface as a follow-up.
+ */
+export class BackgroundTaskRegistryClass {
+ private readonly buckets = new Map<string, TaskBucket>();
+ private lastGlobalSweepAt = 0;
+
+ private key(userId: string, conversationId: string): string {
+ return `${userId}::${conversationId}`;
+ }
+
+ private sweepBucketTasks(bucket: TaskBucket, now: number): void {
+ for (const [taskId, task] of bucket.tasks) {
+ if (task.status === 'running' && now - task.createdAt > RUNNING_TASK_TTL_MS) {
+ /** Reap a stuck task: freeing the running slot (it no longer counts
+ * toward the cap) and letting the completed-task TTL evict it. */
+ task.status = 'error';
+ task.error = 'Background task timed out';
+ task.updatedAt = now;
+ continue;
+ }
+ if (task.status !== 'running' && now - task.updatedAt > COMPLETED_TASK_TTL_MS) {
+ bucket.tasks.delete(taskId);
+ }
+ }
+ /** Drop dedupe mappings whose task was evicted (keys are
+ * `agentId::runId::toolCallId`, so they can't be derived from a task alone). */
+ for (const [dedupeKey, taskId] of bucket.byToolCall) {
+ if (!bucket.tasks.has(taskId)) {
+ bucket.byToolCall.delete(dedupeKey);
+ }
+ }
+ }
+
+ /**
+ * Accessors always sweep the bucket they touch (so TTLs hold exactly for the
+ * data being read), while the all-buckets pass — needed only for idle-bucket
+ * eviction and untouched buckets — is throttled so a hot poll loop isn't
+ * O(total tasks server-wide) on every call.
+ */
+ private sweep(now: number): void {
+ if (now - this.lastGlobalSweepAt < GLOBAL_SWEEP_INTERVAL_MS) {
+ return;
+ }
+ this.lastGlobalSweepAt = now;
+ for (const [bucketKey, bucket] of this.buckets) {
+ if (now - bucket.lastAccess > IDLE_BUCKET_TTL_MS) {
+ this.buckets.delete(bucketKey);
+ continue;
+ }
+ this.sweepBucketTasks(bucket, now);
+ }
+ }
+
+ private getBucket(userId: string, conversationId: string, now: number): TaskBucket {
+ const bucketKey = this.key(userId, conversationId);
+ let bucket = this.buckets.get(bucketKey);
+ if (!bucket) {
+ bucket = { tasks: new Map(), byToolCall: new Map(), lastAccess: now };
+ this.buckets.set(bucketKey, bucket);
+ }
+ bucket.lastAccess = now;
+ return bucket;
+ }
+
+ /**
+ * Registers a task for a tool call. Returns the existing task (and
+ * `isNew: false`) only when the SAME run re-dispatched the same `toolCallId`
+ * (a resume/replay) — the caller must not start the work twice. Returns
+ * `atCapacity: true` when the per-conversation running cap is reached.
+ *
+ * The dedupe key includes `agentId` + `runId` because provider tool-call ids
+ * repeat across turns AND across agents in one run (e.g. `call_0` per
+ * response); keying on `toolCallId` alone would make a later turn's — or a
+ * second agent's — identically-named call collide with a prior (retained)
+ * task and hand back a stale/foreign result instead of executing.
+ */
+ create(params: {
+ userId: string;
+ conversationId: string;
+ toolCallId: string;
+ toolName: string;
+ runId?: string;
+ agentId?: string;
+ }): { task: BackgroundTask; isNew: boolean } | { atCapacity: true } {
+ const now = Date.now();
+ this.sweep(now);
+ const bucket = this.getBucket(params.userId, params.conversationId, now);
+ this.sweepBucketTasks(bucket, now);
+
+ const dedupeKey = `${params.agentId ?? ''}::${params.runId ?? ''}::${params.toolCallId}`;
+ const existingId = bucket.byToolCall.get(dedupeKey);
+ if (existingId) {
+ const existing = bucket.tasks.get(existingId);
+ if (existing) {
+ return { task: existing, isNew: false };
+ }
+ }
+
+ let running = 0;
+ for (const task of bucket.tasks.values()) {
+ if (task.status === 'running') {
+ running++;
+ }
+ }
+ /** Only *running* tasks gate dispatch. */
+ if (running >= MAX_RUNNING_PER_BUCKET) {
+ return { atCapacity: true };
+ }
+ /** The total-tasks cap bounds memory but must NOT block new work: evict the
+ * oldest SETTLED tasks to make room rather than rejecting (settled tasks
+ * aren't removed by polling, so 200 quick calls would otherwise block for
+ * up to the completed-TTL). Running is already capped, so room always frees. */
+ if (bucket.tasks.size >= MAX_TASKS_PER_BUCKET) {
+ const settledOldestFirst = [...bucket.tasks.values()]
+ .filter((t) => t.status !== 'running')
+ .sort((a, b) => a.createdAt - b.createdAt);
+ let toEvict = bucket.tasks.size - MAX_TASKS_PER_BUCKET + 1;
+ for (const stale of settledOldestFirst) {
+ if (toEvict <= 0) {
+ break;
+ }
+ bucket.tasks.delete(stale.id);
+ toEvict--;
+ }
+ }
+
+ const task: BackgroundTask = {
+ id: randomUUID(),
+ toolName: params.toolName,
+ toolCallId: params.toolCallId,
+ status: 'running',
+ createdAt: now,
+ updatedAt: now,
+ };
+ bucket.tasks.set(task.id, task);
+ bucket.byToolCall.set(dedupeKey, task.id);
+ return { task, isNew: true };
+ }
+
+ private update(
+ userId: string,
+ conversationId: string,
+ taskId: string,
+ patch: Partial<BackgroundTask>,
+ ): void {
+ const bucket = this.buckets.get(this.key(userId, conversationId));
+ const task = bucket?.tasks.get(taskId);
+ if (!task) {
+ return;
+ }
+ Object.assign(task, patch, { updatedAt: Date.now() });
+ }
+
+ complete(
+ userId: string,
+ conversationId: string,
+ taskId: string,
+ result: { content: unknown; artifact?: unknown },
+ ): void {
+ this.update(userId, conversationId, taskId, {
+ status: 'completed',
+ result: toStoredContent(result.content),
+ artifact: toStoredArtifact(taskId, result.artifact),
+ /** Marks that an artifact existed even after `claimArtifact` clears it,
+ * so re-polls keep the "produced an artifact" note. */
+ artifactDelivered: false,
+ });
+ }
+
+ /**
+ * Returns a completed task's artifact exactly once, marking it delivered and
+ * clearing it. The poll turn routes it to a live `toolEndCallback` so the
+ * artifact isn't lost with the finalized dispatch turn. If handing it to the
+ * callback throws synchronously, `restoreArtifact` puts it back so a later
+ * poll can retry. Note the callback's own persistence is fire-and-forget
+ * (failures are swallowed downstream), so delivery is at-most-once — the
+ * same semantics a foreground tool's artifact has.
+ */
+ claimArtifact(
+ userId: string,
+ conversationId: string,
+ taskId: string,
+ ): { toolName: string; artifact: unknown; content?: string } | undefined {
+ const bucket = this.buckets.get(this.key(userId, conversationId));
+ const task = bucket?.tasks.get(taskId);
+ if (!task || task.status !== 'completed' || task.artifact == null || task.artifactDelivered) {
+ return undefined;
+ }
+ const artifact = task.artifact;
+ task.artifactDelivered = true;
+ task.artifact = undefined;
+ return { toolName: task.toolName, artifact, content: task.result };
+ }
+
+ /**
+ * Puts a claimed artifact back after a synchronous delivery failure so the
+ * next poll retries it. No-op if the task was swept or already holds an
+ * artifact.
+ */
+ restoreArtifact(userId: string, conversationId: string, taskId: string, artifact: unknown): void {
+ const bucket = this.buckets.get(this.key(userId, conversationId));
+ const task = bucket?.tasks.get(taskId);
+ if (!task || task.artifact != null) {
+ return;
+ }
+ task.artifact = artifact;
+ task.artifactDelivered = false;
+ }
+
+ fail(userId: string, conversationId: string, taskId: string, error: string): void {
+ this.update(userId, conversationId, taskId, { status: 'error', error });
+ }
+
+ get(userId: string, conversationId: string, taskId: string): BackgroundTask | undefined {
+ const now = Date.now();
+ /** Sweep before returning so repeated polling of a known id can't keep an
+ * expired task (and its retained result) alive past the completed TTL. */
+ this.sweep(now);
+ const bucket = this.buckets.get(this.key(userId, conversationId));
+ if (!bucket) {
+ return undefined;
+ }
+ bucket.lastAccess = now;
+ this.sweepBucketTasks(bucket, now);
+ return bucket.tasks.get(taskId);
+ }
+
+ list(userId: string, conversationId: string): BackgroundTask[] {
+ const now = Date.now();
+ this.sweep(now);
+ const bucket = this.buckets.get(this.key(userId, conversationId));
+ if (!bucket) {
+ return [];
+ }
+ bucket.lastAccess = now;
+ this.sweepBucketTasks(bucket, now);
+ return [...bucket.tasks.values()].sort((a, b) => a.createdAt - b.createdAt);
+ }
+}
+
+export const backgroundTaskRegistry = new BackgroundTaskRegistryClass();
+
+/** Content for the synthetic ToolMessage returned when a call is backgrounded. */
+export function buildBackgroundHandleContent(task: BackgroundTask): string {
+ return JSON.stringify({
+ background_task_id: task.id,
+ tool: task.toolName,
+ status: task.status,
+ message: `Started "${task.toolName}" in the background. Call ${CHECK_BACKGROUND_TASK_NAME} with background_task_id "${task.id}" to check progress and retrieve the result; it persists on this server, so you may poll it later in this turn or in a following turn. Do not assume it has finished until you have polled and seen status "completed".`,
+ });
+}
+
+/** Content returned when the per-conversation background running cap is hit. */
+export function buildBackgroundCapacityContent(toolName: string): string {
+ return JSON.stringify({
+ status: 'rejected',
+ tool: toolName,
+ message: `Too many background tasks are already running in this conversation (limit ${MAX_RUNNING_PER_BUCKET}). Poll ${CHECK_BACKGROUND_TASK_NAME} to collect finished results before dispatching more, or run this call in the foreground.`,
+ });
+}
+
+/**
+ * Serializes a task for the poll tool. The list path (`includeResult: false`)
+ * returns metadata only — never the full `result` — so a status-list poll can't
+ * inject megabytes of retained tool output into the next model step. The full
+ * result is only returned when a specific `background_task_id` is requested.
+ */
+interface SerializedBackgroundTask {
+ background_task_id: string;
+ tool: string;
+ status: BackgroundTaskStatus;
+ /** Coarse 0..1: no intermediate progress exists, only running vs settled. */
+ progress: number;
+ result?: string;
+ result_available?: boolean;
+ result_chars?: number;
+ note?: string;
+ error?: string;
+}
+
+function resultFields(
+ task: BackgroundTask,
+ includeResult: boolean,
+): Pick<SerializedBackgroundTask, 'result' | 'result_available' | 'result_chars'> {
+ if (task.result === undefined) {
+ return {};
+ }
+ if (includeResult) {
+ return { result: task.result };
+ }
+ return { result_available: true, result_chars: task.result.length };
+}
+
+function serializeTask(
+ task: BackgroundTask,
+ { includeResult }: { includeResult: boolean },
+): SerializedBackgroundTask {
+ return {
+ background_task_id: task.id,
+ tool: task.toolName,
+ status: task.status,
+ progress: task.status === 'running' ? 0 : 1,
+ ...resultFields(task, includeResult),
+ ...(task.artifact != null || task.artifactDelivered === true
+ ? { note: 'The tool produced an artifact that is not included inline.' }
+ : {}),
+ ...(task.error !== undefined ? { error: task.error } : {}),
+ };
+}
+
+/** Executes a `check_background_task` call and returns the ToolMessage content. */
+export function runCheckBackgroundTask(params: {
+ userId: string;
+ conversationId: string;
+ args: unknown;
+}): string {
+ const { userId, conversationId } = params;
+ const rawId = coerceArgsObject(params.args)?.background_task_id;
+ const taskId = typeof rawId === 'string' && rawId.trim() !== '' ? rawId.trim() : undefined;
+
+ if (taskId) {
+ const task = backgroundTaskRegistry.get(userId, conversationId, taskId);
+ if (!task) {
+ return JSON.stringify({
+ status: 'not_found',
+ background_task_id: taskId,
+ message: 'No background task with that id exists in this conversation.',
+ });
+ }
+ return JSON.stringify(serializeTask(task, { includeResult: true }));
+ }
+
+ const tasks = backgroundTaskRegistry.list(userId, conversationId);
+ logger.debug(`[background] check_background_task listed ${tasks.length} task(s)`);
+ return JSON.stringify({
+ tasks: tasks.map((task) => serializeTask(task, { includeResult: false })),
+ });
+}
+
+/**
+ * When a `check_background_task` call targets a specific completed task that
+ * produced an artifact, returns that artifact once (marking it delivered) so the
+ * poll turn's live callback can persist it. Returns undefined for the list form,
+ * an unknown id, or an already-delivered/artifact-less task.
+ */
+export function claimBackgroundArtifact(params: {
+ userId: string;
+ conversationId: string;
+ args: unknown;
+}): { taskId: string; toolName: string; artifact: unknown; content?: string } | undefined {
+ const rawId = coerceArgsObject(params.args)?.background_task_id;
+ const taskId = typeof rawId === 'string' && rawId.trim() !== '' ? rawId.trim() : undefined;
+ if (!taskId) {
+ return undefined;
+ }
+ const claimed = backgroundTaskRegistry.claimArtifact(
+ params.userId,
+ params.conversationId,
+ taskId,
+ );
+ return claimed ? { taskId, ...claimed } : undefined;
+}
+
+/** Reverses a `claimBackgroundArtifact` after a failed delivery (see `restoreArtifact`). */
+export function restoreBackgroundArtifact(params: {
+ userId: string;
+ conversationId: string;
+ taskId: string;
+ artifact: unknown;
+}): void {
+ backgroundTaskRegistry.restoreArtifact(
+ params.userId,
+ params.conversationId,
+ params.taskId,
+ params.artifact,
+ );
+}
diff --git a/packages/api/src/agents/discovery.ts b/packages/api/src/agents/discovery.ts
index 33b981d141..40176185ec 100644
--- a/packages/api/src/agents/discovery.ts
+++ b/packages/api/src/agents/discovery.ts
@@ -96,6 +96,13 @@ export interface DiscoverConnectedAgentsParams {
* `set_memory` + `delete_memory` pair only when the parent run permits it.
*/
memoryAvailable?: InitializeAgentParams['memoryAvailable'];
+ /**
+ * Run-level `run_in_background` capability gate. Forwarded verbatim so a
+ * handoff/connected agent's own event-driven tools with
+ * `tool_options[tool].run_in_background` get the injected param + poll tool,
+ * matching how the same agent behaves when run as the primary.
+ */
+ backgroundToolsAvailable?: InitializeAgentParams['backgroundToolsAvailable'];
}
export interface DiscoverConnectedAgentsDeps {
@@ -165,6 +172,7 @@ export async function discoverConnectedAgents(
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
} = params;
@@ -270,6 +278,7 @@ export async function discoverConnectedAgents(
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
+ backgroundToolsAvailable,
statefulSessionsAvailable,
memoryAvailable,
},
diff --git a/packages/api/src/agents/handlers.background.spec.ts b/packages/api/src/agents/handlers.background.spec.ts
new file mode 100644
index 0000000000..861765dca1
--- /dev/null
+++ b/packages/api/src/agents/handlers.background.spec.ts
@@ -0,0 +1,526 @@
+import { z } from 'zod';
+import type { StructuredToolInterface } from '@librechat/agents/langchain/tools';
+import { CHECK_BACKGROUND_TASK_NAME } from './background';
+import { createToolExecuteHandler } from './handlers';
+
+interface BatchInput {
+ toolCalls: Array<{ id: string; name: string; args: Record<string, unknown> }>;
+ agentId: string;
+ configurable: Record<string, unknown>;
+ metadata: Record<string, unknown>;
+ resolve: (results: Array<{ content: string }>) => void;
+ reject: (error: Error) => void;
+}
+
+const flushMicrotasks = () => new Promise((resolve) => setImmediate(resolve));
+
+const makeSearchTool = (state: { calls: number; lastInput?: Record<string, unknown> }) =>
+ ({
+ name: 'search_mcp_docs',
+ description: 'search docs',
+ schema: z.object({ q: z.string() }),
+ invoke: async (input: Record<string, unknown>) => {
+ state.calls += 1;
+ state.lastInput = input;
+ return { content: `RESULT for ${String(input.q)}` };
+ },
+ }) as unknown as StructuredToolInterface;
+
+const buildConfig = (backgroundToolNames: string[] = ['search_mcp_docs']) => ({
+ req: { user: { id: 'exec_user' }, body: { conversationId: 'exec_convo' } },
+ backgroundToolNames,
+});
+
+const runBatch = async (
+ handler: ReturnType<typeof createToolExecuteHandler>,
+ input: Omit<BatchInput, 'resolve' | 'reject'>,
+): Promise<Array<{ content: string }>> => {
+ let out: Array<{ content: string }> = [];
+ await handler.handle('on_tool_execute', {
+ ...input,
+ resolve: (results: Array<{ content: string }>) => {
+ out = results;
+ },
+ reject: (error: Error) => {
+ throw error;
+ },
+ } as unknown as Parameters<typeof handler.handle>[1]);
+ return out;
+};
+
+describe('createToolExecuteHandler — background tool calls', () => {
+ it('returns a handle immediately, runs the tool once detached, and yields the result via check_background_task', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const searchTool = makeSearchTool(state);
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [searchTool] }),
+ });
+ const configurable = buildConfig();
+ const metadata = { thread_id: 'exec_convo' };
+
+ const dispatchResults = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_bg',
+ name: 'search_mcp_docs',
+ args: { q: 'librechat', run_in_background: true },
+ },
+ ],
+ agentId: 'agent_1',
+ configurable,
+ metadata,
+ });
+
+ expect(dispatchResults).toHaveLength(1);
+ const handle = JSON.parse(dispatchResults[0].content);
+ expect(handle.status).toBe('running');
+ expect(typeof handle.background_task_id).toBe('string');
+
+ await flushMicrotasks();
+ await flushMicrotasks();
+
+ // real tool ran exactly once, without the injected flag
+ expect(state.calls).toBe(1);
+ expect(state.lastInput).toEqual({ q: 'librechat' });
+
+ const pollResults = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_poll',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handle.background_task_id },
+ },
+ ],
+ agentId: 'agent_1',
+ configurable,
+ metadata,
+ });
+
+ const polled = JSON.parse(pollResults[0].content);
+ expect(polled.status).toBe('completed');
+ expect(polled.result).toContain('RESULT for librechat');
+ });
+
+ it('does not double-dispatch when the same tool call re-executes (resume/replay)', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const searchTool = makeSearchTool(state);
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [searchTool] }),
+ });
+ const configurable = buildConfig();
+ const metadata = { thread_id: 'exec_convo_dup' };
+ const toolCalls = [
+ { id: 'call_same', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
+ ];
+
+ const first = await runBatch(handler, { toolCalls, agentId: 'a', configurable, metadata });
+ await flushMicrotasks();
+ const second = await runBatch(handler, { toolCalls, agentId: 'a', configurable, metadata });
+ await flushMicrotasks();
+
+ const firstId = JSON.parse(first[0].content).background_task_id;
+ const secondId = JSON.parse(second[0].content).background_task_id;
+ expect(secondId).toBe(firstId);
+ expect(state.calls).toBe(1);
+ });
+
+ it('runs the tool synchronously when background is not requested', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const searchTool = makeSearchTool(state);
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [searchTool] }),
+ });
+ const configurable = buildConfig();
+ const metadata = { thread_id: 'exec_convo_sync' };
+
+ const results = await runBatch(handler, {
+ toolCalls: [{ id: 'call_sync', name: 'search_mcp_docs', args: { q: 'now' } }],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+
+ expect(state.calls).toBe(1);
+ expect(results[0].content).toContain('RESULT for now');
+ });
+
+ it('enforces the per-tool opt-in: a tool not in backgroundToolNames runs foreground even with the flag', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const searchTool = makeSearchTool(state);
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [searchTool] }),
+ });
+ // background enabled for the run, but for a DIFFERENT tool
+ const configurable = buildConfig(['some_other_tool']);
+ const metadata = { thread_id: 'exec_convo_gate' };
+
+ const results = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_gate', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+
+ // ran in the foreground; result is the tool output, not a background handle
+ expect(state.calls).toBe(1);
+ expect(results[0].content).toContain('RESULT for x');
+ });
+
+ it('never backgrounds an ephemeral request-scoped MCP tool: runs it foreground (no detached, leak-free)', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const ephemeralTool = {
+ name: 'search_mcp_docs',
+ description: 'search docs',
+ schema: z.object({ q: z.string() }),
+ // Tagged in createToolInstance for servers on a runtime-body-placeholder
+ // connection, which is torn down at request end.
+ mcpRequiresEphemeralConnection: true,
+ invoke: async (input: Record<string, unknown>) => {
+ state.calls += 1;
+ state.lastInput = input;
+ return { content: `RESULT for ${String(input.q)}` };
+ },
+ } as unknown as StructuredToolInterface;
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [ephemeralTool] }),
+ });
+ // background IS enabled for this tool, and the model asked to background it
+ const configurable = buildConfig();
+ const metadata = { thread_id: 'exec_convo_ephemeral' };
+
+ const results = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_eph', name: 'search_mcp_docs', args: { q: 'z', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+
+ // ran synchronously in the foreground: real output inline, not a handle, flag stripped
+ expect(state.calls).toBe(1);
+ expect(state.lastInput).toEqual({ q: 'z' });
+ expect(results[0].content).toContain('RESULT for z');
+ expect(results[0].content).not.toContain('background_task_id');
+ });
+
+ it('does not intercept a check_background_task-named tool when background is off for the run', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const collisionTool = {
+ name: CHECK_BACKGROUND_TASK_NAME,
+ description: 'a user MCP tool that happens to share the name',
+ schema: z.object({ q: z.string() }),
+ invoke: async (input: Record<string, unknown>) => {
+ state.calls += 1;
+ return { content: `REAL for ${String(input.q)}` };
+ },
+ } as unknown as StructuredToolInterface;
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [collisionTool] }),
+ });
+ const configurable = buildConfig([]); // background not active for this run
+ const metadata = { thread_id: 'exec_convo_collision' };
+
+ const results = await runBatch(handler, {
+ toolCalls: [{ id: 'call_collision', name: CHECK_BACKGROUND_TASK_NAME, args: { q: 'y' } }],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+
+ // the real tool ran; the host poll-tool shortcut did not swallow it
+ expect(state.calls).toBe(1);
+ expect(results[0].content).toContain('REAL for y');
+ });
+
+ it('strips run_in_background:false on a foreground call of a background-capable tool', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const searchTool = makeSearchTool(state);
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [searchTool] }),
+ });
+ const configurable = buildConfig(['search_mcp_docs']);
+ const metadata = { thread_id: 'exec_convo_falseflag' };
+
+ const results = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_false', name: 'search_mcp_docs', args: { q: 'z', run_in_background: false } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+
+ // ran in the foreground, and the injected flag never reached the real tool
+ expect(state.calls).toBe(1);
+ expect(state.lastInput).toEqual({ q: 'z' });
+ expect(results[0].content).toContain('RESULT for z');
+ });
+
+ it('delivers a backgrounded tool artifact on poll (live turn), not on the finalized dispatch turn', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const artifactTool = {
+ name: 'search_mcp_docs',
+ description: 'returns an artifact',
+ schema: z.object({ q: z.string() }),
+ invoke: async (input: Record<string, unknown>) => {
+ state.calls += 1;
+ return { content: `RESULT for ${String(input.q)}`, artifact: { files: ['a.png'] } };
+ },
+ } as unknown as StructuredToolInterface;
+ const toolEndCalls: Array<{ name?: string; artifact?: unknown }> = [];
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [artifactTool] }),
+ toolEndCallback: (async (data: { output?: { name?: string; artifact?: unknown } }) => {
+ toolEndCalls.push({ name: data.output?.name, artifact: data.output?.artifact });
+ }) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
+ });
+ const configurable = buildConfig(['search_mcp_docs']);
+ const metadata = { thread_id: 'exec_convo_artifact', run_id: 'run-artifact' };
+
+ const dispatch = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_art', name: 'search_mcp_docs', args: { q: 'img', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+ await flushMicrotasks();
+ await flushMicrotasks();
+
+ // the tool ran, but its artifact is NOT pushed through the finalized dispatch turn
+ expect(state.calls).toBe(1);
+ expect(toolEndCalls).toHaveLength(0);
+
+ const handleId = JSON.parse(dispatch[0].content).background_task_id;
+ const poll = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_poll',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_artifact', run_id: 'run-poll' },
+ });
+
+ // the poll turn delivers the artifact once, attributed to the original tool
+ expect(JSON.parse(poll[0].content).status).toBe('completed');
+ expect(toolEndCalls).toHaveLength(1);
+ expect(toolEndCalls[0]).toEqual({ name: 'search_mcp_docs', artifact: { files: ['a.png'] } });
+
+ // polling again does not re-deliver (idempotent)
+ await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_poll2',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_artifact', run_id: 'run-poll2' },
+ });
+ expect(toolEndCalls).toHaveLength(1);
+ });
+
+ it('scopes tasks by configurable user_id when req is absent (external service hosts)', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [makeSearchTool(state)] }),
+ });
+ const configurable = {
+ user_id: 'exec_user_external',
+ backgroundToolNames: ['search_mcp_docs'],
+ };
+ const metadata = { thread_id: 'exec_convo_external', run_id: 'run-external' };
+
+ const dispatch = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_ext', name: 'search_mcp_docs', args: { q: 'ping', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata,
+ });
+ await flushMicrotasks();
+ await flushMicrotasks();
+
+ const handleId = JSON.parse(dispatch[0].content).background_task_id;
+ const poll = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_ext_poll',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_external', run_id: 'run-external-poll' },
+ });
+ const polled = JSON.parse(poll[0].content);
+ expect(polled.status).toBe('completed');
+ expect(polled.result).toContain('RESULT for ping');
+
+ // a different user id cannot see the task (isolation is not conversation-only)
+ const foreign = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_foreign_poll',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable: { user_id: 'someone_else', backgroundToolNames: ['search_mcp_docs'] },
+ metadata: { thread_id: 'exec_convo_external', run_id: 'run-foreign' },
+ });
+ expect(JSON.parse(foreign[0].content).status).toBe('not_found');
+ });
+
+ it('errors immediately (like foreground) when a background-requested tool failed to load', async () => {
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [] }),
+ });
+ const results = (await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_missing', name: 'search_mcp_docs', args: { q: 'x', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable: buildConfig(['search_mcp_docs']),
+ metadata: { thread_id: 'exec_convo_missing', run_id: 'run-missing' },
+ })) as Array<{ content: string; status?: string; errorMessage?: string }>;
+
+ expect(results[0].status).toBe('error');
+ expect(results[0].errorMessage).toBe('Tool search_mcp_docs not found');
+ expect(results[0].content).not.toContain('background_task_id');
+ });
+
+ it('strips a run_in_background arg imitated onto a tool this agent never opted in', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [makeSearchTool(state)] }),
+ });
+ // background is enabled for the run via another tool; search_mcp_docs is NOT opted in
+ await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_foreign',
+ name: 'search_mcp_docs',
+ args: { q: 'hello', run_in_background: true },
+ },
+ ],
+ agentId: 'a',
+ configurable: buildConfig(['other_tool']),
+ metadata: { thread_id: 'exec_convo_foreign', run_id: 'run-foreign' },
+ });
+
+ expect(state.calls).toBe(1);
+ expect(state.lastInput).toEqual({ q: 'hello' });
+ });
+
+ it('forwards run_in_background untouched to a tool whose own schema declares it', async () => {
+ const state = { calls: 0 } as { calls: number; lastInput?: Record<string, unknown> };
+ const owningTool = {
+ name: 'owns_the_param',
+ description: 'declares run_in_background itself',
+ schema: z.object({ q: z.string(), run_in_background: z.boolean().optional() }),
+ invoke: async (input: Record<string, unknown>) => {
+ state.calls += 1;
+ state.lastInput = input;
+ return { content: 'OWNED' };
+ },
+ } as unknown as StructuredToolInterface;
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [owningTool] }),
+ });
+ await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_owned',
+ name: 'owns_the_param',
+ args: { q: 'hello', run_in_background: true },
+ },
+ ],
+ agentId: 'a',
+ configurable: buildConfig(['other_tool']),
+ metadata: { thread_id: 'exec_convo_owned', run_id: 'run-owned' },
+ });
+
+ expect(state.calls).toBe(1);
+ expect(state.lastInput).toEqual({ q: 'hello', run_in_background: true });
+ });
+
+ it('retries artifact delivery on the next poll when the callback fails (artifact not lost)', async () => {
+ const artifactTool = {
+ name: 'search_mcp_docs',
+ description: 'returns an artifact',
+ schema: z.object({ q: z.string() }),
+ invoke: async () => ({ content: 'RESULT', artifact: { files: ['a.png'] } }),
+ } as unknown as StructuredToolInterface;
+ const toolEndCalls: Array<{ name?: string; artifact?: unknown }> = [];
+ let failNextDelivery = true;
+ const handler = createToolExecuteHandler({
+ loadTools: async () => ({ loadedTools: [artifactTool] }),
+ toolEndCallback: (async (data: { output?: { name?: string; artifact?: unknown } }) => {
+ if (failNextDelivery) {
+ failNextDelivery = false;
+ throw new Error('transient storage failure');
+ }
+ toolEndCalls.push({ name: data.output?.name, artifact: data.output?.artifact });
+ }) as unknown as Parameters<typeof createToolExecuteHandler>[0]['toolEndCallback'],
+ });
+ const configurable = buildConfig(['search_mcp_docs']);
+
+ const dispatch = await runBatch(handler, {
+ toolCalls: [
+ { id: 'call_art', name: 'search_mcp_docs', args: { q: 'img', run_in_background: true } },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-artifact' },
+ });
+ await flushMicrotasks();
+ await flushMicrotasks();
+ const handleId = JSON.parse(dispatch[0].content).background_task_id;
+
+ // first poll: delivery fails, but the poll itself still succeeds
+ const poll1 = await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_poll',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-poll' },
+ });
+ expect(JSON.parse(poll1[0].content).status).toBe('completed');
+ expect(toolEndCalls).toHaveLength(0);
+
+ // second poll: the restored artifact is re-claimed and delivered
+ await runBatch(handler, {
+ toolCalls: [
+ {
+ id: 'call_poll2',
+ name: CHECK_BACKGROUND_TASK_NAME,
+ args: { background_task_id: handleId },
+ },
+ ],
+ agentId: 'a',
+ configurable,
+ metadata: { thread_id: 'exec_convo_art_retry', run_id: 'run-poll2' },
+ });
+ expect(toolEndCalls).toHaveLength(1);
+ expect(toolEndCalls[0]).toEqual({ name: 'search_mcp_docs', artifact: { files: ['a.png'] } });
+ });
+});
diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.ts
index 845fc6231c..a60581591a 100644
--- a/packages/api/src/agents/handlers.ts
+++ b/packages/api/src/agents/handlers.ts
@@ -15,14 +15,28 @@ import type { StructuredToolInterface } from '@librechat/agents/langchain/tools'
import type { CodeEnvRef } from 'librechat-data-provider';
import type { SkillFileRecord } from './skillFiles';
import type { ServerRequest } from '~/types';
+import {
+ backgroundTaskRegistry,
+ runCheckBackgroundTask,
+ claimBackgroundArtifact,
+ restoreBackgroundArtifact,
+ isBackgroundRequested,
+ hasRunInBackgroundArg,
+ stripRunInBackgroundArg,
+ buildBackgroundHandleContent,
+ buildBackgroundCapacityContent,
+ stripBackgroundFromToolDefinitions,
+ CHECK_BACKGROUND_TASK_NAME,
+ RUN_IN_BACKGROUND_ARG,
+} from './background';
import {
CREATE_FILE_TOOL_NAME,
EDIT_FILE_TOOL_NAME,
HOST_FILE_AUTHORING_ARTIFACT_KEY,
isCodeSessionToolName,
} from './tools';
+import { logAxiosError, runOutsideTracing, truncateMiddle } from '~/utils';
import { buildSkillPrimeMessage, SKILL_FILE_PREFIX } from './skills';
-import { logAxiosError, runOutsideTracing } from '~/utils';
import { parseFrontmatter } from '../skills/import';
import { cleanCodeToolOutput } from './cleanup';
import { primeSkillFiles } from './skillFiles';
@@ -275,22 +289,6 @@ type ToolInputSchemaKind = {
string: boolean;
};
-function truncateMiddle(value: string, maxChars: number): string {
- if (value.length <= maxChars) {
- return value;
- }
-
- const indicator = `\n\n... [truncated: ${value.length} chars exceeded ${maxChars} limit] ...\n\n`;
- const available = maxChars - indicator.length;
- if (available <= 0) {
- return value.slice(0, maxChars);
- }
-
- const headSize = Math.ceil(available * 0.7);
- const tailSize = available - headSize;
- return value.slice(0, headSize) + indicator + value.slice(value.length - tailSize);
-}
-
function stringifyThrownValue(error: unknown): string {
try {
return String(error);
@@ -1721,6 +1719,64 @@ function mergeActiveSkillNames(
return names.size > 0 ? names : undefined;
}
+/**
+ * True for MCP tools on an ephemeral request-scoped connection (runtime body
+ * placeholders), tagged in `createToolInstance`. Their connection is torn down
+ * at request end, so they must run in the foreground rather than be backgrounded.
+ */
+function toolRequiresEphemeralConnection(tool: StructuredToolInterface | undefined): boolean {
+ return (
+ (tool as (StructuredToolInterface & { mcpRequiresEphemeralConnection?: boolean }) | undefined)
+ ?.mcpRequiresEphemeralConnection === true
+ );
+}
+
+const EMPTY_BACKGROUND_TOOL_SET: ReadonlySet<string> = new Set();
+
+/**
+ * Authenticated user id for background-task scoping. The in-repo routes merge
+ * `req` into the tool-execute configurable, but external hosts of the exported
+ * OpenAI-compatible service inject their own `loadTools` and may not — fall
+ * back to the run configurable's user identity so tasks are never registered
+ * under an empty user id (which would collapse isolation to conversationId).
+ */
+function resolveBackgroundUserId(configurable: Record<string, unknown> | undefined): string {
+ const req = configurable?.req as ServerRequest | undefined;
+ if (req?.user?.id) {
+ return req.user.id;
+ }
+ const userId = configurable?.user_id;
+ if (typeof userId === 'string' && userId !== '') {
+ return userId;
+ }
+ const user = configurable?.user;
+ if (typeof user === 'string') {
+ return user;
+ }
+ const idFromUser = (user as { id?: string } | undefined)?.id;
+ return typeof idFromUser === 'string' ? idFromUser : '';
+}
+
+/**
+ * True when the tool's own schema declares `run_in_background` (zod shape or
+ * raw JSON schema), i.e. the parameter belongs to the tool rather than being
+ * host-injected — such a tool must receive the argument untouched.
+ */
+function toolDeclaresRunInBackgroundParam(tool: StructuredToolInterface): boolean {
+ const schema = (
+ tool as StructuredToolInterface & {
+ schema?: { shape?: Record<string, unknown>; properties?: Record<string, unknown> };
+ }
+ ).schema;
+ if (schema == null) {
+ return false;
+ }
+ return (
+ schema.shape?.[RUN_IN_BACKGROUND_ARG] != null ||
+ schema.properties?.[RUN_IN_BACKGROUND_ARG] != null
+ );
+}
+
function mergeToolConfigurables(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
@@ -3226,8 +3282,181 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
const authoringQueues = new Map<string, Promise<void>>();
const sandboxAuthoringContexts = new Map<string, SandboxSessionContext>();
+ /**
+ * Background tool calls. The set of tools that received the injected
+ * `run_in_background` param is threaded per-agent from `initializeAgent`
+ * via `configurable.backgroundToolNames` (a reliable channel, unlike
+ * `toolRegistry` which only reaches the executor for PTC/tool_search).
+ * A non-empty set is the exact condition under which the run registered
+ * the poll tool and the model could have been shown the param, so it
+ * also gates the `check_background_task` interception and enforces the
+ * per-tool opt-in (a tool not in the set never had the param).
+ */
+ const backgroundToolNames = mergedConfigurable?.backgroundToolNames as
+ | string[]
+ | undefined;
+ const backgroundEnabledForRun = (backgroundToolNames?.length ?? 0) > 0;
+ const backgroundToolSet: ReadonlySet<string> = backgroundEnabledForRun
+ ? new Set(backgroundToolNames)
+ : EMPTY_BACKGROUND_TOOL_SET;
+ const backgroundReq = backgroundEnabledForRun
+ ? (mergedConfigurable?.req as ServerRequest | undefined)
+ : undefined;
+ const backgroundUserId = backgroundEnabledForRun
+ ? resolveBackgroundUserId(mergedConfigurable)
+ : '';
+ const backgroundConversationId = backgroundEnabledForRun
+ ? (((metadata as Record<string, unknown>)?.thread_id as string | undefined) ??
+ (mergedConfigurable?.thread_id as string | undefined) ??
+ (backgroundReq?.body as { conversationId?: string } | undefined)?.conversationId ??
+ '')
+ : '';
+
+ /**
+ * Registers the task, returns a synthetic handle immediately, and
+ * runs the real tool as a floating promise whose result lands in the
+ * registry for `check_background_task` to collect. Idempotent by
+ * `toolCallId` so graph re-execution (resume/replay) never double-fires.
+ */
+ const backgroundRunId = (metadata as Record<string, unknown>)?.run_id as
+ | string
+ | undefined;
+ const dispatchBackgroundToolCall = (tc: ToolCallRequest): ToolExecuteResult => {
+ /** A tool that failed to load must error immediately (matching the
+ * foreground path) — a synthetic "started" handle would tell the
+ * model a side effect is in flight that never executed. */
+ const tool = toolMap.get(tc.name);
+ if (!tool) {
+ return {
+ toolCallId: tc.id,
+ status: 'error' as const,
+ content: '',
+ errorMessage: `Tool ${tc.name} not found`,
+ };
+ }
+ const created = backgroundTaskRegistry.create({
+ userId: backgroundUserId,
+ conversationId: backgroundConversationId,
+ toolCallId: tc.id,
+ toolName: tc.name,
+ /** Scope idempotency to the agent + run + turn so a later turn's
+ * or a second agent's repeated provider id (e.g. `call_0`)
+ * starts a fresh task instead of colliding. */
+ agentId,
+ runId: `${backgroundRunId ?? ''}:${tc.turn ?? ''}`,
+ });
+ if ('atCapacity' in created) {
+ return {
+ toolCallId: tc.id,
+ status: 'success' as const,
+ content: buildBackgroundCapacityContent(tc.name),
+ };
+ }
+ const { task, isNew } = created;
+ if (isNew) {
+ const strippedArgs = stripRunInBackgroundArg(tc.args);
+ void (async () => {
+ try {
+ const result = (await tool.invoke(normalizeToolInvokeArgs(strippedArgs, tool), {
+ toolCall: { id: tc.id, stepId: tc.stepId, turn: tc.turn },
+ configurable: mergedConfigurable,
+ metadata,
+ } as Record<string, unknown>)) as { content?: unknown; artifact?: unknown };
+ /** Hold any artifact (images, files, UI resources,
+ * citations) on the task instead of routing it through
+ * this dispatch turn's callback: a slow background call
+ * resolves after the turn finalized, when its
+ * artifactPromises are already awaited and the stream is
+ * closed, so that push would be silently dropped. The poll
+ * turn delivers it live in `check_background_task`. */
+ backgroundTaskRegistry.complete(
+ backgroundUserId,
+ backgroundConversationId,
+ task.id,
+ { content: result.content, artifact: result.artifact },
+ );
+ } catch (toolError) {
+ const { message } = getSafeToolError(toolError);
+ backgroundTaskRegistry.fail(
+ backgroundUserId,
+ backgroundConversationId,
+ task.id,
+ message,
+ );
+ }
+ })();
+ }
+ return {
+ toolCallId: tc.id,
+ status: 'success' as const,
+ content: buildBackgroundHandleContent(task),
+ };
+ };
+
const results: ToolExecuteResult[] = await Promise.all(
toolCalls.map(async (tc: ToolCallRequest) => {
+ if (backgroundEnabledForRun && tc.name === CHECK_BACKGROUND_TASK_NAME) {
+ const pollContent = runCheckBackgroundTask({
+ userId: backgroundUserId,
+ conversationId: backgroundConversationId,
+ args: tc.args,
+ });
+ /** Deliver a completed task's artifact through THIS live poll
+ * turn's callback (once): the tool's own turn finalized before
+ * the artifact resolved, so this is where it can be persisted. */
+ if (toolEndCallback) {
+ const pending = claimBackgroundArtifact({
+ userId: backgroundUserId,
+ conversationId: backgroundConversationId,
+ args: tc.args,
+ });
+ if (pending) {
+ try {
+ await toolEndCallback(
+ {
+ output: {
+ name: pending.toolName,
+ tool_call_id: tc.id,
+ content: pending.content,
+ artifact: pending.artifact,
+ },
+ },
+ (metadata ?? {}) as ToolEndCallbackMetadata,
+ );
+ } catch (callbackError) {
+ /** Only synchronous callback throws land here (e.g. a
+ * malformed artifact shape); the callback's downstream
+ * persistence is fire-and-forget, so a storage failure
+ * is at-most-once — the same semantics as a foreground
+ * artifact. */
+ restoreBackgroundArtifact({
+ userId: backgroundUserId,
+ conversationId: backgroundConversationId,
+ taskId: pending.taskId,
+ artifact: pending.artifact,
+ });
+ logger.warn(
+ '[background] toolEndCallback error delivering artifact on poll:',
+ callbackError,
+ );
+ }
+ }
+ }
+ return reportResult({
+ toolCallId: tc.id,
+ status: 'success' as const,
+ content: pollContent,
+ });
+ }
+
+ if (
+ backgroundToolSet.has(tc.name) &&
+ isBackgroundRequested(tc.args) &&
+ !toolRequiresEphemeralConnection(toolMap.get(tc.name))
+ ) {
+ return reportResult(dispatchBackgroundToolCall(tc));
+ }
+
const execute = async (
sandboxContext?: SandboxSessionContext,
): Promise<ToolExecuteResult> => {
@@ -3446,23 +3675,48 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
if (toolRegistry) {
const fileAuthoringToolNames =
getFileAuthoringToolNames(mergedConfigurable) ?? new Set<string>();
- const toolDefs: LCTool[] = Array.from(toolRegistry.values()).filter(
+ const filteredToolDefs: LCTool[] = Array.from(toolRegistry.values()).filter(
(t) =>
t.name !== Constants.PROGRAMMATIC_TOOL_CALLING &&
t.name !== Constants.BASH_PROGRAMMATIC_TOOL_CALLING &&
t.name !== Constants.TOOL_SEARCH &&
+ /* Host-only poll tool: implemented by the ON_TOOL_EXECUTE
+ * shortcut, not callable from PTC-generated code. */
+ t.name !== CHECK_BACKGROUND_TASK_NAME &&
!fileAuthoringToolNames.has(t.name),
);
+ /* PTC-generated calls don't go through the host background
+ * interceptor, so strip the injected `run_in_background`
+ * param from target schemas (the registry entries were
+ * mutated to include it) — mirrors the self-spawn path. */
+ const toolDefs = stripBackgroundFromToolDefinitions(
+ filteredToolDefs,
+ mergedConfigurable?.backgroundToolNames as string[] | undefined,
+ );
toolCallConfig.toolDefs = toolDefs;
toolCallConfig.toolMap = ptcToolMap ?? toolMap;
}
}
- const result = await tool.invoke(normalizeToolInvokeArgs(tc.args, tool), {
- toolCall: toolCallConfig,
- configurable: mergedConfigurable,
- metadata,
- } as Record<string, unknown>);
+ /** Strip the host-only `run_in_background` flag on foreground
+ * calls (the model may emit it as `false`, or imitate it from
+ * another agent's history on a tool this agent never opted
+ * in), so a strict MCP/action schema doesn't reject an
+ * undeclared argument. Only a tool whose own schema declares
+ * the parameter receives it. */
+ const foregroundArgs =
+ backgroundToolSet.has(tc.name) ||
+ (hasRunInBackgroundArg(tc.args) && !toolDeclaresRunInBackgroundParam(tool))
+ ? stripRunInBackgroundArg(tc.args)
+ : tc.args;
+ const result = await tool.invoke(
+ normalizeToolInvokeArgs(foregroundArgs, tool),
+ {
+ toolCall: toolCallConfig,
+ configurable: mergedConfigurable,
+ metadata,
+ } as Record<string, unknown>,
+ );
// Code-execution tools emit per-call boilerplate
// ("Note: ..." paragraphs and `| <annotation>` per-file
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index e6848d5897..6c52107427 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -50,7 +50,9 @@ import {
registerFileAuthoringTools,
isFileAuthoringToolDefinition,
} from './tools';
+import { normalizeServerName, requiresEphemeralUserConnection } from '~/mcp/utils';
import { registerMemoryTools, memoryToolUsageGuard } from './memory';
+import { applyBackgroundToolCalls } from './background';
import { filterFilesByEndpointConfig } from '~/files';
import { generateArtifactsPrompt } from '~/prompts';
import { getProviderConfig } from '~/endpoints';
@@ -256,6 +258,13 @@ export type InitializedAgent = Agent & {
toolDefinitions?: LCTool[];
/** Precomputed flag indicating if any tools have defer_loading enabled (for efficient runtime checks) */
hasDeferredTools?: boolean;
+ /**
+ * Names of this agent's tools that were injected with the `run_in_background`
+ * param (capability enabled AND per-tool opt-in AND eligible). Threaded to the
+ * tool executor via `configurable` so it can enforce the per-tool background
+ * opt-in and gate the `check_background_task` poll tool at execution time.
+ */
+ backgroundToolNames?: string[];
/** Whether the inline memory tools (`set_memory`/`delete_memory`) were
* registered for this agent. Authoritative LibreChat-only signal of the
* inline memory opt-in for the execution path, since some contexts hold the
@@ -405,6 +414,13 @@ export interface InitializeAgentParams {
skillAuthoringAvailable?: boolean;
/** Whether the code execution environment is available (execute_code capability enabled) */
codeEnvAvailable?: boolean;
+ /**
+ * Whether the `run_in_background` capability is enabled for this run. When
+ * true, tools the agent opted in via `tool_options[name].run_in_background`
+ * get a `run_in_background` schema param and the `check_background_task` poll
+ * tool is registered.
+ */
+ backgroundToolsAvailable?: boolean;
/** Whether stateful code sessions are available (stateful_code_sessions capability enabled) */
statefulSessionsAvailable?: boolean;
/** Whether inline memory tools are available (memory capability enabled, memory
@@ -1154,6 +1170,48 @@ export async function initializeAgent(
toolDefinitions = fileAuthoringResult.toolDefinitions;
}
+ /**
+ * Inject the `run_in_background` param into eligible opted-in tools and
+ * register the `check_background_task` poll tool. Runs after all built-in
+ * tool registration so the full, final `toolDefinitions` set is considered.
+ * Opt-in is per-tool via `tool_options` for both saved and ephemeral agents.
+ */
+ let backgroundToolNames: string[] | undefined;
+ if (params.backgroundToolsAvailable === true) {
+ /** Tool names embed `normalizeServerName(server)` (see MCP.js tool keys)
+ * while `mcpConfig` keys the original name, so index the ephemeral
+ * servers by their normalized form. */
+ const ephemeralServerNames = new Set<string>();
+ for (const [serverName, serverConfig] of Object.entries(req.config?.mcpConfig ?? {})) {
+ if (serverConfig != null && requiresEphemeralUserConnection(serverConfig)) {
+ ephemeralServerNames.add(normalizeServerName(serverName));
+ }
+ }
+ const backgroundResult = applyBackgroundToolCalls({
+ toolDefinitions,
+ toolRegistry,
+ toolOptions: agent.tool_options,
+ /** Tools of ephemeral request-scoped MCP servers (runtime body
+ * placeholders) never get the param: their connection dies at request
+ * end, so the executor would only downgrade the call to foreground.
+ * Unknown servers stay eligible — the executor's per-instance tag is
+ * the fail-safe for those. */
+ excludeTool: (toolName) => {
+ const delimiterIndex = toolName.indexOf(Constants.mcp_delimiter);
+ if (delimiterIndex < 0) {
+ return false;
+ }
+ return ephemeralServerNames.has(
+ toolName.slice(delimiterIndex + Constants.mcp_delimiter.length),
+ );
+ },
+ });
+ toolDefinitions = backgroundResult.toolDefinitions;
+ if (backgroundResult.backgroundToolNames.length > 0) {
+ backgroundToolNames = backgroundResult.backgroundToolNames;
+ }
+ }
+
/** Check for tool presence from either full instances or definitions (event-driven mode) */
const hasAgentTools = (structuredTools?.length ?? 0) > 0 || (toolDefinitions?.length ?? 0) > 0;
const providerTools = resolveProviderToolConflicts({
@@ -1309,6 +1367,7 @@ export async function initializeAgent(
userMCPAuthMap,
toolDefinitions,
hasDeferredTools,
+ backgroundToolNames,
actionsEnabled,
baseContextTokens,
memoryToolsRegistered: inlineMemoryRegistered,
diff --git a/packages/api/src/agents/load.ts b/packages/api/src/agents/load.ts
index a0192544da..1b4dbbca91 100644
--- a/packages/api/src/agents/load.ts
+++ b/packages/api/src/agents/load.ts
@@ -8,12 +8,14 @@ import {
} from 'librechat-data-provider';
import type {
AgentModelParameters,
+ AgentToolOptions,
TEphemeralAgent,
TModelSpec,
Agent,
} from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import { ASK_USER_QUESTION_TOOL_NAME } from '~/agents/hitl/askUserQuestionTool';
+import { synthesizeBackgroundToolOptions } from '~/agents/background';
import { requiresEphemeralUserConnection } from '~/mcp/utils';
import { getCustomEndpointConfig } from '~/app/config';
@@ -149,6 +151,14 @@ export async function loadEphemeralAgent(
tools,
};
+ const backgroundToolOptions: AgentToolOptions | undefined = synthesizeBackgroundToolOptions(
+ tools,
+ { ephemeralAgent, modelSpec },
+ );
+ if (backgroundToolOptions) {
+ result.tool_options = backgroundToolOptions;
+ }
+
if (ephemeralAgent?.artifacts) {
result.artifacts = ephemeralAgent.artifacts;
}
diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.ts
index 09b796cf8a..7d52001ef8 100644
--- a/packages/api/src/agents/openai/service.ts
+++ b/packages/api/src/agents/openai/service.ts
@@ -153,6 +153,13 @@ interface InitializeAgentParams {
* in-repo controllers; absent / `undefined` disables the feature.
*/
statefulSessionsAvailable?: boolean;
+ /**
+ * Whether the admin-level `run_in_background` capability is enabled.
+ * Gates `applyBackgroundToolCalls` in `initializeAgent` (the injected
+ * `run_in_background` param + the `check_background_task` poll tool);
+ * absent / `undefined` disables background tool calls on this route.
+ */
+ backgroundToolsAvailable?: boolean;
}
/**
@@ -445,23 +452,21 @@ export async function createAgentChatCompletion(
* use.
*/
const agentsConfig = (deps.appConfig?.endpoints as Record<string, unknown> | undefined)?.agents;
- const codeEnvAvailable =
+ const capabilityEnabled = (capability: AgentCapabilities): boolean | undefined =>
agentsConfig != null && typeof agentsConfig === 'object'
- ? ((agentsConfig as { capabilities?: string[] }).capabilities ?? []).includes(
- AgentCapabilities.execute_code,
- )
+ ? ((agentsConfig as { capabilities?: string[] }).capabilities ?? []).includes(capability)
: undefined;
+ const codeEnvAvailable = capabilityEnabled(AgentCapabilities.execute_code);
/** Mirror `codeEnvAvailable` for the stateful-session gate so an agent with
* `execute_code`, the app `stateful_code_sessions` capability, and its own
* builder opt-in resolves stateful sessions on this route too — otherwise
* `statefulCodeSessions` stays false and `createRun` never sends
* `toolExecution.sandbox`. */
- const statefulSessionsAvailable =
- agentsConfig != null && typeof agentsConfig === 'object'
- ? ((agentsConfig as { capabilities?: string[] }).capabilities ?? []).includes(
- AgentCapabilities.stateful_code_sessions,
- )
- : undefined;
+ const statefulSessionsAvailable = capabilityEnabled(AgentCapabilities.stateful_code_sessions);
+ /** Same gate as the in-repo controllers: without it, agents that opted
+ * tools in via tool_options.run_in_background silently lose the
+ * background param + poll tool on this route. */
+ const backgroundToolsAvailable = capabilityEnabled(AgentCapabilities.run_in_background);
// Initialize the agent first to check for disableStreaming
const initializedAgent = await deps.initializeAgent({
@@ -479,6 +484,7 @@ export async function createAgentChatCompletion(
isInitialAgent: true,
codeEnvAvailable,
statefulSessionsAvailable,
+ backgroundToolsAvailable,
});
// Determine if streaming is enabled (check both request and agent config)
diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts
index 9e551b09ac..b83003e806 100644
--- a/packages/api/src/agents/run.ts
+++ b/packages/api/src/agents/run.ts
@@ -35,6 +35,11 @@ import type { BaseMessage } from '@librechat/agents/langchain/messages';
import type { AppConfig, IUser } from '@librechat/data-schemas';
import type { SubagentUsageEvent } from '~/agents/usage';
import type * as t from '~/types';
+import {
+ CHECK_BACKGROUND_TASK_NAME,
+ stripBackgroundFromToolRegistry,
+ stripBackgroundFromToolDefinitions,
+} from '~/agents/background';
import {
ASK_USER_QUESTION_TOOL_NAME,
createAskUserQuestionTool,
@@ -331,6 +336,8 @@ type RunAgent = Omit<Agent, 'tools'> & {
toolDefinitions?: LCTool[];
/** Precomputed flag indicating if any tools have defer_loading enabled */
hasDeferredTools?: boolean;
+ /** Names of tools injected with the `run_in_background` param (excluded from eager execution). */
+ backgroundToolNames?: string[];
/**
* Per-agent codeenv gate set by `initializeAgent`: admin-level
* `execute_code` capability AND the agent actually requested
@@ -871,6 +878,14 @@ function buildSubagentConfigs(
if (allowSelf) {
const selfName = agentInput.name ?? agent.name ?? 'self';
countSubagentConfig(state);
+ /**
+ * Self-spawn reuses the parent's AgentInputs. When the parent has background
+ * tools, provide a sanitized copy so the isolated child — which runs the
+ * direct/child-graph path rather than the host background interceptor —
+ * doesn't advertise `run_in_background` / `check_background_task`. The
+ * resolver keeps a provided `agentInputs` even with `self: true`.
+ */
+ const hasBackground = (agent.backgroundToolNames?.length ?? 0) > 0;
configs.push({
self: true,
type: SELF_SUBAGENT_TYPE,
@@ -878,6 +893,21 @@ function buildSubagentConfigs(
description: `Spawn ${selfName} in an isolated context to handle a focused subtask. Verbose tool output stays in the child's context; only a summary returns.`,
/** Self-spawn reuses the parent's config, so mirror the parent's recursion limit. */
maxTurns: resolveSubagentMaxTurns(agentsEConfig, agent),
+ ...(hasBackground
+ ? {
+ agentInputs: {
+ ...agentInput,
+ toolDefinitions: stripBackgroundFromToolDefinitions(
+ agentInput.toolDefinitions,
+ agent.backgroundToolNames,
+ ),
+ toolRegistry: stripBackgroundFromToolRegistry(
+ agentInput.toolRegistry,
+ agent.backgroundToolNames,
+ ),
+ },
+ }
+ : {}),
});
}
@@ -913,6 +943,24 @@ function buildSubagentConfigs(
* source so children truly start fresh.
*/
const childInputs = toInput(child, { isSubagent: true });
+ /**
+ * A child reachable as a top-level/handoff agent is initialized WITH the
+ * background capability, then reused here as a subagent. Isolated child
+ * graphs run subagent tools without the host background dispatch/poll
+ * behavior, so strip the injected `run_in_background` param + the
+ * `check_background_task` def (defs AND registry) so the child doesn't
+ * advertise a background contract it can't honor. Mirrors the self-spawn path.
+ */
+ if ((child.backgroundToolNames?.length ?? 0) > 0) {
+ childInputs.toolDefinitions = stripBackgroundFromToolDefinitions(
+ childInputs.toolDefinitions,
+ child.backgroundToolNames,
+ );
+ childInputs.toolRegistry = stripBackgroundFromToolRegistry(
+ childInputs.toolRegistry,
+ child.backgroundToolNames,
+ );
+ }
/**
* Recursively resolve the child's own spawn targets so multi-level
* delegation (A → B → C) works. Without this, a child whose own
@@ -1409,6 +1457,16 @@ export async function createRun({
Constants.EXECUTE_CODE,
Constants.BASH_TOOL,
ASK_USER_QUESTION_TOOL_NAME,
+ /**
+ * Background-capable tools: eager execution could launch the detached
+ * task with speculative/partial args before the final tool call, and a
+ * background side effect (unlike a foreground eager mismatch) can't be
+ * canceled once dispatched. The poll tool is excluded for the same
+ * reason: collecting a task's artifact is a one-shot claim that must
+ * not fire from a speculative snapshot the SDK may later discard.
+ */
+ CHECK_BACKGROUND_TASK_NAME,
+ ...agents.flatMap((agent) => agent.backgroundToolNames ?? []),
],
},
// Let host file-authoring tools share the code-execution sandbox session so
diff --git a/packages/api/src/agents/validation.ts b/packages/api/src/agents/validation.ts
index 93699a0df7..23a3052382 100644
--- a/packages/api/src/agents/validation.ts
+++ b/packages/api/src/agents/validation.ts
@@ -289,16 +289,18 @@ export const graphEdgeSchema: z.ZodObject<
.transform((v) => (v === '' ? undefined : v)),
});
-/** Per-tool options schema (defer_loading, allowed_callers) */
+/** Per-tool options schema (defer_loading, allowed_callers, run_in_background) */
export const toolOptionsSchema: z.ZodObject<
{
defer_loading: z.ZodOptional<z.ZodBoolean>;
allowed_callers: z.ZodOptional<z.ZodArray<z.ZodEnum<['direct', 'code_execution']>, 'many'>>;
+ run_in_background: z.ZodOptional<z.ZodBoolean>;
},
'strip'
> = z.object({
defer_loading: z.boolean().optional(),
allowed_callers: z.array(z.enum(['direct', 'code_execution'])).optional(),
+ run_in_background: z.boolean().optional(),
});
/** Agent tool options - map of tool_id to tool options */
@@ -309,16 +311,19 @@ export const agentToolOptionsSchema: z.ZodOptional<
{
defer_loading: z.ZodOptional<z.ZodBoolean>;
allowed_callers: z.ZodOptional<z.ZodArray<z.ZodEnum<['direct', 'code_execution']>, 'many'>>;
+ run_in_background: z.ZodOptional<z.ZodBoolean>;
},
'strip',
z.ZodTypeAny,
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
},
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
}
>
>
@@ -625,16 +630,19 @@ export const agentBaseSchema: z.ZodObject<
allowed_callers: z.ZodOptional<
z.ZodArray<z.ZodEnum<['direct', 'code_execution']>, 'many'>
>;
+ run_in_background: z.ZodOptional<z.ZodBoolean>;
},
'strip',
z.ZodTypeAny,
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
},
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
}
>
>
@@ -972,16 +980,19 @@ export const agentCreateSchema: z.ZodObject<
allowed_callers: z.ZodOptional<
z.ZodArray<z.ZodEnum<['direct', 'code_execution']>, 'many'>
>;
+ run_in_background: z.ZodOptional<z.ZodBoolean>;
},
'strip',
z.ZodTypeAny,
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
},
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
}
>
>
@@ -1284,16 +1295,19 @@ export const agentUpdateSchema: z.ZodObject<
allowed_callers: z.ZodOptional<
z.ZodArray<z.ZodEnum<['direct', 'code_execution']>, 'many'>
>;
+ run_in_background: z.ZodOptional<z.ZodBoolean>;
},
'strip',
z.ZodTypeAny,
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
},
{
defer_loading?: boolean | undefined;
allowed_callers?: ('direct' | 'code_execution')[] | undefined;
+ run_in_background?: boolean | undefined;
}
>
>
diff --git a/packages/api/src/utils/text.ts b/packages/api/src/utils/text.ts
index 00e9e81d86..2d3977465a 100644
--- a/packages/api/src/utils/text.ts
+++ b/packages/api/src/utils/text.ts
@@ -98,3 +98,23 @@ export async function processTextWithTokenLimit({
wasTruncated: true,
};
}
+
+/**
+ * Truncates to `maxChars` keeping head and tail around an explicit marker, so
+ * the consumer (usually a model) can tell the content was cut and by how much.
+ */
+export function truncateMiddle(value: string, maxChars: number): string {
+ if (value.length <= maxChars) {
+ return value;
+ }
+
+ const indicator = `\n\n... [truncated: ${value.length} chars exceeded ${maxChars} limit] ...\n\n`;
+ const available = maxChars - indicator.length;
+ if (available <= 0) {
+ return value.slice(0, maxChars);
+ }
+
+ const headSize = Math.ceil(available * 0.7);
+ const tailSize = available - headSize;
+ return value.slice(0, headSize) + indicator + value.slice(value.length - tailSize);
+}
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 0be0481846..203ac3b023 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -578,6 +578,7 @@ export enum AgentCapabilities {
tools = 'tools',
chain = 'chain',
ocr = 'ocr',
+ run_in_background = 'run_in_background',
}
export const defaultAssistantsVersion = {
@@ -2728,6 +2729,8 @@ export enum Constants {
BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
/** Subagent spawn tool name (must match `@librechat/agents` `Constants.SUBAGENT`). */
SUBAGENT = 'subagent',
+ /** Poll tool for retrieving the status/result of a backgrounded tool call. */
+ CHECK_BACKGROUND_TASK = 'check_background_task',
}
/** Maximum explicit subagent hops allowed from any root agent at runtime. */
diff --git a/packages/data-provider/src/models.ts b/packages/data-provider/src/models.ts
index 5249ac8f8f..5f48fed349 100644
--- a/packages/data-provider/src/models.ts
+++ b/packages/data-provider/src/models.ts
@@ -55,6 +55,12 @@ export type TModelSpec = {
memory?: boolean;
/** Equip the spec's ephemeral agent with the `ask_user_question` HITL tool. */
askUserQuestion?: boolean;
+ /**
+ * Let the model dispatch this spec's eligible tool calls in the background
+ * (poll results via `check_background_task`). Requires the `run_in_background`
+ * agent capability to be enabled by the admin.
+ */
+ runInBackground?: boolean;
artifacts?: string | boolean;
mcpServers?: string[];
skills?: boolean | string[];
@@ -90,6 +96,7 @@ export const tModelSpecSchema = z.object({
executeCode: z.boolean().optional(),
memory: z.boolean().optional(),
askUserQuestion: z.boolean().optional(),
+ runInBackground: z.boolean().optional(),
artifacts: z.union([z.string(), z.boolean()]).optional(),
mcpServers: z.array(z.string()).optional(),
skills: z.union([z.boolean(), z.array(z.string())]).optional(),
diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.ts
index e711a580a5..9c9b8cb71e 100644
--- a/packages/data-provider/src/types.ts
+++ b/packages/data-provider/src/types.ts
@@ -111,6 +111,12 @@ export type TEphemeralAgent = {
memory?: boolean;
/** Equip the ephemeral agent with the `ask_user_question` HITL tool. */
ask_user_question?: boolean;
+ /**
+ * Let the model dispatch this ephemeral agent's eligible tool calls in the
+ * background (poll results via `check_background_task`). Requires the
+ * `run_in_background` agent capability to be enabled by the admin.
+ */
+ run_in_background?: boolean;
};
export type TPayload = Partial<TMessage> &
diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.ts
index 349776b34f..2882ac96d1 100644
--- a/packages/data-provider/src/types/assistants.ts
+++ b/packages/data-provider/src/types/assistants.ts
@@ -238,6 +238,13 @@ export type ToolOptions = {
* @default ['direct']
*/
allowed_callers?: AllowedCaller[];
+ /**
+ * If true (and the `run_in_background` capability is enabled), the tool's
+ * schema gains a `run_in_background` boolean so the model can dispatch the
+ * call detached and poll its result via `check_background_task`.
+ * @default false
+ */
+ run_in_background?: boolean;
};
/**