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 Execution Toggles for Actions & Plugin Tools (#14407)

Danny Avila4b113697b5ea
diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.js
index 51fed9159b..485694dc52 100644
--- a/api/server/services/ToolService.js
+++ b/api/server/services/ToolService.js
@@ -35,6 +35,7 @@ const {
getSafeErrorMetadata,
isContentFilterError,
isFileAuthoringToolDefinition,
+ normalizeActionToolName,
ASK_USER_QUESTION_TOOL_NAME,
splitMCPToolKey,
buildServerNameAliases,
@@ -53,6 +54,7 @@ const {
ErrorTypes,
ContentTypes,
imageGenTools,
+ AuthTypeEnum,
EModelEndpoint,
EToolResources,
isActionTool,
@@ -202,32 +204,6 @@ const prepareActionSnapshotForTools = async ({ agentId, toolNames, filters, decr
return { storedActions, actionSets };
};
-/**
- * Collapse every `actionDomainSeparator` sequence in the encoded-domain
- * suffix of a fully-qualified action tool name to an underscore. Agents
- * can store tool names in the raw `domainParser(..., true)` output,
- * which for short hostnames is a `---`-separated string (e.g.
- * `medium---com`). The lookup maps below are always keyed with the
- * `_`-collapsed domain, so every read must normalize that suffix or
- * short-hostname tools silently fail to resolve.
- *
- * The operationId portion (everything before the last `actionDelimiter`)
- * is deliberately left untouched: `openapiToFunction` preserves hyphens
- * in generated operationIds, so two specs can legitimately produce
- * operationIds that differ only in hyphens-vs-underscores (e.g.
- * `get_foo---bar` vs `get_foo_bar`). Collapsing the operationId would
- * merge those into a single map slot and silently drop one tool.
- */
-const normalizeActionToolName = (toolName) => {
- const delimiterIndex = toolName.lastIndexOf(actionDelimiter);
- if (delimiterIndex === -1) {
- return toolName;
- }
- const prefixEnd = delimiterIndex + actionDelimiter.length;
- const encodedDomain = toolName.slice(prefixEnd);
- return toolName.slice(0, prefixEnd) + encodedDomain.replace(domainSeparatorRegex, '_');
-};
-
/**
* Populate a `toolToAction` map with one slot per fully-qualified tool
* name (`<operationId><actionDelimiter><encoded-domain>`). Both the new
@@ -1208,14 +1184,19 @@ async function loadToolDefinitionsWrapper({
for (const sig of functionSignatures) {
const toolName = `${sig.name}${actionDelimiter}${normalizedDomain}`;
const legacyToolName = `${sig.name}${actionDelimiter}${legacyNormalized}`;
- if (!normalizedToolNames.has(toolName) && !normalizedToolNames.has(legacyToolName)) {
+ const matchesCurrentName = normalizedToolNames.has(toolName);
+ const matchesLegacyName = normalizedToolNames.has(legacyToolName);
+ if (!matchesCurrentName && !matchesLegacyName) {
continue;
}
definitions.push({
- name: toolName,
+ /** Keep the selected legacy spelling when that is the only match so
+ * persisted tool_options resolve against the emitted definition. */
+ name: matchesCurrentName ? toolName : legacyToolName,
description: sig.description,
parameters: sig.parameters,
+ oauth: action.metadata.auth?.type === AuthTypeEnum.OAuth,
});
}
}
@@ -1223,28 +1204,34 @@ async function loadToolDefinitionsWrapper({
return definitions;
};
- let { toolDefinitions, toolRegistry, hasDeferredTools, mcpToolAliases, mcpResolution } =
- await loadToolDefinitions(
- {
- userId: req.user.id,
- agentId: agent.id,
- tools: defsFilteredTools,
- toolOptions: agent.tool_options,
- deferredToolsEnabled,
- programmaticToolsEnabled,
- codeExecutionEnabled,
- provider: agent.provider,
- mcpServerNames,
- rawServerNames: mcpRawServerNames,
- accessibleServerNames: defsAccessibleServerNames,
- },
- {
- isBuiltInTool,
- getOrFetchMCPServerTools,
- refreshMCPServerTools,
- getActionToolDefinitions,
- },
- );
+ let {
+ toolDefinitions,
+ toolRegistry,
+ hasDeferredTools,
+ mcpToolAliases,
+ mcpResolution,
+ oauthActionToolNames,
+ } = await loadToolDefinitions(
+ {
+ userId: req.user.id,
+ agentId: agent.id,
+ tools: defsFilteredTools,
+ toolOptions: agent.tool_options,
+ deferredToolsEnabled,
+ programmaticToolsEnabled,
+ codeExecutionEnabled,
+ provider: agent.provider,
+ mcpServerNames,
+ rawServerNames: mcpRawServerNames,
+ accessibleServerNames: defsAccessibleServerNames,
+ },
+ {
+ isBuiltInTool,
+ getOrFetchMCPServerTools,
+ refreshMCPServerTools,
+ getActionToolDefinitions,
+ },
+ );
/** OAuth discovery must not reconnect (or prompt for) a server whose
* definitions the collision filter deliberately rejected. */
@@ -1338,6 +1325,7 @@ async function loadToolDefinitionsWrapper({
hasDeferredTools = reloadResult.hasDeferredTools;
mcpToolAliases = reloadResult.mcpToolAliases;
mcpResolution = reloadResult.mcpResolution;
+ oauthActionToolNames = reloadResult.oauthActionToolNames;
}
}
@@ -1454,6 +1442,7 @@ async function loadToolDefinitionsWrapper({
mcpToolAliases,
actionsEnabled,
primedCodeFiles,
+ oauthActionToolNames,
};
}
diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.js
index 8bf3126d72..4281e485ea 100644
--- a/api/server/services/__tests__/ToolService.spec.js
+++ b/api/server/services/__tests__/ToolService.spec.js
@@ -3348,6 +3348,41 @@ describe('ToolService - Action Capability Gating', () => {
expect(callArgs.requestBuilder.path).toBe('/echo');
});
+ it('definitions-only loading emits the selected legacy action name', async () => {
+ mockLoadActionSets.mockResolvedValue([actionA]);
+ const legacyToolName = `echoMessage${actionDelimiter}${LEGACY_ENCODED_DOMAIN}`;
+ const capabilities = [AgentCapabilities.tools, AgentCapabilities.actions];
+ const req = createMockReq(capabilities);
+ mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
+
+ mockLoadToolDefinitions.mockImplementationOnce(async (_options, dependencies) => {
+ const definitions = await dependencies.getActionToolDefinitions('agent_legacy', [
+ legacyToolName,
+ ]);
+ expect(definitions).toEqual([
+ expect.objectContaining({ name: legacyToolName, description: 'Mock echoMessage' }),
+ ]);
+ return {
+ toolDefinitions: definitions,
+ toolRegistry: new Map(),
+ hasDeferredTools: false,
+ };
+ });
+
+ await loadAgentTools({
+ req,
+ res: {},
+ agent: {
+ id: 'agent_legacy',
+ tools: [legacyToolName],
+ tool_options: { [legacyToolName]: { run_in_background: true } },
+ },
+ definitionsOnly: true,
+ });
+
+ expect(mockLoadToolDefinitions).toHaveBeenCalledTimes(1);
+ });
+
it('loadAgentTools distinguishes operationIds that differ only by `---` vs `_`', async () => {
// `openapiToFunction` uses the user-supplied operationId verbatim
// and only sanitizes the synthetic `<method>_<path>` fallback, and
diff --git a/client/src/components/SidePanel/Agents/Actions/Background.tsx b/client/src/components/SidePanel/Agents/Actions/Background.tsx
new file mode 100644
index 0000000000..f8a405535c
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Actions/Background.tsx
@@ -0,0 +1,92 @@
+import { useMemo } from 'react';
+import {
+ AuthTypeEnum,
+ actionDelimiter,
+ openapiToFunction,
+ validateAndParseOpenAPISpec,
+} from 'librechat-data-provider';
+import { useAgentCapabilities, useGetAgentsConfig } from '~/hooks';
+import { useGetExpandedAgentByIdQuery } from '~/data-provider';
+import { useAgentPanelContext } from '~/Providers';
+import { isEphemeralAgent } from '~/common';
+import Background from '../Background';
+
+/** "Background execution" switch for a saved action — opts every operation of
+ * the action into background dispatch via `tool_options`. Hidden for OAuth
+ * actions: their calls can block on an interactive login prompt that a
+ * detached run could never surface (the server excludes them regardless). */
+export default function ActionBackground({ agentId }: { agentId: string }) {
+ const { action } = useAgentPanelContext();
+ const { agentsConfig } = useGetAgentsConfig();
+ const { backgroundToolsEnabled } = useAgentCapabilities(agentsConfig?.capabilities);
+ const { data: agent } = useGetExpandedAgentByIdQuery(agentId, {
+ enabled: backgroundToolsEnabled && action != null && !isEphemeralAgent(agentId),
+ });
+
+ /** The agent's `actions` entries are `${encodedDomain}_action_${action_id}`,
+ * so the saved encoded domain is recoverable without re-implementing the
+ * server's domain encoding. The domain alone is NOT enough to identify this
+ * action's tools: two actions may share a hostname, and their operations
+ * then share the suffix. Narrow by this spec's own operation ids, falling
+ * back to the suffix only when no other action shares the domain. */
+ const actionToolIds = useMemo(() => {
+ const actionId = action?.action_id;
+ if (!actionId || !agent) {
+ return [];
+ }
+ let domain = '';
+ const domainCounts = new Map<string, number>();
+ for (const entry of agent.actions ?? []) {
+ const idx = entry.indexOf(actionDelimiter);
+ if (idx < 1) {
+ continue;
+ }
+ const entryDomain = entry.slice(0, idx);
+ domainCounts.set(entryDomain, (domainCounts.get(entryDomain) ?? 0) + 1);
+ if (entry.slice(idx + actionDelimiter.length) === actionId) {
+ domain = entryDomain;
+ }
+ }
+ if (!domain) {
+ return [];
+ }
+
+ const sharesDomain = (domainCounts.get(domain) ?? 0) > 1;
+ const suffix = `${actionDelimiter}${domain}`;
+ const domainTools = (agent.tools ?? []).filter((tool) => tool.endsWith(suffix));
+ const spec = action?.metadata.raw_spec;
+ const parsed = spec ? validateAndParseOpenAPISpec(spec) : undefined;
+ if (!parsed?.spec) {
+ return sharesDomain ? [] : domainTools;
+ }
+ const functionSignatures = openapiToFunction(parsed.spec).functionSignatures;
+ const operationIds = new Set(functionSignatures.map((sig) => sig.name));
+ const backgroundOperationIds = new Set(
+ functionSignatures
+ .filter((sig) => sig.parameters.properties.run_in_background == null)
+ .map((sig) => sig.name),
+ );
+ const ownTools = domainTools.filter((tool) =>
+ operationIds.has(tool.slice(0, tool.length - suffix.length)),
+ );
+ if (ownTools.length === 0) {
+ return sharesDomain ? [] : domainTools;
+ }
+ return ownTools.filter((tool) =>
+ backgroundOperationIds.has(tool.slice(0, tool.length - suffix.length)),
+ );
+ }, [action?.action_id, action?.metadata.raw_spec, agent]);
+
+ if (action?.metadata.auth?.type === AuthTypeEnum.OAuth) {
+ return null;
+ }
+
+ return (
+ <Background
+ toolIds={actionToolIds}
+ switchId="action-background-tools"
+ labelKey="com_ui_tool_background"
+ infoKey="com_nav_info_tool_background"
+ />
+ );
+}
diff --git a/client/src/components/SidePanel/Agents/Actions/__tests__/Background.spec.tsx b/client/src/components/SidePanel/Agents/Actions/__tests__/Background.spec.tsx
new file mode 100644
index 0000000000..a97f6d0d7d
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Actions/__tests__/Background.spec.tsx
@@ -0,0 +1,183 @@
+import '@testing-library/jest-dom/extend-expect';
+import { AuthTypeEnum } from 'librechat-data-provider';
+import { useForm, FormProvider, useWatch } from 'react-hook-form';
+import { render, screen, fireEvent } from '@testing-library/react';
+import type { Action, Agent } from 'librechat-data-provider';
+import type { ReactNode } from 'react';
+import type { AgentForm } from '~/common';
+import ActionBackground from '../Background';
+
+let mockBackgroundEnabled = true;
+let mockAction: Partial<Action> | undefined;
+let mockAgent: Partial<Agent> | undefined;
+
+jest.mock('~/hooks', () => ({
+ useLocalize: () => (key: string) => key,
+ useGetAgentsConfig: () => ({ agentsConfig: undefined }),
+ useAgentCapabilities: () => ({ backgroundToolsEnabled: mockBackgroundEnabled }),
+}));
+jest.mock('~/Providers', () => ({
+ useAgentPanelContext: () => ({ action: mockAction }),
+}));
+jest.mock('~/data-provider', () => ({
+ useGetExpandedAgentByIdQuery: () => ({ data: mockAgent }),
+}));
+
+function OptionsProbe() {
+ const value = useWatch<AgentForm>({ name: 'tool_options' });
+ return <span data-testid="options">{JSON.stringify(value ?? null)}</span>;
+}
+
+function renderActionBackground(defaultValues: Partial<AgentForm> = {}) {
+ function Wrapper({ children }: { children: ReactNode }) {
+ const methods = useForm<AgentForm>({ defaultValues: defaultValues as AgentForm });
+ return (
+ <FormProvider {...methods}>
+ {children}
+ <OptionsProbe />
+ </FormProvider>
+ );
+ }
+
+ return render(<ActionBackground agentId="agent_abc" />, { wrapper: Wrapper });
+}
+
+describe('ActionBackground', () => {
+ beforeEach(() => {
+ mockBackgroundEnabled = true;
+ mockAction = { action_id: 'act123', metadata: {} };
+ mockAgent = {
+ id: 'agent_abc',
+ tools: [
+ 'getWeather_action_weather---com',
+ 'getForecast_action_weather---com',
+ 'sendMail_action_mail---com',
+ 'web_search',
+ ],
+ actions: ['weather---com_action_act123', 'mail---com_action_act456'],
+ };
+ });
+
+ test('toggling opts in every operation of this action and no other tools', () => {
+ renderActionBackground();
+ const switchEl = screen.getByTestId('action-background-tools');
+ expect(switchEl).not.toBeChecked();
+
+ fireEvent.click(switchEl);
+ const options = JSON.parse(screen.getByTestId('options').textContent ?? 'null');
+ expect(options).toEqual({
+ 'getWeather_action_weather---com': { run_in_background: true },
+ getWeather_action_weather_com: { run_in_background: true },
+ 'getForecast_action_weather---com': { run_in_background: true },
+ getForecast_action_weather_com: { run_in_background: true },
+ });
+ });
+
+ test('reflects enabled when one operation is already opted in', () => {
+ renderActionBackground({
+ tool_options: { 'getForecast_action_weather---com': { run_in_background: true } },
+ });
+ expect(screen.getByTestId('action-background-tools')).toBeChecked();
+ });
+
+ test('opts in only the selected action when two actions share a hostname', () => {
+ mockAgent = {
+ id: 'agent_abc',
+ tools: [
+ 'getWeather_action_api---example---com',
+ 'sendMail_action_api---example---com',
+ 'web_search',
+ ],
+ actions: ['api---example---com_action_act123', 'api---example---com_action_act456'],
+ };
+ mockAction = {
+ action_id: 'act123',
+ metadata: {
+ raw_spec: JSON.stringify({
+ openapi: '3.0.0',
+ info: { title: 'Weather', version: '1.0.0' },
+ servers: [{ url: 'https://api.example.com' }],
+ paths: {
+ '/weather': {
+ get: { operationId: 'getWeather', responses: { '200': { description: 'ok' } } },
+ },
+ },
+ }),
+ },
+ };
+
+ renderActionBackground();
+ fireEvent.click(screen.getByTestId('action-background-tools'));
+ const options = JSON.parse(screen.getByTestId('options').textContent ?? 'null');
+ expect(options).toEqual({
+ 'getWeather_action_api---example---com': { run_in_background: true },
+ getWeather_action_api_example_com: { run_in_background: true },
+ });
+ });
+
+ test('hides rather than guesses when a shared-hostname spec cannot be parsed', () => {
+ mockAgent = {
+ id: 'agent_abc',
+ tools: ['getWeather_action_api---example---com', 'sendMail_action_api---example---com'],
+ actions: ['api---example---com_action_act123', 'api---example---com_action_act456'],
+ };
+ mockAction = { action_id: 'act123', metadata: {} };
+
+ renderActionBackground();
+ expect(screen.queryByTestId('action-background-tools')).toBeNull();
+ });
+
+ test('hidden for OAuth actions', () => {
+ mockAction = { action_id: 'act123', metadata: { auth: { type: AuthTypeEnum.OAuth } } };
+ renderActionBackground();
+ expect(screen.queryByTestId('action-background-tools')).toBeNull();
+ });
+
+ test('hidden when every operation owns the run_in_background parameter', () => {
+ mockAgent = {
+ id: 'agent_abc',
+ tools: ['getWeather_action_weather---com'],
+ actions: ['weather---com_action_act123'],
+ };
+ mockAction = {
+ action_id: 'act123',
+ metadata: {
+ raw_spec: JSON.stringify({
+ openapi: '3.0.0',
+ info: { title: 'Weather', version: '1.0.0' },
+ servers: [{ url: 'https://weather.com' }],
+ paths: {
+ '/weather': {
+ get: {
+ operationId: 'getWeather',
+ parameters: [
+ {
+ name: 'run_in_background',
+ in: 'query',
+ schema: { type: 'boolean' },
+ },
+ ],
+ responses: { '200': { description: 'ok' } },
+ },
+ },
+ },
+ }),
+ },
+ };
+
+ renderActionBackground();
+ expect(screen.queryByTestId('action-background-tools')).toBeNull();
+ });
+
+ test('hidden when the action is not registered on the agent', () => {
+ mockAction = { action_id: 'act999', metadata: {} };
+ renderActionBackground();
+ expect(screen.queryByTestId('action-background-tools')).toBeNull();
+ });
+
+ test('hidden when the background capability is off', () => {
+ mockBackgroundEnabled = false;
+ renderActionBackground();
+ expect(screen.queryByTestId('action-background-tools')).toBeNull();
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/AgentSelect.tsx b/client/src/components/SidePanel/Agents/AgentSelect.tsx
index 4bea8c1416..08449d6fa8 100644
--- a/client/src/components/SidePanel/Agents/AgentSelect.tsx
+++ b/client/src/components/SidePanel/Agents/AgentSelect.tsx
@@ -8,6 +8,7 @@ import type { UseMutationResult, QueryObserverResult } from '@tanstack/react-que
import type { TAgentCapabilities, AgentForm } from '~/common';
import { cn, createProviderOption, processAgentOption, getDefaultAgentFormValues } from '~/utils';
import { useLocalize, useAgentDefaultPermissionLevel } from '~/hooks';
+import { mergeDirtyToolsWithServerActions } from './agentTools';
import { useListAgentsQuery } from '~/data-provider';
const keys = new Set(Object.keys(defaultAgentFormValues));
@@ -27,7 +28,17 @@ function AgentSelect({
}) {
const localize = useLocalize();
const lastSelectedAgent = useRef<string | null>(null);
- const { control, reset } = useFormContext();
+ const {
+ control,
+ getValues,
+ reset,
+ setValue,
+ /** Subscribing dirtyFields is required for reset({ keepDirtyValues: true })
+ * to preserve edits when an action mutation refreshes the agent query. */
+ formState: { dirtyFields },
+ } = useFormContext();
+ const dirtyFieldsRef = useRef(dirtyFields);
+ dirtyFieldsRef.current = dirtyFields;
const permissionLevel = useAgentDefaultPermissionLevel();
const { data: agents = null } = useListAgentsQuery(
@@ -46,7 +57,7 @@ function AgentSelect({
);
const resetAgentForm = useCallback(
- (fullAgent: Agent) => {
+ (fullAgent: Agent, preserveDirtyValues = false) => {
const isGlobal = fullAgent.isPublic ?? false;
const update = {
...fullAgent,
@@ -168,9 +179,16 @@ function AgentSelect({
formValues.skills_enabled = true;
}
- reset(formValues);
+ const mergedDirtyTools =
+ preserveDirtyValues && dirtyFieldsRef.current.tools != null
+ ? mergeDirtyToolsWithServerActions(getValues('tools') ?? [], agentTools)
+ : undefined;
+ reset(formValues, { keepDirtyValues: preserveDirtyValues });
+ if (mergedDirtyTools != null) {
+ setValue('tools', mergedDirtyTools, { shouldDirty: true });
+ }
},
- [reset],
+ [getValues, reset, setValue],
);
const onSelect = useCallback(
@@ -207,7 +225,7 @@ function AgentSelect({
useEffect(() => {
if (agentQuery.data && agentQuery.isSuccess) {
- resetAgentForm(agentQuery.data);
+ resetAgentForm(agentQuery.data, true);
}
}, [agentQuery.data, agentQuery.isSuccess, resetAgentForm]);
diff --git a/client/src/components/SidePanel/Agents/Background.tsx b/client/src/components/SidePanel/Agents/Background.tsx
new file mode 100644
index 0000000000..054e9318e2
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Background.tsx
@@ -0,0 +1,90 @@
+import { useCallback } from 'react';
+import { useFormContext, useWatch } from 'react-hook-form';
+import { normalizeActionToolName } from 'librechat-data-provider';
+import {
+ Switch,
+ HoverCard,
+ HoverCardPortal,
+ HoverCardContent,
+ HoverCardTrigger,
+ CircleHelpIcon,
+} from '@librechat/client';
+import type { TranslationKeys } from '~/hooks/useLocalize';
+import type { AgentForm } from '~/common';
+import { useAgentCapabilities, useGetAgentsConfig, useLocalize } from '~/hooks';
+import { withBooleanOption } from '~/hooks/Agents/useMCPToolOptions';
+import { ESide } from '~/common';
+
+interface Props {
+ toolIds: string[];
+ switchId: string;
+ labelKey: TranslationKeys;
+ infoKey: TranslationKeys;
+}
+
+/** Shared "Background execution" switch — opts the given tool ids into
+ * background dispatch via `tool_options`. Reflects enabled when ANY id is
+ * opted in, mirroring the server, which honors each id independently and
+ * expands grouped ids (e.g. the code pair) across the group. */
+export default function Background({ toolIds, switchId, labelKey, infoKey }: Props) {
+ const localize = useLocalize();
+ const { agentsConfig } = useGetAgentsConfig();
+ const { backgroundToolsEnabled } = useAgentCapabilities(agentsConfig?.capabilities);
+ const { control, getValues, setValue } = useFormContext<AgentForm>();
+ const toolOptions = useWatch({ control, name: 'tool_options' });
+ const enabled = toolIds.some((toolId) => {
+ const normalized = normalizeActionToolName(toolId);
+ const normalizedValue = toolOptions?.[normalized]?.run_in_background;
+ if (normalized !== toolId && normalizedValue != null) {
+ return normalizedValue;
+ }
+ return toolOptions?.[toolId]?.run_in_background === true;
+ });
+
+ const handleChange = useCallback(
+ (value: boolean) => {
+ let updated = getValues('tool_options') || {};
+ for (const toolId of toolIds) {
+ const normalized = normalizeActionToolName(toolId);
+ const aliases = normalized === toolId ? [toolId] : [toolId, normalized];
+ for (const alias of aliases) {
+ updated = withBooleanOption(updated, alias, 'run_in_background', value);
+ }
+ }
+ setValue('tool_options', updated, { shouldDirty: true });
+ },
+ [toolIds, getValues, setValue],
+ );
+
+ if (!backgroundToolsEnabled || toolIds.length === 0) {
+ return null;
+ }
+
+ return (
+ <HoverCard openDelay={50}>
+ <div className="flex items-center justify-between">
+ <div className="flex items-center space-x-2">
+ <div className="text-sm">{localize(labelKey)}</div>
+ <HoverCardTrigger>
+ <CircleHelpIcon className="h-4 w-4 text-text-tertiary" />
+ </HoverCardTrigger>
+ </div>
+ <HoverCardPortal>
+ <HoverCardContent side={ESide.Top} className="w-80">
+ <div className="space-y-2">
+ <p className="text-sm text-text-secondary">{localize(infoKey)}</p>
+ </div>
+ </HoverCardContent>
+ </HoverCardPortal>
+ <Switch
+ id={switchId}
+ checked={enabled}
+ onCheckedChange={handleChange}
+ className="ml-4"
+ data-testid={switchId}
+ aria-label={localize(labelKey)}
+ />
+ </div>
+ </HoverCard>
+ );
+}
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ToolSection.spec.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ToolSection.spec.tsx
new file mode 100644
index 0000000000..a599afc81b
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ToolSection.spec.tsx
@@ -0,0 +1,60 @@
+import '@testing-library/jest-dom/extend-expect';
+import { useForm, FormProvider } from 'react-hook-form';
+import { render, screen } from '@testing-library/react';
+import type { TPlugin } from 'librechat-data-provider';
+import type { ReactNode } from 'react';
+import type { ToolItem } from '../../items/types';
+import type { AgentForm } from '~/common';
+import ToolSection from '../sections/ToolSection';
+
+jest.mock('~/hooks', () => ({
+ useLocalize: () => (key: string) => key,
+ useGetAgentsConfig: () => ({ agentsConfig: undefined }),
+ useAgentCapabilities: () => ({ backgroundToolsEnabled: true }),
+}));
+jest.mock('librechat-data-provider/react-query', () => ({
+ useUpdateUserPluginsMutation: () => ({ mutate: jest.fn(), isLoading: false }),
+}));
+jest.mock('@librechat/client', () => ({
+ ...jest.requireActual('@librechat/client'),
+ useToastContext: () => ({ showToast: jest.fn() }),
+}));
+jest.mock('~/components/Plugins/Store/PluginAuthForm', () => ({
+ __esModule: true,
+ default: () => <div />,
+}));
+
+function toolItem(id: string): ToolItem {
+ return {
+ kind: 'tool',
+ id,
+ name: id,
+ description: 'A tool',
+ iconKey: 'tool',
+ plugin: { pluginKey: id, name: id, authConfig: [] } as unknown as TPlugin,
+ };
+}
+
+function renderSection(item: ToolItem) {
+ function Wrapper({ children }: { children: ReactNode }) {
+ const methods = useForm<AgentForm>({ defaultValues: {} as AgentForm });
+ return <FormProvider {...methods}>{children}</FormProvider>;
+ }
+
+ return render(<ToolSection item={item} />, { wrapper: Wrapper });
+}
+
+describe('ToolSection background switch', () => {
+ test('renders the switch for a background-eligible plugin tool', () => {
+ renderSection(toolItem('wolfram'));
+ expect(screen.getByTestId('tool-background')).toBeInTheDocument();
+ });
+
+ test('does not render the switch for image generation tools', () => {
+ renderSection(toolItem('dalle'));
+ expect(screen.queryByTestId('tool-background')).toBeNull();
+
+ renderSection(toolItem('image_gen_oai'));
+ expect(screen.queryByTestId('tool-background')).toBeNull();
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ActionSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ActionSection.tsx
index 5d34c3ad4e..f62a70fa9d 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ActionSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ActionSection.tsx
@@ -1,5 +1,6 @@
import { useEffect } from 'react';
import type { ActionItem } from '../../items/types';
+import ActionBackground from '../../../Actions/Background';
import { useAgentPanelContext } from '~/Providers';
import { NEW_ACTION_ID } from '../../items/types';
import ActionEditor from '../../ActionEditor';
@@ -20,7 +21,8 @@ export default function ActionSection({ item, agentId, onClose }: Props) {
}, [isCreate, item.action, setAction]);
return (
- <div className="flex min-h-0 flex-1 flex-col">
+ <div className="flex min-h-0 flex-1 flex-col gap-4">
+ {!isCreate && <ActionBackground agentId={agentId} />}
<ActionEditor
agentId={agentId}
onClose={onClose}
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 86e9dd4fa2..228764e550 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/ToolSection.tsx
@@ -1,6 +1,7 @@
import { useState } from 'react';
import { CheckCircle2 } from 'lucide-react';
import { useFormContext } from 'react-hook-form';
+import { imageGenTools } from 'librechat-data-provider';
import { Button, useToastContext } from '@librechat/client';
import { useUpdateUserPluginsMutation } from 'librechat-data-provider/react-query';
import type { TError, TPluginAction } from 'librechat-data-provider';
@@ -8,12 +9,19 @@ import type { ToolItem } from '../../items/types';
import type { AgentForm } from '~/common';
import PluginAuthForm from '~/components/Plugins/Store/PluginAuthForm';
import { pluginNeedsAuth } from '../../items/auth';
+import Background from '../../../Background';
import { useLocalize } from '~/hooks';
interface Props {
item: ToolItem;
}
+/** Client mirror of the server's image-gen background exclusion
+ * (`EXCLUDED_BACKGROUND_TOOL_NAMES`): artifact-first tools whose files can't
+ * attach to an already-saved turn never get the switch. */
+const isBackgroundEligibleTool = (toolId: string): boolean =>
+ !imageGenTools.has(toolId) && toolId !== 'image_gen_oai' && toolId !== 'image_edit_oai';
+
export default function ToolSection({ item }: Props) {
const localize = useLocalize();
const { showToast } = useToastContext();
@@ -94,6 +102,14 @@ export default function ToolSection({ item }: Props) {
onSubmit={handleSubmit}
/>
)}
+ {isBackgroundEligibleTool(item.id) && (
+ <Background
+ toolIds={[item.id]}
+ switchId="tool-background"
+ labelKey="com_ui_tool_background"
+ infoKey="com_nav_info_tool_background"
+ />
+ )}
</div>
);
}
diff --git a/client/src/components/SidePanel/Agents/__tests__/Background.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/Background.spec.tsx
new file mode 100644
index 0000000000..ad3a0da0ea
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/__tests__/Background.spec.tsx
@@ -0,0 +1,133 @@
+import '@testing-library/jest-dom/extend-expect';
+import { useForm, FormProvider, useWatch } from 'react-hook-form';
+import { render, screen, fireEvent } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import type { AgentForm } from '~/common';
+import Background from '../Background';
+
+let mockBackgroundEnabled = true;
+jest.mock('~/hooks', () => ({
+ useLocalize: () => (key: string) => key,
+ useGetAgentsConfig: () => ({ agentsConfig: undefined }),
+ useAgentCapabilities: () => ({ backgroundToolsEnabled: mockBackgroundEnabled }),
+}));
+
+function OptionsProbe() {
+ const value = useWatch<AgentForm>({ name: 'tool_options' });
+ return <span data-testid="options">{JSON.stringify(value ?? null)}</span>;
+}
+
+function renderBackground(toolIds: string[], defaultValues: Partial<AgentForm> = {}) {
+ function Wrapper({ children }: { children: ReactNode }) {
+ const methods = useForm<AgentForm>({ defaultValues: defaultValues as AgentForm });
+ return (
+ <FormProvider {...methods}>
+ {children}
+ <OptionsProbe />
+ </FormProvider>
+ );
+ }
+
+ return render(
+ <Background
+ toolIds={toolIds}
+ switchId="bg-switch"
+ labelKey="com_ui_tool_background"
+ infoKey="com_nav_info_tool_background"
+ />,
+ { wrapper: Wrapper },
+ );
+}
+
+describe('Background switch', () => {
+ beforeEach(() => {
+ mockBackgroundEnabled = true;
+ });
+
+ test('hidden when the background capability is off', () => {
+ mockBackgroundEnabled = false;
+ renderBackground(['wolfram']);
+ expect(screen.queryByTestId('bg-switch')).toBeNull();
+ });
+
+ test('hidden when there are no tool ids to opt in', () => {
+ renderBackground([]);
+ expect(screen.queryByTestId('bg-switch')).toBeNull();
+ });
+
+ test('reflects enabled when ANY grouped id is opted in', () => {
+ renderBackground(['execute_code', 'bash_tool'], {
+ tool_options: { bash_tool: { run_in_background: true } },
+ });
+ expect(screen.getByTestId('bg-switch')).toBeChecked();
+ });
+
+ test('toggling writes every grouped id and clears entries on disable', () => {
+ renderBackground(['execute_code', 'bash_tool']);
+ const switchEl = screen.getByTestId('bg-switch');
+ expect(switchEl).not.toBeChecked();
+
+ fireEvent.click(switchEl);
+ expect(switchEl).toBeChecked();
+ const enabled = JSON.parse(screen.getByTestId('options').textContent ?? 'null');
+ expect(enabled).toEqual({
+ execute_code: { run_in_background: true },
+ bash_tool: { run_in_background: true },
+ });
+
+ fireEvent.click(switchEl);
+ expect(switchEl).not.toBeChecked();
+ const disabled = JSON.parse(screen.getByTestId('options').textContent ?? 'null');
+ expect(disabled).toEqual({});
+ });
+
+ test('preserves unrelated per-tool options when toggling', () => {
+ renderBackground(['wolfram'], {
+ tool_options: { search_mcp_docs: { defer_loading: true } },
+ });
+ fireEvent.click(screen.getByTestId('bg-switch'));
+ const options = JSON.parse(screen.getByTestId('options').textContent ?? 'null');
+ expect(options).toEqual({
+ search_mcp_docs: { defer_loading: true },
+ wolfram: { run_in_background: true },
+ });
+ });
+
+ test('reconciles raw and normalized action aliases when enabling', () => {
+ const rawToolId = 'getPerson_action_swapi---tech';
+ const normalizedToolId = 'getPerson_action_swapi_tech';
+ renderBackground([rawToolId], {
+ tool_options: {
+ [rawToolId]: { run_in_background: true },
+ [normalizedToolId]: { defer_loading: true, run_in_background: false },
+ },
+ });
+
+ const switchEl = screen.getByTestId('bg-switch');
+ expect(switchEl).not.toBeChecked();
+ fireEvent.click(switchEl);
+
+ expect(JSON.parse(screen.getByTestId('options').textContent ?? 'null')).toEqual({
+ [rawToolId]: { run_in_background: true },
+ [normalizedToolId]: { defer_loading: true, run_in_background: true },
+ });
+ });
+
+ test('clears both action aliases when disabling', () => {
+ const rawToolId = 'getPerson_action_swapi---tech';
+ const normalizedToolId = 'getPerson_action_swapi_tech';
+ renderBackground([rawToolId], {
+ tool_options: {
+ [normalizedToolId]: { defer_loading: true, run_in_background: true },
+ },
+ });
+
+ const switchEl = screen.getByTestId('bg-switch');
+ expect(switchEl).toBeChecked();
+ fireEvent.click(switchEl);
+
+ expect(JSON.parse(screen.getByTestId('options').textContent ?? 'null')).toEqual({
+ [normalizedToolId]: { defer_loading: true },
+ });
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/__tests__/agentTools.spec.ts b/client/src/components/SidePanel/Agents/__tests__/agentTools.spec.ts
new file mode 100644
index 0000000000..631b48816a
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/__tests__/agentTools.spec.ts
@@ -0,0 +1,21 @@
+import { mergeDirtyToolsWithServerActions } from '../agentTools';
+
+describe('mergeDirtyToolsWithServerActions', () => {
+ it('preserves dirty non-action choices and replaces action registrations', () => {
+ expect(
+ mergeDirtyToolsWithServerActions(
+ ['local_plugin', 'removed_action_old---example---com'],
+ ['server_plugin', 'added_action_new---example---com'],
+ ),
+ ).toEqual(['local_plugin', 'added_action_new---example---com']);
+ });
+
+ it('does not duplicate a server action registration', () => {
+ expect(
+ mergeDirtyToolsWithServerActions(
+ [],
+ ['get_action_api---example---com', 'get_action_api---example---com'],
+ ),
+ ).toEqual(['get_action_api---example---com']);
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/agentTools.ts b/client/src/components/SidePanel/Agents/agentTools.ts
new file mode 100644
index 0000000000..9d3806d4c5
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/agentTools.ts
@@ -0,0 +1,20 @@
+import { isActionTool } from 'librechat-data-provider';
+
+/**
+ * Keeps unsaved non-action tool choices while accepting the server's canonical
+ * action registrations after an adjacent action create/update mutation.
+ */
+export function mergeDirtyToolsWithServerActions(
+ dirtyTools: readonly string[],
+ serverTools: readonly string[],
+): string[] {
+ const merged = dirtyTools.filter((tool) => !isActionTool(tool));
+ const seen = new Set(merged);
+ for (const tool of serverTools) {
+ if (isActionTool(tool) && !seen.has(tool)) {
+ merged.push(tool);
+ seen.add(tool);
+ }
+ }
+ return merged;
+}
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 1b16c3ed04..1843c97b12 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -554,6 +554,7 @@
"com_nav_info_smooth_streaming": "When enabled, newly streamed words fade in smoothly for the latest response. This is purely visual — it does not delay token delivery — and is disabled automatically when your device prefers reduced motion.",
"com_nav_info_stateful_sessions": "When enabled, this agent uses the dedicated stateful Code API instead of the default stateless service. Files, installed packages, and working state usually carry over between runs. The workspace may occasionally reset, so save anything important under /mnt/data. Requires Code Interpreter and the app-level stateful sessions capability.",
"com_nav_info_stateful_code_environment": "Choose who shares this agent's stateful workspace. This does not share live files with stateless code sessions.",
+ "com_nav_info_tool_background": "When enabled, the model can run this tool in the background: the conversation continues immediately while the tool runs, and the model retrieves the result later with the background task tool. Requires the app-level background tools capability.",
"com_nav_info_user_name_display": "When enabled, the username of the sender will be shown above each message you send. When disabled, you will only see \"You\" above your messages.",
"com_nav_keep_screen_awake": "Keep screen awake during response generation",
"com_nav_lang_arabic": "العربية",
@@ -2279,6 +2280,7 @@
"com_ui_token_exchange_method": "Token Exchange Method",
"com_ui_token_url": "Token URL",
"com_ui_tokens": "tokens",
+ "com_ui_tool_background": "Background execution",
"com_ui_tool_collection_prefix": "A collection of tools from",
"com_ui_tool_credentials_saved": "Credentials saved",
"com_ui_tool_failed": "failed",
diff --git a/packages/api/src/actions/tools.spec.ts b/packages/api/src/actions/tools.spec.ts
index 2b4747de64..e0c18f611e 100644
--- a/packages/api/src/actions/tools.spec.ts
+++ b/packages/api/src/actions/tools.spec.ts
@@ -2,6 +2,7 @@ jest.mock(
'librechat-data-provider',
() => ({
actionDelimiter: '_action_',
+ normalizeActionToolName: (toolName: string) => toolName,
validateAndParseOpenAPISpec: (specString: string) => {
const spec = JSON.parse(specString) as { paths?: Record<string, unknown> };
return {
diff --git a/packages/api/src/actions/tools.ts b/packages/api/src/actions/tools.ts
index 2647d5cde5..89c96c019a 100644
--- a/packages/api/src/actions/tools.ts
+++ b/packages/api/src/actions/tools.ts
@@ -1,5 +1,7 @@
import { actionDelimiter, validateAndParseOpenAPISpec } from 'librechat-data-provider';
+export { normalizeActionToolName } from 'librechat-data-provider';
+
export type ActionToolLike = {
function?: {
name?: string;
diff --git a/packages/api/src/agents/background.spec.ts b/packages/api/src/agents/background.spec.ts
index 810b2a2750..cb73053bcf 100644
--- a/packages/api/src/agents/background.spec.ts
+++ b/packages/api/src/agents/background.spec.ts
@@ -237,6 +237,88 @@ describe('applyBackgroundToolCalls', () => {
).toBeUndefined();
});
+ it('resolves an action opt-in stored with the raw `---` domain against the collapsed def name', () => {
+ /** Agents persist `swapi---tech`; the runtime def is named `swapi_tech`. */
+ const defs = [mcpDef('getPerson_action_swapi_tech')];
+ const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
+ const result = applyBackgroundToolCalls({
+ toolDefinitions: defs,
+ toolRegistry: registry,
+ toolOptions: { 'getPerson_action_swapi---tech': { run_in_background: true } },
+ });
+ expect(result.backgroundToolNames).toEqual(['getPerson_action_swapi_tech']);
+ expect(registry.has(CHECK_BACKGROUND_TASK_NAME)).toBe(true);
+ });
+
+ it('merges a raw action opt-in into an existing normalized option entry', () => {
+ const defs = [mcpDef('getPerson_action_swapi_tech')];
+ const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
+ const result = applyBackgroundToolCalls({
+ toolDefinitions: defs,
+ toolRegistry: registry,
+ toolOptions: {
+ 'getPerson_action_swapi---tech': { run_in_background: true },
+ getPerson_action_swapi_tech: { defer_loading: true },
+ },
+ });
+ expect(result.backgroundToolNames).toEqual(['getPerson_action_swapi_tech']);
+ });
+
+ it('keeps an explicit normalized action background option authoritative', () => {
+ const defs = [mcpDef('getPerson_action_swapi_tech')];
+ const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
+ const result = applyBackgroundToolCalls({
+ toolDefinitions: defs,
+ toolRegistry: registry,
+ toolOptions: {
+ 'getPerson_action_swapi---tech': { run_in_background: true },
+ getPerson_action_swapi_tech: { run_in_background: false },
+ },
+ });
+ expect(result.backgroundToolNames).toEqual([]);
+ });
+
+ it('does not collapse hyphens in the operationId when normalizing an action key', () => {
+ const defs = [
+ mcpDef('get_foo---bar_action_swapi_tech'),
+ mcpDef('get_foo_bar_action_swapi_tech'),
+ ];
+ const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
+ const result = applyBackgroundToolCalls({
+ toolDefinitions: defs,
+ toolRegistry: registry,
+ toolOptions: { 'get_foo---bar_action_swapi---tech': { run_in_background: true } },
+ });
+ expect(result.backgroundToolNames).toEqual(['get_foo---bar_action_swapi_tech']);
+ });
+
+ it('injects an opted-in action tool but not one the OAuth excludeTool rejects', () => {
+ const oauthActionNames = new Set(['sendMail_action_mail---example---com']);
+ const defs = [
+ mcpDef('getWeather_action_weather---com'),
+ mcpDef('sendMail_action_mail---example---com'),
+ ];
+ const registry: LCToolRegistry = new Map(defs.map((d) => [d.name, { ...d }]));
+ const result = applyBackgroundToolCalls({
+ toolDefinitions: defs,
+ toolRegistry: registry,
+ toolOptions: {
+ 'getWeather_action_weather---com': { run_in_background: true },
+ 'sendMail_action_mail---example---com': { run_in_background: true },
+ },
+ excludeTool: (name) => oauthActionNames.has(name),
+ });
+ expect(result.backgroundToolNames).toEqual(['getWeather_action_weather---com']);
+ const oauthDef = result.toolDefinitions.find(
+ (d) => d.name === 'sendMail_action_mail---example---com',
+ );
+ expect(
+ (oauthDef?.parameters as { properties?: Record<string, unknown> }).properties?.[
+ RUN_IN_BACKGROUND_ARG
+ ],
+ ).toBeUndefined();
+ });
+
it('skips a non-object (string-input) schema without rewriting it', () => {
const defs = [{ name: 'legacy_tool', parameters: { type: 'string' } } as unknown as LCTool];
const result = applyBackgroundToolCalls({
diff --git a/packages/api/src/agents/background.ts b/packages/api/src/agents/background.ts
index 1dde2b5654..079ae3ff62 100644
--- a/packages/api/src/agents/background.ts
+++ b/packages/api/src/agents/background.ts
@@ -61,6 +61,7 @@ import { SubagentTaskOwnerUnavailableError } from './subagentTaskRouting';
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 { normalizeActionToolName } from '~/actions/tools';
import { truncateMiddle } from '~/utils';
/** Argument the model sets on a tool call to dispatch it in the background. */
@@ -125,6 +126,36 @@ const EXCLUDED_BACKGROUND_TOOL_NAMES: ReadonlySet<string> = new Set<string>([
'image_edit_oai',
]);
+/**
+ * Agents persist action tool names with the raw encoded domain (`---` for short
+ * hostnames), while the runtime definitions those names must match against are
+ * always `_`-collapsed. The builder writes `tool_options` keyed by the persisted
+ * name, so alias every action-shaped key to its normalized form; without this
+ * the opt-in silently never resolves for short-hostname actions. Merge the raw
+ * background option into any normalized entry while keeping an explicit
+ * normalized background value authoritative.
+ */
+function expandActionToolOptions(toolOptions: AgentToolOptions): AgentToolOptions {
+ let expanded: AgentToolOptions | undefined;
+ for (const [name, options] of Object.entries(toolOptions)) {
+ const normalized = normalizeActionToolName(name);
+ const runInBackground = options?.run_in_background;
+ if (
+ normalized === name ||
+ runInBackground == null ||
+ toolOptions[normalized]?.run_in_background != null
+ ) {
+ continue;
+ }
+ expanded = expanded ?? { ...toolOptions };
+ expanded[normalized] = {
+ ...toolOptions[normalized],
+ run_in_background: runInBackground,
+ };
+ }
+ return expanded ?? toolOptions;
+}
+
/**
* Whether a tool may be dispatched in the background. Handoff tools
* (`lc_transfer_to_*`) run through the direct path and are excluded by prefix.
@@ -466,7 +497,8 @@ export function applyBackgroundToolCalls(params: {
*/
excludeTool?: (toolName: string) => boolean;
}): { toolDefinitions: LCTool[]; backgroundToolNames: string[] } {
- const { toolRegistry, toolOptions, capabilityToolNames, excludeTool } = params;
+ const { toolRegistry, capabilityToolNames, excludeTool } = params;
+ const toolOptions = params.toolOptions && expandActionToolOptions(params.toolOptions);
const defs = params.toolDefinitions ?? [];
const selectionNames = getSelectionNames(toolOptions, 'run_in_background');
const effectiveSources = new Set<string>();
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index 2a1fcdbdc9..5831c95b95 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -555,6 +555,8 @@ export interface InitializeAgentParams {
hasDeferredTools?: boolean;
mcpToolAliases?: MCPToolAlias[];
actionsEnabled?: boolean;
+ /** Action tool names backed by OAuth — excluded from background dispatch. */
+ oauthActionToolNames?: string[];
/**
* Pre-uploaded code-env file refs for the agent's
* `tool_resources.execute_code`. Bubbled up so the run host can seed
@@ -1308,6 +1310,7 @@ export async function initializeAgent(
hasDeferredTools,
mcpToolAliases,
actionsEnabled,
+ oauthActionToolNames,
tools: structuredTools,
primedCodeFiles,
} = loadToolsResult ?? {
@@ -1322,6 +1325,7 @@ export async function initializeAgent(
hasDeferredTools: false,
mcpToolAliases: [],
actionsEnabled: undefined,
+ oauthActionToolNames: undefined,
primedCodeFiles: undefined,
};
@@ -1540,6 +1544,7 @@ export async function initializeAgent(
* ephemeral subset: a non-ephemeral name ending in an ephemeral one would
* otherwise be misread as ephemeral. */
const allServerNames = Object.keys(req.config?.mcpConfig ?? {}).map(normalizeServerName);
+ const oauthActionNames = new Set(oauthActionToolNames ?? []);
const backgroundResult = applyBackgroundToolCalls({
toolDefinitions,
toolRegistry,
@@ -1549,8 +1554,13 @@ export async function initializeAgent(
* 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. */
+ * the fail-safe for those. OAuth-backed action tools are excluded too:
+ * a detached call can block on an interactive login prompt the user
+ * never sees. */
excludeTool: (toolName) => {
+ if (oauthActionNames.has(toolName)) {
+ return true;
+ }
const [, serverName] = splitMCPToolKey(toolName, allServerNames);
return serverName != null && ephemeralServerNames.has(serverName);
},
diff --git a/packages/api/src/agents/subagentThreads.spec.ts b/packages/api/src/agents/subagentThreads.spec.ts
index f1f8c383e0..4861022d7b 100644
--- a/packages/api/src/agents/subagentThreads.spec.ts
+++ b/packages/api/src/agents/subagentThreads.spec.ts
@@ -3778,7 +3778,13 @@ describe('SubagentThreadTaskStore', () => {
expect(store.get(config.scopeId, liveTaskId)?.pendingControls).toBe(2);
finish({ content: 'done' });
- await waitForSettled(store, config.scopeId, live);
+ /** This store deliberately uses a 20 ms completed TTL. Under coverage the
+ * task can settle and expire between polling ticks, which is also a valid
+ * terminal outcome for the cleanup asserted by this test. */
+ await waitUntil(
+ () => store.get(config.scopeId, liveTaskId)?.status !== 'running',
+ 'the live replay-window task to settle or expire',
+ );
await store.destroyTaskControlTransport();
});
diff --git a/packages/api/src/tools/definitions.spec.ts b/packages/api/src/tools/definitions.spec.ts
index 9e7fc239e1..809e1ba9b5 100644
--- a/packages/api/src/tools/definitions.spec.ts
+++ b/packages/api/src/tools/definitions.spec.ts
@@ -48,6 +48,7 @@ describe('definitions.ts', () => {
expect(result.toolDefinitions).toHaveLength(0);
expect(result.toolRegistry.size).toBe(0);
expect(result.hasDeferredTools).toBe(false);
+ expect(result.oauthActionToolNames).toEqual([]);
});
describe('action tool definitions', () => {
@@ -130,6 +131,53 @@ describe('definitions.ts', () => {
expect(actionDef?.parameters).toBeUndefined();
});
+ it('collects OAuth action tool names and strips the marker from emitted defs', async () => {
+ const mockActionDefs: ActionToolDefinition[] = [
+ {
+ name: 'getWeather_action_weather_com',
+ description: 'Get weather for a location',
+ oauth: false,
+ },
+ {
+ name: 'sendMail_action_mail_example_com',
+ description: 'Send an email',
+ oauth: true,
+ },
+ {
+ name: 'listItems_action_api_example_com',
+ description: 'List all items',
+ },
+ ];
+
+ const mockGetActionToolDefinitions = jest.fn().mockResolvedValue(mockActionDefs);
+
+ const params: LoadToolDefinitionsParams = {
+ userId: 'user-123',
+ agentId: 'agent-123',
+ tools: [
+ 'getWeather_action_weather---com',
+ 'sendMail_action_mail---example---com',
+ 'listItems_action_api---example---com',
+ ],
+ };
+
+ const deps: LoadToolDefinitionsDeps = {
+ getOrFetchMCPServerTools: mockGetOrFetchMCPServerTools,
+ isBuiltInTool: mockIsBuiltInTool,
+ getActionToolDefinitions: mockGetActionToolDefinitions,
+ };
+
+ const result = await loadToolDefinitions(params, deps);
+
+ expect(result.oauthActionToolNames).toEqual(['sendMail_action_mail_example_com']);
+ for (const def of result.toolDefinitions) {
+ expect(def).not.toHaveProperty('oauth');
+ }
+ const registryEntry = result.toolRegistry.get('sendMail_action_mail_example_com');
+ expect(registryEntry).toBeDefined();
+ expect(registryEntry).not.toHaveProperty('oauth');
+ });
+
it('should not classify MCP tools with _action in name as action tools', async () => {
const mockGetActionToolDefinitions = jest.fn();
const mcpTool = 'get_action_mcp_myserver';
diff --git a/packages/api/src/tools/definitions.ts b/packages/api/src/tools/definitions.ts
index d4b5967b1d..ea0cf9844d 100644
--- a/packages/api/src/tools/definitions.ts
+++ b/packages/api/src/tools/definitions.ts
@@ -75,6 +75,9 @@ export interface ActionToolDefinition {
name: string;
description?: string;
parameters?: JsonSchemaType;
+ /** True when the action authenticates via OAuth — its calls may block on an
+ * interactive login prompt, so it must never be dispatched in the background. */
+ oauth?: boolean;
}
export interface LoadToolDefinitionsDeps {
@@ -101,6 +104,8 @@ export interface LoadToolDefinitionsResult {
expectedToolCount: number;
resolvedToolCount: number;
};
+ /** Action tool names backed by OAuth — excluded from background dispatch. */
+ oauthActionToolNames: string[];
}
const mcpToolPattern = /_mcp_/;
@@ -152,6 +157,7 @@ export async function loadToolDefinitions(
hasDeferredTools: false,
mcpToolAliases: [],
mcpResolution: { expectedToolCount: 0, resolvedToolCount: 0 },
+ oauthActionToolNames: [],
};
if (!tools || tools.length === 0) {
@@ -324,13 +330,19 @@ export async function loadToolDefinitions(
}
}
+ const oauthActionToolNames: string[] = [];
if (actionToolNames.length > 0 && getActionToolDefinitions) {
const fetchedActionDefs = await getActionToolDefinitions(agentId, actionToolNames);
- actionToolDefs = fetchedActionDefs.map((def) => ({
- name: def.name,
- description: def.description,
- parameters: def.parameters,
- }));
+ actionToolDefs = fetchedActionDefs.map((def) => {
+ if (def.oauth === true) {
+ oauthActionToolNames.push(def.name);
+ }
+ return {
+ name: def.name,
+ description: def.description,
+ parameters: def.parameters,
+ };
+ });
}
const loadedTools = mcpToolDefs.map((def) => ({
@@ -395,5 +407,6 @@ export async function loadToolDefinitions(
expectedToolCount: expectedMCPToolCount,
resolvedToolCount: resolvedMCPToolCount,
},
+ oauthActionToolNames,
};
}
diff --git a/packages/data-provider/src/agentToolOptions.spec.ts b/packages/data-provider/src/agentToolOptions.spec.ts
index f0ce65814d..be52b21b98 100644
--- a/packages/data-provider/src/agentToolOptions.spec.ts
+++ b/packages/data-provider/src/agentToolOptions.spec.ts
@@ -1,5 +1,20 @@
import type { AgentToolOptions } from './types/assistants';
-import { removeCodeExecutionCaller } from './agentToolOptions';
+import { normalizeActionToolName, removeCodeExecutionCaller } from './agentToolOptions';
+
+describe('normalizeActionToolName', () => {
+ it('normalizes only the encoded action domain', () => {
+ expect(normalizeActionToolName('get_foo---bar_action_swapi---tech')).toBe(
+ 'get_foo---bar_action_swapi_tech',
+ );
+ });
+
+ it('leaves non-action tool names unchanged', () => {
+ expect(normalizeActionToolName('search_mcp_docs---server')).toBe('search_mcp_docs---server');
+ expect(normalizeActionToolName('get_action_data---x_mcp_srv')).toBe(
+ 'get_action_data---x_mcp_srv',
+ );
+ });
+});
describe('removeCodeExecutionCaller', () => {
it('removes a programmatic-only entry that has no other options', () => {
diff --git a/packages/data-provider/src/agentToolOptions.ts b/packages/data-provider/src/agentToolOptions.ts
index a611b49704..269e27a7b7 100644
--- a/packages/data-provider/src/agentToolOptions.ts
+++ b/packages/data-provider/src/agentToolOptions.ts
@@ -1,4 +1,26 @@
-import type { AgentToolOptions, AllowedCaller } from './types/assistants';
+import {
+ actionDelimiter,
+ actionDomainSeparator,
+ isActionTool,
+ type AgentToolOptions,
+ type AllowedCaller,
+} from './types/assistants';
+
+const actionDomainSeparatorRegex = new RegExp(actionDomainSeparator, 'g');
+
+/**
+ * Collapses the encoded-domain suffix of an action tool name to the shape used
+ * by runtime tool definitions. The operation id is deliberately preserved.
+ */
+export function normalizeActionToolName(toolName: string): string {
+ if (!isActionTool(toolName)) {
+ return toolName;
+ }
+ const delimiterIndex = toolName.lastIndexOf(actionDelimiter);
+ const prefixEnd = delimiterIndex + actionDelimiter.length;
+ const encodedDomain = toolName.slice(prefixEnd);
+ return toolName.slice(0, prefixEnd) + encodedDomain.replace(actionDomainSeparatorRegex, '_');
+}
/**
* Removes Code Interpreter as an allowed caller without mutating the input.
diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.ts
index 9d309086f0..764d8a0bf3 100644
--- a/packages/data-provider/src/types/assistants.ts
+++ b/packages/data-provider/src/types/assistants.ts
@@ -359,6 +359,8 @@ export type Agent = {
owner_contact?: AgentOwnerContact;
/** Per-tool configuration options (deferred loading, allowed callers, etc.) */
tool_options?: AgentToolOptions;
+ /** Attached action registrations, each `${encodedDomain}${actionDelimiter}${action_id}` */
+ actions?: string[];
/** Optional allowlist of skill ObjectIds. Only applies when `skills_enabled`. */
skills?: string[];
/** Master toggle for skill use on this agent. `true` = active (full catalog unless