Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧺 feat: Preserve Partial Work at Tool Call Limits (#15486)
Marco Beretta2cf1007f3c0a
diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.jsindex b1f49b8ab8..a9e2e6475e 100644--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js@@ -5481,7 +5481,7 @@ describe('ResumableAgentController resume metadata', () => {getHaltReason: () => 'preempt_incomplete',};- const runFirstTurn = async ({ run, addTitle: suppliedAddTitle } = {}) => {+ const runFirstTurn = async ({ run, addTitle: suppliedAddTitle, clientOverrides } = {}) => {let signalFinished;const finished = new Promise((resolve) => {signalFinished = resolve;@@ -5500,6 +5500,7 @@ describe('ResumableAgentController resume metadata', () => {savedMessageIds: new Set(),skipSaveUserMessage: false,...(run && { run }),+ ...clientOverrides,sendMessage: jest.fn(async (_text, options) => {const userMessage = {messageId: 'user-msg',@@ -5602,5 +5603,53 @@ describe('ResumableAgentController resume metadata', () => {expect(addTitle).toHaveBeenCalledTimes(1);expect(getTitleSignal().aborted).toBe(false);});++ /**+ * The hop that makes the client notice possible: `AgentClient` swallows the+ * graph's step-limit error and raises `stepLimitReached`, and the controller+ * must turn that into an `unfinished` row stamped with the tool-call-limit+ * finish reason on BOTH the durable write and the terminal SSE event.+ */+ const stepLimitClient = { stepLimitReached: true };++ const savedResponseRow = () =>+ mockSaveMessage.mock.calls+ .map(([, message]) => message)+ .find((message) => message?.messageId === 'response-msg');++ it('persists a step-limited turn as unfinished with the tool-call-limit finish reason', async () => {+ await runFirstTurn({ clientOverrides: stepLimitClient });++ expect(savedResponseRow()).toEqual(+ expect.objectContaining({+ unfinished: true,+ finish_reason: Constants.TOOL_CALL_LIMIT_FINISH_REASON,+ }),+ );+ });++ it('keeps the partial content on a step-limited turn instead of replacing it with an error', async () => {+ await runFirstTurn({ clientOverrides: stepLimitClient });++ const saved = savedResponseRow();+ expect(saved.content).toEqual([{ type: 'text', text: 'Truncated answer' }]);+ expect(saved.error).not.toBe(true);+ });++ it('publishes the finish reason on the terminal event so the client needs no refetch', async () => {+ await runFirstTurn({ clientOverrides: stepLimitClient });++ const published = mockGenerationJobManager.publishTerminalClaim.mock.calls.at(-1);+ expect(published).toBeDefined();+ expect(JSON.stringify(published)).toContain(Constants.TOOL_CALL_LIMIT_FINISH_REASON);+ });++ it('leaves an ordinary completed turn finished and unstamped', async () => {+ await runFirstTurn();++ const saved = savedResponseRow();+ expect(saved.unfinished).toBe(false);+ expect(saved.finish_reason).toBeUndefined();+ });});});diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.jsindex 49b53bac89..2570a070b0 100644--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js@@ -289,6 +289,7 @@ jest.mock('@librechat/api', () => ({alwaysApplyDedupedFromManual: 0,}),createToolExecuteHandler: jest.fn().mockReturnValue({ handle: jest.fn() }),+ resolveRecursionLimit: jest.fn().mockReturnValue(50),// Responses APIwriteDone: jest.fn(),buildResponse: jest.fn().mockReturnValue({ id: 'resp_123', output: [] }),@@ -709,6 +710,21 @@ describe('createResponse controller', () => {);});+ it('invokes the graph with the resolved recursion limit rather than the SDK default', async () => {+ const api = require('@librechat/api');+ const processStream = jest.fn().mockResolvedValue(undefined);+ api.createRun.mockResolvedValueOnce({ processStream });+ api.resolveRecursionLimit.mockReturnValueOnce(123);++ await createResponse(req, res);++ expect(processStream).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ recursionLimit: 123 }),+ expect.anything(),+ );+ });+it('returns 503 when an agent expects MCP tools but resolves none', async () => {const { initializeAgent, sendResponsesErrorResponse } = require('@librechat/api');const { loadAgentTools } = require('~/server/services/ToolService');diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 9b9abe2f57..388bddda5f 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -55,6 +55,7 @@ const {getPluginHookSource,captureAgentCheckpointGeneration,isContentFilterError,+ isStepLimitError,deleteAgentCheckpoint,LIBRECHAT_CHECKPOINT_NAMESPACE_KEY,LIBRECHAT_EVENT_ACTOR_INVOCATION_KEY,@@ -387,6 +388,11 @@ class AgentClient extends BaseClient {* these before returning — otherwise job cleanup can race the persist.* @type {Promise<void>[]} */this.pendingSubagentEmits = [];+ /** Set when the graph exhausted its per-turn step budget (`recursionLimit`).+ * Read by `request.js`/`resume.js` to persist the row as `unfinished` with+ * `Constants.TOOL_CALL_LIMIT_FINISH_REASON` instead of publishing an error.+ * @type {boolean} */+ this.stepLimitReached = false;/** Stable per-generation sequence for subagent usage events. Detached* usage is billed outside `collectedUsage`, so array length is no longer* a valid sequence source. @type {number} */@@ -4407,6 +4413,25 @@ class AgentClient extends BaseClient {'[api/server/controllers/agents/client.js #sendCompletion] Operation aborted by user',{ conversationId: this.conversationId, ...getSafeErrorMetadata(err) },);+ } else if (isStepLimitError(err)) {+ /**+ * The graph ran out of supersteps. Everything already streamed is real work,+ * so this terminates the turn as incomplete rather than failed: no ERROR part,+ * and `request.js` persists the row `unfinished` with the tool-call-limit+ * finish reason so the UI can offer to continue. Mirrors the abort contract:+ * a turn that stopped early is not a turn that broke.+ */+ this.stepLimitReached = true;+ logger.warn(+ '[api/server/controllers/agents/client.js #sendCompletion] Tool call limit reached; ending the turn as incomplete',+ {+ conversationId: this.conversationId,+ recursionLimit: resolveRecursionLimit(+ this.options.req.config?.endpoints?.[EModelEndpoint.agents],+ this.options.agent,+ ),+ },+ );} else {logger.error('[api/server/controllers/agents/client.js #sendCompletion] Unhandled error type',@@ -4854,6 +4879,15 @@ class AgentClient extends BaseClient {...getSafeErrorMetadata(err),},);+ } else if (isStepLimitError(err)) {+ /** Same contract as the initial turn: incomplete, not failed. A resumed run+ * inherits the budget of a turn that already spent steps before pausing, so+ * this boundary is if anything more likely to be reached here. */+ this.stepLimitReached = true;+ logger.warn(+ '[api/server/controllers/agents/client.js #resumeCompletion] Tool call limit reached; ending the resumed turn as incomplete',+ { conversationId: this.conversationId },+ );} else {logger.error('[api/server/controllers/agents/client.js #resumeCompletion] Unhandled error',diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.jsindex 7e04e768f4..39a1648729 100644--- a/api/server/controllers/agents/client.test.js+++ b/api/server/controllers/agents/client.test.js@@ -2053,6 +2053,103 @@ describe('AgentClient - startup telemetry', () => {);});+ it('ends a step-limit turn as incomplete rather than as an error part', async () => {+ jest.clearAllMocks();+ const { GraphRecursionError } = require('@langchain/langgraph');+ /** The exact error LangGraph throws once the graph runs out of supersteps. */+ const stepLimitError = new GraphRecursionError(+ 'Recursion limit of 50 reached without hitting a stop condition.',+ { lc_error_code: 'GRAPH_RECURSION_LIMIT' },+ );++ mockCreateRun.mockResolvedValue({+ Graph: null,+ processStream: jest.fn().mockRejectedValue(stepLimitError),+ getCalibrationRatio: jest.fn(() => 0),+ });+ mockIsHITLEnabled.mockReturnValue(false);+ const client = new AgentClient({+ req: {+ user: { id: 'user-123' },+ body: {},+ config: { endpoints: { [EModelEndpoint.agents]: {} } },+ _resumableStreamId: 'conversation-step-limit',+ },+ res: {},+ agent: {+ id: 'agent-123',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ hide_sequential_outputs: false,+ },+ endpointTokenConfig: {},+ eventHandlers: {},+ /** Work the turn already produced; it must survive the boundary. */+ contentParts: [{ type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Partial findings' }],+ collectedUsage: [],+ artifactPromises: [],+ });+ client.conversationId = 'conversation-step-limit';+ client.responseMessageId = 'response-step-limit';+ client.parentMessageId = 'parent-step-limit';+ client.recordCollectedUsage = jest.fn().mockResolvedValue();++ await client.chatCompletion({ payload: [] });++ expect(client.stepLimitReached).toBe(true);+ expect(client.contentParts).not.toEqual(+ expect.arrayContaining([expect.objectContaining({ type: ContentTypes.ERROR })]),+ );+ expect(client.contentParts).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ [ContentTypes.TEXT]: 'Partial findings' }),+ ]),+ );+ });++ it('still surfaces an error part for an ordinary run failure', async () => {+ jest.clearAllMocks();+ mockCreateRun.mockResolvedValue({+ Graph: null,+ processStream: jest.fn().mockRejectedValue(new Error('provider exploded')),+ getCalibrationRatio: jest.fn(() => 0),+ });+ mockIsHITLEnabled.mockReturnValue(false);+ const client = new AgentClient({+ req: {+ user: { id: 'user-123' },+ body: {},+ config: { endpoints: { [EModelEndpoint.agents]: {} } },+ _resumableStreamId: 'conversation-plain-error',+ },+ res: {},+ agent: {+ id: 'agent-123',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ hide_sequential_outputs: false,+ },+ endpointTokenConfig: {},+ eventHandlers: {},+ contentParts: [],+ collectedUsage: [],+ artifactPromises: [],+ });+ client.conversationId = 'conversation-plain-error';+ client.responseMessageId = 'response-plain-error';+ client.parentMessageId = 'parent-plain-error';+ client.recordCollectedUsage = jest.fn().mockResolvedValue();++ await client.chatCompletion({ payload: [] });++ expect(client.stepLimitReached).toBe(false);+ expect(client.contentParts).toEqual(+ expect.arrayContaining([expect.objectContaining({ type: ContentTypes.ERROR })]),+ );+ });+it('evolves warm compaction guidance while injecting only the new event message', async () => {jest.clearAllMocks();const history = { _getType: () => 'human', content: 'old turn' };diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex 5f57af82c5..8e8880fc52 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -1892,6 +1892,10 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitlet terminalPersistenceChecked = false;let terminalWasAborted = false;let preemptIncomplete = false;+ /** The graph exhausted its per-turn step budget. Like `preemptIncomplete`, an+ * honest `unfinished` outcome rather than an error: the partial turn is real+ * work and the user is offered a way to carry on. */+ let stepLimitReached = false;/** A pause-row write failure is terminalized through the exact action/epoch* barrier. Once that path starts, neither generic background error handler* may call completeJob: the pause may already have been replaced by a newer@@ -1929,6 +1933,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitpreemptIncomplete =(preemptStats?.emptyBoundaries ?? 0) > 0 ||client?.run?.getHaltReason?.() === 'preempt_incomplete';+ stepLimitReached = client?.stepLimitReached === true;terminalClaim = await GenerationJobManager.claimTerminalJob(streamId,terminalWasAborted ? 'aborted' : 'complete',@@ -2712,13 +2717,19 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit/** BaseClient can add the id to savedMessageIds even when its model-layer* save resolved falsy. Re-save the terminal row idempotently and require* the returned durable row before publishing the normal FINAL. */- const responseIsUnfinished = terminalWasAborted || preemptIncomplete;+ const responseIsUnfinished = terminalWasAborted || preemptIncomplete || stepLimitReached;const savedResponseMessage = await saveMessage(reqCtx,{...response,user: userId,unfinished: responseIsUnfinished,+ /** Distinguishes "ran out of steps" from a user stop, so the client can+ * render the actionable tool-call-limit notice rather than the generic+ * incomplete-response warning. */+ ...(stepLimitReached && {+ finish_reason: Constants.TOOL_CALL_LIMIT_FINISH_REASON,+ }),},{context: responseIsUnfinished@@ -2778,9 +2789,11 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitscheduleCompletionError = 'Scheduled run was stopped';} else if (preemptIncomplete) {scheduleCompletionError = 'Scheduled run was interrupted before completion';+ } else if (stepLimitReached) {+ scheduleCompletionError = 'Scheduled run reached its tool call limit before completion';}await settleScheduledRun({- status: terminalWasAborted || preemptIncomplete ? 'interrupted' : 'success',+ status: responseIsUnfinished ? 'interrupted' : 'success',...(scheduleCompletionError != null && { error: scheduleCompletionError }),});@@ -2794,7 +2807,10 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitrequestMessage: sanitizeMessageForTransmit(userMessage),responseMessage: {...response,- ...((terminalWasAborted || preemptIncomplete) && { unfinished: true }),+ ...(responseIsUnfinished && { unfinished: true }),+ ...(stepLimitReached && {+ finish_reason: Constants.TOOL_CALL_LIMIT_FINISH_REASON,+ }),},...(pendingSteers.length > 0 && { pendingSteers }),};diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsindex f80f0ebd57..79ce4ea3e2 100644--- a/api/server/controllers/agents/responses.js+++ b/api/server/controllers/agents/responses.js@@ -53,6 +53,7 @@ const {getSafeErrorMetadata,getUserFacingProviderError,createToolExecuteHandler,+ resolveRecursionLimit,getRemoteAgentPermissions,resolveAgentScopedSkillIds,// Responses API@@ -1201,6 +1202,7 @@ const executeResponse = async (envelope, { req, res }) => {requestBody: mcpRequestBody,...(userMCPAuthMap != null && { userMCPAuthMap }),},+ recursionLimit: resolveRecursionLimit(agentsEConfig, agent),signal: execution.signal,streamMode: 'values',version: 'v2',@@ -1411,6 +1413,7 @@ const executeResponse = async (envelope, { req, res }) => {requestBody: mcpRequestBody,...(userMCPAuthMap != null && { userMCPAuthMap }),},+ recursionLimit: resolveRecursionLimit(agentsEConfig, agent),signal: execution.signal,streamMode: 'values',version: 'v2',diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.jsindex cd19216c76..5d767a7c69 100644--- a/api/server/controllers/agents/resume.js+++ b/api/server/controllers/agents/resume.js@@ -447,6 +447,8 @@ async function finalizeResumedTurn({const preemptIncomplete =(preemptStats?.emptyBoundaries ?? 0) > 0 ||client?.run?.getHaltReason?.() === 'preempt_incomplete';+ /** Same honest-incomplete contract for a resumed turn that runs out of steps. */+ const stepLimitReached = client?.stepLimitReached === true;const responseMessage = {messageId: responseMessageId,@@ -457,7 +459,8 @@ async function finalizeResumedTurn({endpoint: meta.endpoint,iconURL: meta.iconURL,model: meta.model,- unfinished: preemptIncomplete,+ unfinished: preemptIncomplete || stepLimitReached,+ ...(stepLimitReached && { finish_reason: Constants.TOOL_CALL_LIMIT_FINISH_REASON }),error: false,isCreatedByUser: false,user: userId,@@ -612,11 +615,15 @@ async function finalizeResumedTurn({scheduledFor: meta.scheduledFor,streamId,jobCreatedAt: job.createdAt,- status: preemptIncomplete ? 'interrupted' : 'success',+ status: preemptIncomplete || stepLimitReached ? 'interrupted' : 'success',conversationId,...(preemptIncomplete && {error: 'Scheduled run was interrupted before completion',}),+ ...(stepLimitReached &&+ !preemptIncomplete && {+ error: 'Scheduled run reached its tool call limit before completion',+ }),});}diff --git a/client/src/components/Chat/Messages/Content/MessageContent.tsx b/client/src/components/Chat/Messages/Content/MessageContent.tsxindex 419625eb6e..a1291c76b1 100644--- a/client/src/components/Chat/Messages/Content/MessageContent.tsx+++ b/client/src/components/Chat/Messages/Content/MessageContent.tsx@@ -1,10 +1,12 @@import { memo, Suspense, useMemo } from 'react';import { useRecoilValue } from 'recoil';+import { Constants } from 'librechat-data-provider';import { Alert, DelayedRender } from '@librechat/client';import type { TMessage } from 'librechat-data-provider';import type { TMessageContentProps, TDisplayProps } from '~/common';import useSmoothStreaming from '~/hooks/Messages/useSmoothStreaming';import Error from '~/components/Messages/Content/Error';+import ToolCallLimitNotice from './ToolCallLimitNotice';import CollapsibleText from './Parts/CollapsibleText';import { useMessageContext } from '~/Providers';import EmptyText from './Parts/EmptyText';@@ -130,12 +132,21 @@ const DisplayMessage = ({ text, isCreatedByUser, message, showCursor }: TDisplay);};-export const UnfinishedMessage = ({ message }: { message: TMessage }) => (- <ErrorMessage- message={message}- text="The response is incomplete; it's either still processing, was cancelled, or censored. Refresh or try a different prompt."- />-);+export const UnfinishedMessage = ({ message }: { message: TMessage }) => {+ const localize = useLocalize();++ /** Ran out of steps, not broken: a distinct, actionable card rather than the+ * generic "something went wrong, try again" warning. */+ if (message.finish_reason === Constants.TOOL_CALL_LIMIT_FINISH_REASON) {+ return (+ <Container message={message}>+ <ToolCallLimitNotice message={message} />+ </Container>+ );+ }++ return <ErrorMessage message={message} text={localize('com_ui_response_incomplete')} />;+};const MessageContent = ({text,diff --git a/client/src/components/Chat/Messages/Content/ToolCallLimitNotice.tsx b/client/src/components/Chat/Messages/Content/ToolCallLimitNotice.tsxnew file mode 100644index 0000000000..b4aeaca9a2--- /dev/null+++ b/client/src/components/Chat/Messages/Content/ToolCallLimitNotice.tsx@@ -0,0 +1,113 @@+import { useContext, useId, useState } from 'react';+import { Button } from '@librechat/client';+import { FastForward, Gauge, MessageSquareText, X } from 'lucide-react';+import type { TMessage } from 'librechat-data-provider';+import { ChatContext } from '~/Providers/ChatContext';+import { useLocalize } from '~/hooks';++/**+ * Shown when a turn ended because the agent exhausted its per-turn step budget+ * (`recursionLimit`) rather than because anything failed. The server marks that+ * row `unfinished` with `Constants.TOOL_CALL_LIMIT_FINISH_REASON`.+ *+ * Deliberately not an `ErrorBox`: nothing broke, the work above is real, and the+ * only thing the user needs is a way forward. Both actions post an ordinary user+ * turn, which is what makes them work everywhere:+ *+ * - the previous turn is already persisted with its tool calls, so the model sees+ * everything it did before deciding what to do next, and+ * - a new turn gets a fresh step budget without needing a resumable checkpoint,+ * which only exists on HITL-capable deployments.+ *+ * The instruction text is localized because it becomes a visible message in the+ * user's own conversation, in their own language.+ */+export default function ToolCallLimitNotice({ message }: { message: TMessage }) {+ const localize = useLocalize();+ const titleId = useId();+ const [dismissed, setDismissed] = useState(false);+ const [noticeMessageId, setNoticeMessageId] = useState(message.messageId);+ /**+ * MultiMessage reuses this row when switching siblings, so dismiss state+ * would otherwise hide the notice on a different message. Reset during+ * render when the displayed id changes; no effect needed.+ */+ if (noticeMessageId !== message.messageId) {+ setNoticeMessageId(message.messageId);+ setDismissed(false);+ }+ /**+ * Nullable on purpose: this renders inside shared links, search results and+ * exports, which mount message content with no live chat behind it. There the+ * explanation still helps, so the card degrades to text instead of throwing.+ */+ const chat = useContext(ChatContext);++ if (dismissed && noticeMessageId === message.messageId) {+ return null;+ }++ /**+ * `ask` appends to the tail of the active branch, so offering it on anything+ * but the tail would send the follow-up somewhere the user is not looking.+ * Same gate `useGenerationsByLatest` applies to the Continue hover button.+ */+ const canAct =+ chat?.ask != null && chat.isSubmitting !== true && chat.latestMessageId === message.messageId;+ /**+ * Empty overrides are authoritative: a recovery prompt is not the user's next+ * compose, so `ask` must not attach or drain files, skills, or quotes already+ * staged in the composer.+ */+ const recover = (text: string) =>+ chat?.ask({ text }, { overrideFiles: [], overrideManualSkills: [], overrideQuotes: [] });++ return (+ <div+ role="group"+ aria-labelledby={titleId}+ className="relative my-2 flex w-full flex-col rounded-xl border border-border-light bg-surface-secondary p-3"+ >+ <Button+ type="button"+ variant="ghost"+ size="icon-xs"+ aria-label={localize('com_ui_dismiss')}+ className="absolute right-1.5 top-1.5 text-text-secondary focus-visible:ring-inset focus-visible:ring-offset-0"+ onClick={() => setDismissed(true)}+ >+ <X className="h-4 w-4" aria-hidden="true" />+ </Button>+ <p+ id={titleId}+ className="flex min-w-0 items-center gap-2 pr-8 text-sm font-medium text-text-primary"+ >+ <Gauge className="h-4 w-4 shrink-0 text-text-secondary" aria-hidden="true" />+ {localize('com_ui_tool_call_limit_title')}+ </p>+ <p className="mb-3 mt-1 text-sm text-text-secondary">+ {localize('com_ui_tool_call_limit_body')}+ </p>+ {canAct && (+ <div className="flex flex-wrap items-center gap-2">+ <Button+ size="sm"+ variant="submit"+ onClick={() => recover(localize('com_ui_tool_call_limit_continue_prompt'))}+ >+ <FastForward className="icon-md shrink-0" aria-hidden="true" />+ {localize('com_ui_tool_call_limit_continue')}+ </Button>+ <Button+ size="sm"+ variant="outline"+ onClick={() => recover(localize('com_ui_tool_call_limit_answer_prompt'))}+ >+ <MessageSquareText className="icon-md shrink-0" aria-hidden="true" />+ {localize('com_ui_tool_call_limit_answer')}+ </Button>+ </div>+ )}+ </div>+ );+}diff --git a/client/src/components/Chat/Messages/Content/__tests__/ToolCallLimitNotice.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ToolCallLimitNotice.test.tsxnew file mode 100644index 0000000000..5deb83ef7b--- /dev/null+++ b/client/src/components/Chat/Messages/Content/__tests__/ToolCallLimitNotice.test.tsx@@ -0,0 +1,153 @@+import React from 'react';+import { render, screen, fireEvent } from '@testing-library/react';+import type { TMessage } from 'librechat-data-provider';+import ToolCallLimitNotice from '../ToolCallLimitNotice';+import { ChatContext } from '~/Providers/ChatContext';++const TRANSLATIONS: Record<string, string> = {+ com_ui_tool_call_limit_title: 'Reached the tool call limit for this turn',+ com_ui_tool_call_limit_body: 'The agent used every step allowed in a single turn.',+ com_ui_tool_call_limit_continue: 'Keep going',+ com_ui_tool_call_limit_continue_prompt: 'Keep going from where you stopped.',+ com_ui_tool_call_limit_answer: 'Answer now',+ com_ui_tool_call_limit_answer_prompt: 'Stop using tools and answer now.',+ com_ui_dismiss: 'Dismiss',+};++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => TRANSLATIONS[key] ?? key,+}));++const MESSAGE = { messageId: 'response-1' } as TMessage;++type NoticeChatContext = NonNullable<React.ContextType<typeof ChatContext>>;++/**+ * The notice only reads `ask`, `isSubmitting`, and `latestMessageId`. The real+ * context is a large helper return type, so a partial cannot overlap it for+ * TypeScript without going through `unknown`.+ */+function chatContextValue(context: Partial<NoticeChatContext>): NoticeChatContext {+ return context as unknown as NoticeChatContext;+}++function renderNotice(context?: Partial<NoticeChatContext>, message: TMessage = MESSAGE) {+ if (context == null) {+ return render(<ToolCallLimitNotice message={message} />);+ }+ return render(+ <ChatContext.Provider value={chatContextValue(context)}>+ <ToolCallLimitNotice message={message} />+ </ChatContext.Provider>,+ );+}++describe('ToolCallLimitNotice', () => {+ it('explains what happened rather than reporting an error', () => {+ renderNotice();++ expect(screen.getByText(TRANSLATIONS.com_ui_tool_call_limit_title)).toBeInTheDocument();+ expect(screen.getByText(TRANSLATIONS.com_ui_tool_call_limit_body)).toBeInTheDocument();+ /** An `alert` role would announce this as a failure; it is a normal outcome. */+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('names its container for screen readers', () => {+ renderNotice();++ expect(+ screen.getByRole('group', { name: TRANSLATIONS.com_ui_tool_call_limit_title }),+ ).toBeInTheDocument();+ });++ it('continues the turn as a new request carrying the continue instruction', () => {+ const ask = jest.fn();+ renderNotice({ ask, isSubmitting: false, latestMessageId: 'response-1' });++ fireEvent.click(+ screen.getByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_continue }),+ );++ expect(ask).toHaveBeenCalledTimes(1);+ expect(ask).toHaveBeenCalledWith(+ { text: TRANSLATIONS.com_ui_tool_call_limit_continue_prompt },+ { overrideFiles: [], overrideManualSkills: [], overrideQuotes: [] },+ );+ });++ it('asks for an immediate answer instead of more tool use', () => {+ const ask = jest.fn();+ renderNotice({ ask, isSubmitting: false, latestMessageId: 'response-1' });++ fireEvent.click(+ screen.getByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_answer }),+ );++ expect(ask).toHaveBeenCalledWith(+ { text: TRANSLATIONS.com_ui_tool_call_limit_answer_prompt },+ { overrideFiles: [], overrideManualSkills: [], overrideQuotes: [] },+ );+ });++ it('offers no actions with no live chat behind it, as in a shared link or export', () => {+ renderNotice();++ expect(+ screen.queryByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_continue }),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_answer }),+ ).not.toBeInTheDocument();+ /** The explanation and the way to hide it must survive. */+ expect(screen.getByText(TRANSLATIONS.com_ui_tool_call_limit_body)).toBeInTheDocument();+ expect(screen.getByRole('button', { name: 'Dismiss' })).toBeInTheDocument();+ });++ it('offers no actions on a message that is not the branch tail', () => {+ const ask = jest.fn();+ renderNotice({ ask, isSubmitting: false, latestMessageId: 'some-newer-message' });++ expect(+ screen.queryByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_continue }),+ ).not.toBeInTheDocument();+ expect(ask).not.toHaveBeenCalled();+ });++ it('offers no actions while a generation is already running', () => {+ renderNotice({ ask: jest.fn(), isSubmitting: true, latestMessageId: 'response-1' });++ expect(+ screen.queryByRole('button', { name: TRANSLATIONS.com_ui_tool_call_limit_continue }),+ ).not.toBeInTheDocument();+ });++ it('can be dismissed', () => {+ renderNotice({ ask: jest.fn(), isSubmitting: false, latestMessageId: 'response-1' });++ fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));++ expect(screen.queryByText(TRANSLATIONS.com_ui_tool_call_limit_title)).not.toBeInTheDocument();+ });++ it('shows the notice again when switching to another sibling message', () => {+ const ask = jest.fn();+ const { rerender } = renderNotice({+ ask,+ isSubmitting: false,+ latestMessageId: 'response-1',+ });++ fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));+ expect(screen.queryByText(TRANSLATIONS.com_ui_tool_call_limit_title)).not.toBeInTheDocument();++ rerender(+ <ChatContext.Provider+ value={chatContextValue({ ask, isSubmitting: false, latestMessageId: 'response-2' })}+ >+ <ToolCallLimitNotice message={{ messageId: 'response-2' } as TMessage} />+ </ChatContext.Provider>,+ );++ expect(screen.getByText(TRANSLATIONS.com_ui_tool_call_limit_title)).toBeInTheDocument();+ });+});diff --git a/client/src/components/Chat/Messages/Content/__tests__/UnfinishedMessage.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/UnfinishedMessage.test.tsxnew file mode 100644index 0000000000..1960f7f324--- /dev/null+++ b/client/src/components/Chat/Messages/Content/__tests__/UnfinishedMessage.test.tsx@@ -0,0 +1,60 @@+import React from 'react';+import { Constants } from 'librechat-data-provider';+import { render, screen } from '@testing-library/react';+import type { TMessage } from 'librechat-data-provider';+import { UnfinishedMessage } from '../MessageContent';++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+}));++/** `Container` reads message context for sequential-agent layout; not under test. */+jest.mock('../Container', () => ({+ __esModule: true,+ default: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,+}));++jest.mock('~/components/Messages/Content/Error', () => ({+ __esModule: true,+ default: ({ text }: { text: string }) => <span>{text}</span>,+}));++jest.mock('../ToolCallLimitNotice', () => ({+ __esModule: true,+ default: () => <div data-testid="tool-call-limit-notice" />,+}));++/** `Constants` is a heterogeneous enum, so its members are not directly+ * assignable to `finish_reason`'s `string`; coerce rather than duplicate the value. */+const TOOL_CALL_LIMIT = String(Constants.TOOL_CALL_LIMIT_FINISH_REASON);++const message = (overrides: Partial<TMessage> = {}) =>+ ({ messageId: 'response-1', ...overrides }) as TMessage;++describe('UnfinishedMessage', () => {+ it('routes a step-limit turn to the actionable notice, not an error box', () => {+ render(<UnfinishedMessage message={message({ finish_reason: TOOL_CALL_LIMIT })} />);++ expect(screen.getByTestId('tool-call-limit-notice')).toBeInTheDocument();+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();+ });++ it('keeps the generic incomplete warning for every other unfinished turn', () => {+ render(<UnfinishedMessage message={message()} />);++ expect(screen.queryByTestId('tool-call-limit-notice')).not.toBeInTheDocument();+ expect(screen.getByText('com_ui_response_incomplete')).toBeInTheDocument();+ });++ it('does not mistake an unrelated finish reason for the step limit', () => {+ render(<UnfinishedMessage message={message({ finish_reason: 'length' })} />);++ expect(screen.queryByTestId('tool-call-limit-notice')).not.toBeInTheDocument();+ });++ it('localizes the generic warning instead of hardcoding English', () => {+ render(<UnfinishedMessage message={message()} />);++ expect(screen.queryByText(/The response is incomplete/)).not.toBeInTheDocument();+ });+});diff --git a/client/src/components/Messages/ContentRender.tsx b/client/src/components/Messages/ContentRender.tsxindex 6416188286..51a9279e27 100644--- a/client/src/components/Messages/ContentRender.tsx+++ b/client/src/components/Messages/ContentRender.tsx@@ -1,5 +1,6 @@import { useCallback, useMemo, memo } from 'react';import { useRecoilValue } from 'recoil';+import { Constants } from 'librechat-data-provider';import type { TMessage, TMessageContentParts } from 'librechat-data-provider';import type { TMessageProps, TMessageIcon, TMessageChatContext } from '~/common';import {@@ -10,6 +11,7 @@ import {} from '~/utils';import { revealOnRowHoverClasses, messageFooterClasses } from '~/components/Chat/Messages/styles';import { useAttachments, useLocalize, useMessageActions, useContentMetadata } from '~/hooks';+import ToolCallLimitNotice from '~/components/Chat/Messages/Content/ToolCallLimitNotice';import AuthorHeader from '~/components/Chat/Messages/Content/Parts/AuthorHeader';import Elapsed, { shouldShowElapsed } from '~/components/Chat/Messages/Elapsed';import { getHeaderModelName } from '~/components/Chat/Messages/ui/HeaderLabel';@@ -220,6 +222,15 @@ const ContentRender = memo(function ContentRender({conversationId={conversation?.conversationId}content={msg.content as Array<TMessageContentParts | undefined>}/>+ {/** A turn that ran out of agent steps is incomplete, not broken. Rendered+ * here rather than inside `ContentParts` because it is a message-level+ * outcome, and `ContentParts` also serves surfaces (subagent panels,+ * search) that have no message row behind them. */}+ {msg.unfinished === true &&+ !isSubmitting &&+ msg.finish_reason === Constants.TOOL_CALL_LIMIT_FINISH_REASON && (+ <ToolCallLimitNotice message={msg} />+ )}</MessageRow>);}, areContentRenderPropsEqual);diff --git a/client/src/hooks/__tests__/useGenerationsByLatest.spec.ts b/client/src/hooks/__tests__/useGenerationsByLatest.spec.tsnew file mode 100644index 0000000000..f281edf8b4--- /dev/null+++ b/client/src/hooks/__tests__/useGenerationsByLatest.spec.ts@@ -0,0 +1,30 @@+import { Constants, EModelEndpoint } from 'librechat-data-provider';+import useGenerationsByLatest from '../useGenerationsByLatest';++const base = {+ endpoint: EModelEndpoint.agents,+ messageId: 'response-1',+ latestMessageId: 'response-1',+ isSubmitting: false,+ isCreatedByUser: false,+};++describe('useGenerationsByLatest', () => {+ it('withholds the hover Continue control when the turn ran out of tool steps', () => {+ const result = useGenerationsByLatest({+ ...base,+ finish_reason: String(Constants.TOOL_CALL_LIMIT_FINISH_REASON),+ });++ expect(result.continueSupported).toBe(false);+ });++ it('still offers Continue for other incomplete finish reasons', () => {+ const result = useGenerationsByLatest({+ ...base,+ finish_reason: 'length',+ });++ expect(result.continueSupported).toBe(true);+ });+});diff --git a/client/src/hooks/useGenerationsByLatest.ts b/client/src/hooks/useGenerationsByLatest.tsindex 88c02511f7..4349291177 100644--- a/client/src/hooks/useGenerationsByLatest.ts+++ b/client/src/hooks/useGenerationsByLatest.ts@@ -1,4 +1,4 @@-import { EModelEndpoint, isAssistantsEndpoint } from 'librechat-data-provider';+import { Constants, EModelEndpoint, isAssistantsEndpoint } from 'librechat-data-provider';type TUseGenerations = {error?: boolean;@@ -35,10 +35,14 @@ export default function useGenerationsByLatest({].find((e) => e === endpoint),);+ /** The tool-call-limit notice already offers Keep going / Answer now. The hover+ * Continue would re-submit the parent user turn with `isContinued`, a different+ * and weaker path sitting next to the intended one. */const continueSupported =latestMessageId === messageId &&- finish_reason &&+ Boolean(finish_reason) &&finish_reason !== 'stop' &&+ finish_reason !== Constants.TOOL_CALL_LIMIT_FINISH_REASON &&!isEditing &&!isSubmitting &&!searchResult &&diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex db284326f6..3550b892e3 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -1189,6 +1189,7 @@"com_ui_details": "Details","com_ui_disabled": "Disabled","com_ui_disabling": "Disabling...",+ "com_ui_dismiss": "Dismiss","com_ui_done": "Done","com_ui_download": "Download","com_ui_download_artifact": "Download Artifact",@@ -1850,6 +1851,7 @@"com_ui_resource": "resource","com_ui_respond": "Respond","com_ui_response": "Response",+ "com_ui_response_incomplete": "The response is incomplete; it's either still processing, was cancelled, or censored. Refresh or try a different prompt.","com_ui_result": "Result","com_ui_result_found": "{{count}} result found","com_ui_results_found": "{{count}} results found",@@ -2335,6 +2337,12 @@"com_ui_token_url": "Token URL","com_ui_tokens": "tokens","com_ui_tool_background": "Background execution",+ "com_ui_tool_call_limit_answer": "Answer now",+ "com_ui_tool_call_limit_answer_prompt": "Stop using tools and answer now with what you already have. Say briefly what you could not finish checking.",+ "com_ui_tool_call_limit_body": "The agent used every step allowed in a single turn, so it stopped before finishing. Everything above is saved. Choose how to carry on.",+ "com_ui_tool_call_limit_continue": "Keep going",+ "com_ui_tool_call_limit_continue_prompt": "Keep going from where you stopped.",+ "com_ui_tool_call_limit_title": "Reached the tool call limit for this turn","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/client/src/utils/__tests__/messages.test.ts b/client/src/utils/__tests__/messages.test.tsindex 517e1a4014..492d942e33 100644--- a/client/src/utils/__tests__/messages.test.ts+++ b/client/src/utils/__tests__/messages.test.ts@@ -300,6 +300,7 @@ const makeFieldsMsg = (over: Partial<TMessage> = {}): TMessage =>text: 'hello',error: false,unfinished: false,+ finish_reason: 'stop',createdAt: '2026-07-01T00:00:00.000Z',depth: 0,isCreatedByUser: false,@@ -321,6 +322,7 @@ const FIELD_MUTATIONS: Array<[string, Partial<TMessage>]> = [['text', { text: 'changed' }],['error', { error: true }],['unfinished', { unfinished: true }],+ ['finish_reason', { finish_reason: 'tool_call_limit' }],['createdAt', { createdAt: '2026-07-02T00:00:00.000Z' }],['depth', { depth: 3 }],['isCreatedByUser', { isCreatedByUser: true }],diff --git a/client/src/utils/messages.ts b/client/src/utils/messages.tsindex e8afaac986..532add8de9 100644--- a/client/src/utils/messages.ts+++ b/client/src/utils/messages.ts@@ -826,6 +826,9 @@ export function areMessageFieldsEqual(prevMsg.text === nextMsg.text &&prevMsg.error === nextMsg.error &&prevMsg.unfinished === nextMsg.unfinished &&+ /** Read by the row: `useGenerationsByLatest` gates the Continue button on it and+ * `ContentRender` renders the tool-call-limit notice from it. */+ prevMsg.finish_reason === nextMsg.finish_reason &&prevMsg.createdAt === nextMsg.createdAt &&prevMsg.depth === nextMsg.depth &&prevMsg.isCreatedByUser === nextMsg.isCreatedByUser &&diff --git a/packages/api/src/agents/__tests__/run-summarization.test.ts b/packages/api/src/agents/__tests__/run-summarization.test.tsindex 5f5e7f17e3..5132ba889b 100644--- a/packages/api/src/agents/__tests__/run-summarization.test.ts+++ b/packages/api/src/agents/__tests__/run-summarization.test.ts@@ -3132,12 +3132,24 @@ describe('ask_user_question run wiring', () => {const firstAgent = (config: Record<string, unknown>) =>(config.graphConfig as { agents: Array<Record<string, unknown>> }).agents[0];+ /**+ * Every run now carries a `PostToolBatch`-only registry for step-budget+ * awareness, so registry presence no longer proves HITL wiring. What still+ * distinguishes an approval-gated run is the `PreToolUse` policy hook, and+ * `PostToolBatch` is deliberately outside the SDK's+ * `RESULT_ALTERING_HOOK_EVENTS`, so it cannot disable eager tool prestart.+ */+ const hasToolApprovalPolicyHook = (config: Record<string, unknown>) =>+ (config.hooks as { hasHookFor?: (event: string) => boolean } | undefined)?.hasHookFor?.(+ 'PreToolUse',+ ) === true;+it('attaches the checkpointer WITHOUT humanInTheLoop when hitlCapable and the ask tool is present (approval disabled)', async () => {const config = await runAndGetConfig(makeAgent({ tools: [askToolInstance] }), {hitlCapable: true,});expect(config).not.toHaveProperty('humanInTheLoop');- expect(config).not.toHaveProperty('hooks');+ expect(hasToolApprovalPolicyHook(config)).toBe(false);expect(getCheckpointer(config)).toBeDefined();const agent = firstAgent(config);// The tool rides the in-graph direct path (graphTools) — never thediff --git a/packages/api/src/agents/errors.spec.ts b/packages/api/src/agents/errors.spec.tsindex 8eb490912e..866236e9ef 100644--- a/packages/api/src/agents/errors.spec.ts+++ b/packages/api/src/agents/errors.spec.ts@@ -1,4 +1,5 @@import { ErrorTypes } from 'librechat-data-provider';+import { GraphRecursionError } from '@langchain/langgraph';import {GENERIC_PROVIDER_ERROR,getLangChainErrorCode,@@ -6,6 +7,7 @@ import {getUserFacingProviderError,isFatalAgentInitializationError,AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,+ isStepLimitError,} from './errors';describe('isFatalAgentInitializationError', () => {@@ -106,3 +108,53 @@ describe('LangChain provider error text', () => {});});});++describe('isStepLimitError', () => {+ it('recognizes the real error LangGraph throws when a graph runs out of supersteps', () => {+ /** Constructed exactly as `pregel/index.js` does on `loop.status === 'out_of_steps'`. */+ const thrown = new GraphRecursionError(+ 'Recursion limit of 50 reached without hitting a stop condition. You can increase the limit by setting the "recursionLimit" config key.',+ { lc_error_code: 'GRAPH_RECURSION_LIMIT' },+ );++ expect(isStepLimitError(thrown)).toBe(true);+ });++ it('matches on `lc_error_code` alone, so a minified class name cannot break detection', () => {+ expect(isStepLimitError({ lc_error_code: 'GRAPH_RECURSION_LIMIT' })).toBe(true);+ });++ it('matches on `name` alone, so an error rebuilt without fields is still recognized', () => {+ expect(isStepLimitError({ name: 'GraphRecursionError' })).toBe(true);+ });++ it('unwraps a graph error rethrown inside a wrapper', () => {+ const wrapper = new Error('agent run failed', {+ cause: new Error('node failed', {+ cause: new GraphRecursionError('Recursion limit of 50 reached', {+ lc_error_code: 'GRAPH_RECURSION_LIMIT',+ }),+ }),+ });++ expect(isStepLimitError(wrapper)).toBe(true);+ });++ it('terminates on a self-referential cause chain instead of looping forever', () => {+ const looping: { name: string; cause?: unknown } = { name: 'SomeError' };+ looping.cause = looping;++ expect(isStepLimitError(looping)).toBe(false);+ });++ it.each([+ undefined,+ null,+ 'GraphRecursionError',+ new Error('rate limited'),+ { lc_error_code: 'GRAPH_VALUE_ERROR' },+ { name: 'GraphInterrupt' },+ ])('leaves case %# on the ordinary error path', (error) => {+ expect(isStepLimitError(error)).toBe(false);+ });+});diff --git a/packages/api/src/agents/errors.ts b/packages/api/src/agents/errors.tsindex 1cb6a7bc6a..9a98ca9894 100644--- a/packages/api/src/agents/errors.ts+++ b/packages/api/src/agents/errors.ts@@ -101,3 +101,44 @@ export function getUserFacingProviderError(error: unknown, protectionEnabled: bo}return stripLangChainTroubleshootingUrl(error.message) || GENERIC_PROVIDER_ERROR;}++/**+ * LangGraph's stable machine identifier for "the graph ran out of supersteps".+ * Set as `lc_error_code` on the `GraphRecursionError` thrown by the Pregel loop+ * when `loop.status === 'out_of_steps'`.+ */+const GRAPH_RECURSION_LIMIT_CODE = 'GRAPH_RECURSION_LIMIT';++/** Bounded `cause` walk: a graph error may be rethrown wrapped by an outer node. */+const MAX_CAUSE_DEPTH = 4;++/**+ * Whether `error` is the agent graph exhausting its per-turn step budget+ * (`recursionLimit`), as opposed to anything actually going wrong.+ *+ * This is a normal terminal condition, not a failure: the turn is persisted as+ * `unfinished` with `Constants.TOOL_CALL_LIMIT_FINISH_REASON` so the UI can offer+ * to continue, instead of surfacing a red error bubble the user cannot act on.+ *+ * Both markers are checked because they fail independently. `lc_error_code` is the+ * documented contract but is only present on errors constructed with the fields+ * argument, while `name` is assigned in the constructor body and therefore survives+ * class-name minification. Either one alone is sufficient evidence.+ */+export function isStepLimitError(error: unknown): boolean {+ let current = error;+ for (let depth = 0; depth < MAX_CAUSE_DEPTH && current != null; depth++) {+ if (typeof current !== 'object') {+ return false;+ }+ const candidate = current as { lc_error_code?: unknown; name?: unknown; cause?: unknown };+ if (+ candidate.lc_error_code === GRAPH_RECURSION_LIMIT_CODE ||+ candidate.name === 'GraphRecursionError'+ ) {+ return true;+ }+ current = candidate.cause;+ }+ return false;+}diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex 2f1d2c6002..81326fb658 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -42,6 +42,7 @@ export * from './resources';export * from './responses';export * from './skills';export * from './phases';+export * from './stepBudget';export * from './startup';export * from './subagentThreads';export * from './subagentActivity';diff --git a/packages/api/src/agents/openai/service.spec.ts b/packages/api/src/agents/openai/service.spec.tsindex a1f7a25dba..8c91c71212 100644--- a/packages/api/src/agents/openai/service.spec.ts+++ b/packages/api/src/agents/openai/service.spec.ts@@ -19,7 +19,7 @@ type CreateRunArgs = {appConfig?: Record<string, unknown>;requestBody?: Record<string, unknown>;};-type ProcessStreamConfig = { configurable?: Record<string, unknown> };+type ProcessStreamConfig = { configurable?: Record<string, unknown>; recursionLimit?: number };function createMockReq(user?: Record<string, unknown>,@@ -126,6 +126,19 @@ describe('createAgentChatCompletion - MCP permission user propagation', () => {expect(streamConfig.configurable?.user_id).toBe('user-123');});+ it('invokes the graph with the same resolved recursion limit the step-budget hook uses', async () => {+ deps.appConfig = { endpoints: { agents: { recursionLimit: 123 } } };++ await createAgentChatCompletion(+ createMockReq({ id: 'user-123', role: 'USER' }),+ createMockRes(),+ deps,+ );++ const streamConfig = processStream.mock.calls[0][1] as ProcessStreamConfig;+ expect(streamConfig.recursionLimit).toBe(123);+ });+it('falls back to a bare id when no authenticated user is attached', async () => {const req = createMockReq(undefined);diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.tsindex f8f5b01bed..9713486b9d 100644--- a/packages/api/src/agents/openai/service.ts+++ b/packages/api/src/agents/openai/service.ts@@ -25,6 +25,7 @@ import type {MessageFilterConfig,MessageFilterPiiConfig,StatefulCodeEnvironment,+ TAgentsEndpoint,} from 'librechat-data-provider';import type { Response as ServerResponse, Request } from 'express';import type {@@ -73,6 +74,7 @@ import { contentFilterUninspectableResponse } from '~/protection/files';import { createMCPRuntimeRequestBody } from '~/mcp/request';import { getUserFacingProviderError } from '../errors';import { collectReachableAgents } from '../traversal';+import { resolveRecursionLimit } from '../config';import { getDynamicToolContexts } from '../hitl';import { createSafeUser } from '~/utils';@@ -164,6 +166,7 @@ interface InitializedAgent {subagentAgentConfigs?: InitializedAgent[];/** Names of tools with the host-injected `intent` label param (see `agents/intent.ts`). */intentToolNames?: string[];+ recursion_limit?: number;[key: string]: unknown;}@@ -819,6 +822,10 @@ export async function createAgentChatCompletion(? { intentToolNames: initializedAgent.intentToolNames }: {}),},+ recursionLimit: resolveRecursionLimit(+ agentsConfig as Partial<TAgentsEndpoint> | undefined,+ initializedAgent,+ ),signal: abortController.signal,streamMode: 'values',version: 'v2',diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.tsindex 619846bf54..a76221b03f 100644--- a/packages/api/src/agents/run.ts+++ b/packages/api/src/agents/run.ts@@ -79,11 +79,15 @@ import {ASK_USER_QUESTION_TOOL_NAME,createAskUserQuestionTool,} from '~/agents/hitl/askUserQuestionTool';+import {+ resolveStreamLimits,+ resolveSubagentMaxTurns,+ resolveRecursionLimit,+} from '~/agents/config';import { applyCustomHandoffPromptKeyCompatibility } from '~/agents/handoffPromptKeyCompatibility';import { stripIntentFromToolRegistry, stripIntentFromToolDefinitions } from '~/agents/intent';import { extractDefaultParams, resolveReasoningParams } from '~/endpoints/openai/llm';import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';-import { resolveStreamLimits, resolveSubagentMaxTurns } from '~/agents/config';import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from '~/agents/tools';import { buildAgentInitialToolSessions } from '~/agents/codeFilesSession';import { getProviderConfig } from '~/endpoints/config/providers';@@ -91,6 +95,7 @@ import { resolveHeaders, createSafeUser } from '~/utils/env';import { getAgentCheckpointer } from '~/agents/checkpointer';import { getPluginHookSource } from '~/agents/hooks/source';import { getOpenAIConfig } from '~/endpoints/openai/config';+import { createStepBudgetHook } from '~/agents/stepBudget';import { buildHITLRunWiring } from '~/agents/hitl/runtime';import { buildLangfuseConfig } from '~/langfuse/config';import { resolveConfigHeaders } from '~/utils/headers';@@ -1996,6 +2001,23 @@ export async function createRun({stopFinalizeRegistry.register('StopFinalize', { hooks: [steering.terminalHook] });}}+ /**+ * Step-budget awareness. Registered unconditionally (no config, no checkpointer,+ * no SDK capability gate, since `additionalContext` has been part of `BaseHookOutput`+ * since hooks shipped) because running out of steps mid-turn is a failure mode on+ * every ingress, and a model that knows its budget is running low usually avoids+ * it. Registered after the label/steer hooks so their content-slot ordering is+ * untouched; `additionalContexts` accumulate independently of injected messages.+ */+ hooks = hooks ?? new HookRegistry();+ hooks.register('PostToolBatch', {+ hooks: [+ createStepBudgetHook({+ recursionLimit: resolveRecursionLimit(agentsEndpointConfig, agents[0]),+ }),+ ],+ internal: true,+ });/*** Deployment-plugin hooks (Agent Plugins `ai.librechat/hooks/hooks.json`)* register last so internal policy hooks (HITL, labels, steering) keepdiff --git a/packages/api/src/agents/stepBudget.spec.ts b/packages/api/src/agents/stepBudget.spec.tsnew file mode 100644index 0000000000..0e780ea2e7--- /dev/null+++ b/packages/api/src/agents/stepBudget.spec.ts@@ -0,0 +1,142 @@+import type { PostToolBatchHookInput, PostToolBatchHookOutput } from '@librechat/agents';+import { createStepBudgetHook, remainingToolRounds, buildBudgetNotice } from './stepBudget';++jest.mock('@librechat/data-schemas', () => ({+ logger: { debug: jest.fn(), warn: jest.fn(), error: jest.fn(), info: jest.fn() },+}));++function batch(toolNames: string[] = ['search']): PostToolBatchHookInput {+ return {+ hook_event_name: 'PostToolBatch',+ runId: 'run-1',+ entries: toolNames.map((toolName, index) => ({+ toolName,+ toolInput: {},+ toolUseId: `t${index}`,+ status: 'success',+ })),+ };+}++const signal = new AbortController().signal;++/** Drives `rounds` tool batches through one hook and returns each round's context. */+async function drain(recursionLimit: number, rounds: number): Promise<Array<string | undefined>> {+ const hook = createStepBudgetHook({ recursionLimit });+ const emitted: Array<string | undefined> = [];+ for (let i = 0; i < rounds; i++) {+ const output: PostToolBatchHookOutput = await hook(batch(), signal);+ emitted.push(output.additionalContext);+ }+ return emitted;+}++describe('remainingToolRounds', () => {+ it('reserves a step for the final answer so a budget is never spent entirely on tools', () => {+ /** 50 steps: round 24 ends on step 48, leaving step 49 to answer. */+ expect(remainingToolRounds(50, 24)).toBe(0);+ expect(remainingToolRounds(50, 23)).toBe(1);+ });++ it('never reports negative headroom once the budget is already overspent', () => {+ expect(remainingToolRounds(50, 25)).toBe(0);+ expect(remainingToolRounds(50, 400)).toBe(0);+ });++ it('reports no headroom for a limit too small to afford a round plus an answer', () => {+ expect(remainingToolRounds(2, 0)).toBe(0);+ expect(remainingToolRounds(3, 1)).toBe(0);+ });++ it('decreases by exactly one round per round spent', () => {+ const start = remainingToolRounds(101, 0);+ expect(start - remainingToolRounds(101, 1)).toBe(1);+ expect(remainingToolRounds(101, 1) - remainingToolRounds(101, 2)).toBe(1);+ });+});++describe('createStepBudgetHook', () => {+ it('stays silent while the budget is ample, so an ordinary turn never sees a notice', async () => {+ const emitted = await drain(50, 20);+ expect(emitted.every((context) => context === undefined)).toBe(true);+ });++ it('counts rounds, not calls: a parallel batch costs one round', async () => {+ const hook = createStepBudgetHook({ recursionLimit: 9 });++ /** 9 steps affords 4 rounds; one batch of three calls must consume only one. */+ expect(await hook(batch(['a', 'b', 'c']), signal)).toEqual({+ additionalContext: buildBudgetNotice(3),+ });+ });++ it('counts down over the final rounds instead of repeating one warning', async () => {+ const emitted = await drain(50, 24);+ const warnings = emitted.filter((context): context is string => context != null);++ expect(warnings).toEqual([+ buildBudgetNotice(3),+ buildBudgetNotice(2),+ buildBudgetNotice(1),+ buildBudgetNotice(0),+ ]);+ expect(new Set(warnings).size).toBe(warnings.length);+ });++ it('tells the model to stop calling tools once nothing is left for a result', async () => {+ const emitted = await drain(50, 24);+ const last = emitted[emitted.length - 1];++ expect(last).toContain('no tool-calling budget left');+ expect(last).toContain('Do not call any more tools');+ });++ it('warns from the very first round when the configured limit is tiny', async () => {+ /** 7 steps affords 3 rounds, so round 1 already sits inside the warning band. */+ const emitted = await drain(7, 1);+ expect(emitted[0]).toBe(buildBudgetNotice(2));+ });++ it('keeps warning after the budget is blown rather than falling silent', async () => {+ const emitted = await drain(50, 30);+ expect(emitted.slice(24).every((context) => context === buildBudgetNotice(0))).toBe(true);+ });++ it('tracks each run independently', async () => {+ const first = createStepBudgetHook({ recursionLimit: 7 });+ const second = createStepBudgetHook({ recursionLimit: 7 });++ /** Spends the first run's whole budget. */+ await first(batch(), signal);+ await first(batch(), signal);+ expect(await first(batch(), signal)).toEqual({ additionalContext: buildBudgetNotice(0) });++ /** The second run must still see a full budget, not the first run's tally. */+ expect(await second(batch(), signal)).toEqual({ additionalContext: buildBudgetNotice(2) });+ });++ it('does not count an empty batch against the budget', async () => {+ const hook = createStepBudgetHook({ recursionLimit: 7 });++ expect(await hook(batch([]), signal)).toEqual({});+ expect(await hook(batch(), signal)).toEqual({ additionalContext: buildBudgetNotice(2) });+ });++ it('does not count a subagent-scoped batch against the parent budget', async () => {+ const hook = createStepBudgetHook({ recursionLimit: 7 });++ expect(await hook({ ...batch(), agentId: 'child' }, signal)).toEqual({});+ expect(await hook(batch(), signal)).toEqual({ additionalContext: buildBudgetNotice(2) });+ });+});++describe('buildBudgetNotice', () => {+ it('hedges the estimate, because unseen graph nodes can also spend steps', () => {+ expect(buildBudgetNotice(3)).toContain('about 3 more tool-calling rounds');+ });++ it('drops the hedge when exactly one round remains', () => {+ expect(buildBudgetNotice(1)).toContain('1 more tool-calling round left');+ expect(buildBudgetNotice(1)).not.toContain('about');+ });+});diff --git a/packages/api/src/agents/stepBudget.ts b/packages/api/src/agents/stepBudget.tsnew file mode 100644index 0000000000..4622da34a3--- /dev/null+++ b/packages/api/src/agents/stepBudget.ts@@ -0,0 +1,106 @@+import { logger } from '@librechat/data-schemas';+import type { HookCallback } from '@librechat/agents';++/**+ * Graph supersteps a single tool-calling round costs: the tool node that runs the+ * batch, plus the model node that consumes its results. Derived from the agent+ * graph topology (`agentNode -> toolNode -> agentNode`), the same relationship the+ * `com_ui_agent_recursion_limit_info` copy describes to admins and that+ * `SUBAGENT_RECURSION_MULTIPLIER` encodes for child runs.+ */+const STEPS_PER_TOOL_ROUND = 2;++/**+ * Supersteps reserved for the final model call that answers without calling tools.+ * A turn that spends its last step on a tool node produces no answer at all, so the+ * budget must always hold one step back.+ */+const STEPS_RESERVED_FOR_FINAL_ANSWER = 1;++/**+ * Remaining-round count at or below which the model is told to start wrapping up.+ * Three rounds is enough runway to finish a partially gathered answer while being+ * late enough that a normal short turn never sees the notice at all.+ */+const WARN_AT_REMAINING_ROUNDS = 3;++/**+ * Upper bound on the tool-calling rounds still affordable after `roundsUsed` have+ * completed, leaving room for a final answer.+ *+ * An upper bound rather than an exact figure: summarization, handoff and multi-agent+ * routing nodes also consume supersteps but are invisible at the tool boundary, so+ * the real number can only be lower. The notice wording is hedged accordingly, because it+ * exists to convey urgency, and {@link isStepLimitError} still catches the wall.+ */+export function remainingToolRounds(recursionLimit: number, roundsUsed: number): number {+ const spent = roundsUsed * STEPS_PER_TOOL_ROUND + STEPS_RESERVED_FOR_FINAL_ANSWER;+ const affordable = Math.floor((recursionLimit - spent) / STEPS_PER_TOOL_ROUND);+ return Math.max(0, affordable);+}++/**+ * The context injected once the budget is nearly spent. Returned as+ * `additionalContext`, which the SDK consolidates into a single system-flavored+ * message placed immediately before the next model call, the last thing the model+ * reads before deciding whether to call another tool.+ *+ * Graph-state only: nothing here is persisted as message content, so the pressure+ * applies to this turn and does not accumulate across the conversation.+ */+export function buildBudgetNotice(remaining: number): string {+ if (remaining <= 0) {+ return [+ 'System notice: this turn has no tool-calling budget left.',+ 'Do not call any more tools; another tool call will be cut off before you can use its result.',+ 'Write your final answer now from what you already have, and state briefly what remains unresolved.',+ ].join(' ');+ }+ const rounds =+ remaining === 1 ? '1 more tool-calling round' : `about ${remaining} more tool-calling rounds`;+ return [+ `System notice: this turn has ${rounds} left before it is cut off.`,+ 'Stop broadening the search and start converging: use what you already have,',+ 'make only calls you cannot finish without, and leave room to write the final answer.',+ ].join(' ');+}++export interface StepBudgetHookOptions {+ /** The resolved graph `recursionLimit` this run was invoked with. */+ recursionLimit: number;+}++/**+ * Builds the run-scoped `PostToolBatch` hook that keeps the model aware of its+ * per-turn step budget.+ *+ * Hitting `recursionLimit` mid-turn is recoverable but never good: the user waits+ * for a turn that ends without an answer. Models are poor at tracking how many+ * calls they have made, so the fix is to tell them, counting down over the last+ * few rounds rather than announcing a budget they will ignore while it is ample.+ *+ * Counts tool *rounds*, not tool calls: a parallel batch of six calls is one node+ * execution and costs one step, so per-call counting would overstate consumption+ * six-fold. Empty batches and subagent-scoped events are skipped so only a real+ * root tool round advances the countdown.+ */+export function createStepBudgetHook({+ recursionLimit,+}: StepBudgetHookOptions): HookCallback<'PostToolBatch'> {+ let roundsUsed = 0;++ return async (input) => {+ if (input.agentId != null || input.entries.length === 0) {+ return {};+ }+ roundsUsed += 1;+ const remaining = remainingToolRounds(recursionLimit, roundsUsed);+ if (remaining > WARN_AT_REMAINING_ROUNDS) {+ return {};+ }+ logger.debug(+ `[stepBudget] Tool round ${roundsUsed} of a ${recursionLimit}-step budget; ~${remaining} rounds left, nudging the model to converge.`,+ );+ return { additionalContext: buildBudgetNotice(remaining) };+ };+}diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex a2fdbe96df..857067b784 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -3346,6 +3346,15 @@ export enum Constants {SUBAGENT = 'subagent',/** Poll tool for retrieving the status/result of a backgrounded tool call. */CHECK_BACKGROUND_TASK = 'check_background_task',+ /**+ * `finish_reason` stamped on an assistant message whose turn ended because the+ * agent exhausted its per-turn graph step budget (`recursionLimit`) rather than+ * because the model chose to stop. Distinct from a user abort: nothing failed and+ * nothing was cancelled, the turn simply ran out of room. The UI keys its+ * "tool call limit reached" notice off this value. The hover Continue control+ * is withheld for this reason because the notice already offers the way forward.+ */+ TOOL_CALL_LIMIT_FINISH_REASON = 'tool_call_limit',}/**