🚞 fix: Route Accepted Tool Calls Through the Live Agents API (#16401)

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-26 20:29:36 -04:00 • committed by GitHub
parent a329e01ac7
commit 19e01607e8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 184 additions and 212 deletions

View file

@ -219,13 +219,7 @@ jest.mock('@librechat/api', () => ({
buildAgentContextAttachmentsByAgentId: (...args) =>
mockBuildAgentContextAttachmentsByAgentId(...args),
createChunk: jest.fn().mockReturnValue({}),
/** Not stubbed: the outward tool-call index this allocates is the behavior the
* controller is responsible for wiring, so the spec runs the real projection. */
createOpenAIToolCallStream: (...args) =>
jest.requireActual('@librechat/api').createOpenAIToolCallStream(...args),
completeOpenAIToolCalls: jest.requireActual('@librechat/api').completeOpenAIToolCalls,
OpenAIRunStepHandler: jest.requireActual('@librechat/api').OpenAIRunStepHandler,
OpenAIRunStepDeltaHandler: jest.requireActual('@librechat/api').OpenAIRunStepDeltaHandler,
buildRunToolSet: jest.fn().mockReturnValue(new Set()),
buildInitialToolSessions: jest.fn().mockReturnValue(mockInitialSessions),
AgentRunEnvelopeError: MockAgentRunEnvelopeError,
@ -520,134 +514,8 @@ describe('OpenAIChatCompletionController', () => {
});
it.each([true, false])(
'projects interleaved calls and preserves the final stop (stream=%s)',
'keeps SDK- and provider-executed calls out of the mounted endpoint (stream=%s)',
async (streaming) => {
const api = require('@librechat/api');
const actual = jest.requireActual('@librechat/api');
const names = [
'createChunk',
'writeSSE',
'sendFinalChunk',
'buildNonStreamingResponse',
'createOpenAIStreamTracker',
'createOpenAIContentAggregator',
];
const original = names.map((name) => [name, api[name].getMockImplementation()]);
for (const name of names) api[name].mockImplementation(actual[name]);
req.body.stream = streaming;
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
const { customHandlers: h } = api.createRun.mock.calls.at(-1)[0];
const meta = { langgraph_node: 'agent=test', langgraph_step: 1 };
for (const [step, id, index] of [
['s1', 'a', 0],
['s2', 'b', 1],
]) {
await h.on_run_step.handle(
'on_run_step',
{
id: step,
stepDetails: {
type: 'tool_calls',
tool_calls: [{ id, name: 'get_time' }],
},
},
meta,
);
await h.on_run_step_delta.handle(
'on_run_step_delta',
{
id: step,
delta: {
type: 'tool_calls',
tool_calls: [{ id, name: 'get_time', index }],
},
},
meta,
);
}
for (const [index, city] of [
[0, 'Madrid'],
[1, 'Paris'],
]) {
await h.on_run_step_delta.handle(
'on_run_step_delta',
{
id: 's2',
delta: {
type: 'tool_calls',
tool_calls: [{ index, args: JSON.stringify({ city }) }],
},
},
meta,
);
}
await h.on_message_delta.handle(
'on_message_delta',
{
id: 'answer',
delta: {
content: [{ type: 'text', text: 'Both tools completed.' }],
},
},
{ ...meta, langgraph_step: 3 },
);
});
try {
await OpenAIChatCompletionController(req, res);
if (streaming) {
const frames = res.write.mock.calls
.map(([frame]) => frame)
.filter((frame) => frame !== 'data: [DONE]\n\n')
.map((frame) => JSON.parse(frame.slice(6)));
expect(frames.at(-1).choices[0].finish_reason).toBe('stop');
expect(
frames
.flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
.filter((call) => call.function?.arguments),
).toEqual([
{ index: 0, function: { arguments: '{"city":"Madrid"}' } },
{ index: 1, function: { arguments: '{"city":"Paris"}' } },
]);
} else {
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
choices: [
expect.objectContaining({
finish_reason: 'stop',
message: expect.objectContaining({
content: 'Both tools completed.',
tool_calls: [
{
id: 'a',
type: 'function',
function: { name: 'get_time', arguments: '{"city":"Madrid"}' },
},
{
id: 'b',
type: 'function',
function: { name: 'get_time', arguments: '{"city":"Paris"}' },
},
],
}),
}),
],
}),
);
}
} finally {
for (const [name, implementation] of original) api[name].mockImplementation(implementation);
}
},
);
it.each(
[true, false].flatMap((stream) =>
['native-string', 'wire-object', 'split', 'idless'].map((shape) => [stream, shape]),
),
)(
'publishes complete identity and arguments before terminal output (stream=%s, shape=%s)',
async (streaming, shape) => {
const api = require('@librechat/api');
const actual = jest.requireActual('@librechat/api');
const names = [
@ -663,34 +531,24 @@ describe('OpenAIChatCompletionController', () => {
req.body.stream = streaming;
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
const { customHandlers: h } = api.createRun.mock.calls.at(-1)[0];
await h.on_run_step.handle('on_run_step', {
id: 'complete',
stepDetails: {
type: 'tool_calls',
tool_calls: [
(() => {
if (shape === 'native-string')
return { id: 'a', name: 'get_time', args: '{"city":"Madrid"}' };
if (shape === 'wire-object')
return { id: 'a', function: { name: 'get_time', arguments: { city: 'Madrid' } } };
if (shape === 'idless') return { name: 'get_time', args: { city: 'Madrid' } };
return { id: 'a', name: 'get_', args: {} };
})(),
],
},
const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
expect(handlers.on_run_step).toBeUndefined();
expect(handlers.on_run_step_delta).toBeUndefined();
expect(handlers.on_run_step_completed).toBeUndefined();
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'accepted-internal',
agentId: 'agent-123',
toolCalls: [
{ id: 'internal', name: 'get_time', args: { city: 'Madrid' } },
{ id: 'provider', name: 'web_search', args: { query: 'weather' } },
],
toolCallDispositions: ['sdk', 'provider'],
invalidToolCalls: [],
});
await handlers.on_message_delta.handle('on_message_delta', {
delta: { content: [{ type: 'text', text: 'Both tools completed.' }] },
});
if (shape === 'split') {
for (const fragment of [
{ id: 'a', name: 'get_', index: 0, args: '{"city":"Madrid"}' },
{ index: 0, name: 'time' },
]) {
await h.on_run_step_delta.handle('on_run_step_delta', {
id: 'complete',
delta: { type: 'tool_calls', tool_calls: [fragment] },
});
}
}
});
try {
await OpenAIChatCompletionController(req, res);
@ -699,22 +557,16 @@ describe('OpenAIChatCompletionController', () => {
.map(([frame]) => frame)
.filter((frame) => frame !== 'data: [DONE]\n\n')
.map((frame) => JSON.parse(frame.slice(6)));
expect(frames.flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])).toEqual([]);
expect(
frames
.flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
.map((call) => call.function?.arguments ?? '')
.join(''),
).toBe('{"city":"Madrid"}');
expect(
frames
.flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
.find((call) => call.id).function.name,
).toBe('get_time');
expect(frames.at(-1).choices[0].finish_reason).toBe('tool_calls');
frames.some((frame) => frame.choices[0].delta.content === 'Both tools completed.'),
).toBe(true);
expect(frames.at(-1).choices[0].finish_reason).toBe('stop');
} else {
expect(
res.json.mock.calls[0][0].choices[0].message.tool_calls[0].function.arguments,
).toBe('{"city":"Madrid"}');
const choice = res.json.mock.calls[0][0].choices[0];
expect(choice.message.content).toBe('Both tools completed.');
expect(choice.message.tool_calls).toBeUndefined();
expect(choice.finish_reason).toBe('stop');
}
} finally {
for (const [name, implementation] of originals)
@ -723,21 +575,146 @@ describe('OpenAIChatCompletionController', () => {
},
);
it('records completed model usage even when terminal snapshot validation fails', async () => {
it.each([true, false])(
'publishes only the accepted client call after a model claim (stream=%s)',
async (streaming) => {
const api = require('@librechat/api');
const actual = jest.requireActual('@librechat/api');
const names = [
'createChunk',
'writeSSE',
'sendFinalChunk',
'buildNonStreamingResponse',
'createOpenAIStreamTracker',
'createOpenAIContentAggregator',
];
const originals = names.map((name) => [name, api[name].getMockImplementation()]);
for (const name of names) api[name].mockImplementation(actual[name]);
req.body.stream = streaming;
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'discarded',
agentId: 'agent-123',
messageId: 'claimed-message',
toolCalls: [{ id: 'stale', name: 'stale_tool', args: { secret: 'DO_NOT_SEND' } }],
toolCallDispositions: ['client'],
invalidToolCalls: [],
});
await handlers.on_model_tools_claimed.handle('on_model_tools_claimed', {
type: 'model_tools_claimed',
agentId: 'agent-123',
messageId: 'claimed-message',
});
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'accepted-client',
agentId: 'agent-123',
toolCalls: [
{ id: 'a', name: 'get_time', args: { city: 'Madrid' } },
{ id: 'a', name: 'get_time', args: { city: 'Paris' } },
],
toolCallDispositions: ['client', 'client'],
invalidToolCalls: [],
});
});
try {
await OpenAIChatCompletionController(req, res);
if (streaming) {
const frames = res.write.mock.calls
.map(([frame]) => frame)
.filter((frame) => frame !== 'data: [DONE]\n\n')
.map((frame) => JSON.parse(frame.slice(6)));
const calls = frames.flatMap((frame) => frame.choices[0].delta.tool_calls ?? []);
expect(calls).toEqual([
{ index: 0, id: 'a', type: 'function', function: { name: 'get_time', arguments: '' } },
{ index: 0, function: { arguments: '{"city":"Madrid"}' } },
{
index: 1,
id: 'call_0',
type: 'function',
function: { name: 'get_time', arguments: '' },
},
{ index: 1, function: { arguments: '{"city":"Paris"}' } },
]);
expect(frames.at(-1).choices[0].finish_reason).toBe('tool_calls');
} else {
const choice = res.json.mock.calls[0][0].choices[0];
expect(choice.message.tool_calls).toEqual([
{
id: 'a',
type: 'function',
function: { name: 'get_time', arguments: '{"city":"Madrid"}' },
},
{
id: 'call_0',
type: 'function',
function: { name: 'get_time', arguments: '{"city":"Paris"}' },
},
]);
expect(choice.finish_reason).toBe('tool_calls');
}
expect(JSON.stringify(res.write.mock.calls)).not.toContain('DO_NOT_SEND');
expect(JSON.stringify(res.json.mock.calls)).not.toContain('DO_NOT_SEND');
} finally {
for (const [name, implementation] of originals)
api[name].mockImplementation(implementation);
}
},
);
it('discards client delegation on failure and ignores late accepted responses', async () => {
const api = require('@librechat/api');
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
const h = require('@librechat/api').createRun.mock.calls.at(-1)[0].customHandlers;
await h.on_run_step.handle('on_run_step', {
id: 'bad',
stepDetails: {
type: 'tool_calls',
tool_calls: [{ id: 'a', function: { name: 'get_time', arguments: 'NOT-JSON' } }],
},
const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'before-failure',
agentId: 'agent-123',
toolCalls: [{ id: 'a', name: 'get_time', args: { secret: 'DO_NOT_SEND' } }],
toolCallDispositions: ['client'],
invalidToolCalls: [],
});
throw new Error('provider failed');
});
await OpenAIChatCompletionController(req, res);
expect(JSON.stringify(res.json.mock.calls)).not.toContain('DO_NOT_SEND');
expect(api.buildNonStreamingResponse).not.toHaveBeenCalled();
const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'too-late',
agentId: 'agent-123',
toolCalls: [{ id: 'late', name: 'get_time', args: { city: 'Late' } }],
toolCallDispositions: ['client'],
invalidToolCalls: [],
});
expect(JSON.stringify(res.json.mock.calls)).not.toContain('Late');
});
it('fails closed on an invalid accepted client call without returning its arguments', async () => {
const api = require('@librechat/api');
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
await handlers.on_model_response.handle('on_model_response', {
type: 'model_response',
id: 'invalid-client',
agentId: 'agent-123',
toolCalls: [{ id: 'a', name: '', args: { secret: 'PRIVATE_ARGUMENTS' } }],
toolCallDispositions: ['client'],
invalidToolCalls: [],
});
});
await OpenAIChatCompletionController(req, res);
expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);
expect(require('@librechat/api').buildNonStreamingResponse).not.toHaveBeenCalled();
expect(JSON.stringify(res.json.mock.calls)).not.toContain('NOT-JSON');
expect(mockExecution.settle).toHaveBeenCalledWith(
expect.objectContaining({ message: 'Accepted tool call is missing its name' }),
);
expect(api.buildNonStreamingResponse).not.toHaveBeenCalled();
expect(JSON.stringify(res.json.mock.calls)).not.toContain('PRIVATE_ARGUMENTS');
});
it('enrolls, starts, and settles the remote execution lifecycle', async () => {

View file

@ -1,6 +1,9 @@
const { nanoid } = require('nanoid');
const { logger } = require('@librechat/data-schemas');
const { Callback, formatAgentMessages } = require('@librechat/agents');
const {
createOpenAIToolCallStream: createAcceptedToolCallStream,
} = require('@librechat/agents/openai');
const {
EModelEndpoint,
ResourceType,
@ -60,9 +63,6 @@ const {
createToolExecuteHandler,
createOwnedToolEndHandler,
buildNonStreamingResponse,
OpenAIRunStepHandler,
OpenAIRunStepDeltaHandler,
createOpenAIToolCallStream,
completeOpenAIToolCalls,
createOpenAIStreamTracker,
resolveAgentScopedSkillIds,
@ -981,12 +981,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
};
/**
* Shared by both run-step events, because the outward index a client keys
* tool-call fragments by is allocated per call and belongs to neither
* event alone.
*/
const toolCallStream = createOpenAIToolCallStream({
const toolCallStream = createAcceptedToolCallStream({
signal: execution.signal,
toolCalls: isStreaming ? tracker.toolCalls : aggregator.toolCalls,
...(isStreaming && {
@ -996,6 +991,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
// Event handlers for OpenAI-compatible streaming
const handlers = {
...toolCallStream.handlers,
// Text content streaming
on_message_delta: createHandler((data) => {
const content = data?.delta?.content;
@ -1021,12 +1017,6 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
}),
// Tool call initiation - declares id and name (from on_run_step)
on_run_step: new OpenAIRunStepHandler(toolCallStream),
// Tool call argument streaming (from on_run_step_delta)
on_run_step_delta: new OpenAIRunStepDeltaHandler(toolCallStream),
// Usage tracking
on_chat_model_end: {
handle: (_event, data, metadata, graph) => {
@ -1038,7 +1028,6 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
},
},
on_run_step_completed: new OpenAIRunStepHandler(toolCallStream),
// Use proper ToolEndHandler for processing artifacts (images, file citations, code output)
on_tool_end: createOwnedToolEndHandler(toolEndCallback, logger),
on_chain_stream: createHandler(),

View file

@ -1,22 +1,26 @@
# Agents API response projection
This module projects an **agent run**, which can include several model invocations and server-executed tools, onto an OpenAI-compatible response. It is not a transparent proxy for a single model completion. Changing tool execution ownership or terminal-turn selection is a separate protocol decision.
This module projects an **agent run**, which can include several model invocations and server-executed tools, onto an OpenAI-compatible response. It is not a transparent proxy for a single model completion. Only explicitly client-owned calls in graph-accepted model responses may become outward `tool_calls`; SDK- and provider-executed calls stay inside the run. Binding caller-supplied tool schemas and client execution remains a separate feature.
## Owners and boundaries
```text
provider adapter -> agents graph -> run-step declarations / argument deltas
provider adapter -> agents graph -> accepted model response + tool ownership
|
tool-call projection
SDK accepted-result projector
/ \
SSE chunks JSON accumulator
\ /
successful response completion
```
The Express controller and packaged `createAgentChatCompletion` service both use the same tool-call projection in streaming and non-streaming mode. The service's content handlers also share text, reasoning and usage handling between modes. The controller retains its existing run lifecycle, usage recording, artifact writes and authorization boundaries.
The mounted `/api/agents/v1/chat/completions` Express controller and packaged `createAgentChatCompletion` service both register the SDK's `on_model_response` and `on_model_tools_claimed` handlers for tool projection in streaming and non-streaming mode. Text, reasoning, usage, host-tool execution, billing, artifact writes and authorization retain their respective host handlers. Both hosts call the SDK projection's `finish` after successful execution and `abort` on failure.
## Identity
## Legacy run-step projector (compatibility export only)
`createOpenAIToolCallStream`, `OpenAIRunStepHandler` and `OpenAIRunStepDeltaHandler` remain exported for existing consumers and their contract tests. Neither in-repo Chat Completions host registers them. The following identity, fragment and terminal rules describe **only** this legacy projector.
### Identity
- A declaring run step owns call identity. Optional provider IDs are aliases, not a prerequisite. Declaration slots keep id-less calls distinct and make snapshot replay idempotent. Provider IDs can repeat in later steps and are not completion-wide identities.
- Outward indexes are allocated once per call across the response. Raw ID substrings are assembled by provider index; shared prefixes such as `call_` are never cross-call aliases. Calls without IDs receive `call_<index>`; collisions receive a suffix. Internal tool execution IDs are not rewritten.
@ -24,7 +28,7 @@ The Express controller and packaged `createAgentChatCompletion` service both use
- Callers without the graph object use metadata scope; callers without that metadata are isolated by step. This fallback cannot reconstruct a missing retry/segment identity.
- Explicit and identified provider indexes take precedence over positional fallback. Positions are used only for multi-call declarations. An unbound singleton may adopt its first provider index; it does not absorb arbitrary later indexes.
## Argument representations
### Argument representations
A run-step declaration can contain a **snapshot**: native `args` or OpenAI-shaped `function.arguments`. A run-step delta carries an **append-only fragment**. They must never be concatenated as though they were the same representation.
@ -38,7 +42,7 @@ Consequently, **tool-call chunks are published only at successful response compl
Name/ID/argument fragments are append-only and take precedence over the corresponding declaration snapshot. Snapshot replay is idempotent; raw fragments are not deduplicated because identical adjacent fragments can be legitimate and the events carry no sequence token. Split IDs require a provider index for unambiguous correlation. Exactly-once raw dispatch remains an upstream requirement.
## Terminal behavior
### Terminal behavior
`completeOpenAIToolCalls` wraps execution and owns the success/failure boundary. The controller schedules completed-run usage recording before final validation.
@ -53,13 +57,15 @@ Name/ID/argument fragments are append-only and take precedence over the correspo
Missing names, missing arguments, malformed JSON or unattributable argument data fail terminal projection with bounded errors that omit provider content. A snapshot never repairs a truncated raw stream. Projection bookkeeping is response-local and released on finish/abort; only successfully validated calls are materialized for the response builder. Publication seals before calling the transport, so a transport error or reentrant finish cannot duplicate calls. Already transmitted frames cannot be retracted.
The existing finish-reason policy is preserved: a response with final text after server-executed tools remains `stop`. Historical tool calls are still exposed by this API. This patch does not make it safe to interpret every advertised call as a new instruction for the caller to execute.
## Accepted-result terminal behavior
The SDK projector accepts only client-disposition calls from graph-accepted responses. A newer accepted text/internal result or a model-tool claim discards superseded calls for that agent. Calls are validated, given unique outward IDs and emitted at successful response completion; failed or aborted runs never publish buffered calls. Internal tools followed by a text answer finish with `stop` and no outward calls. The shared response builders use `tool_calls` as the finish reason when client calls exist without text.
## Verification and limits
- `toolCalls.contract.spec.ts`: shared field types, strings/objects, partial names and IDs, optional IDs, declaration order and transport reentrancy.
- `toolCalls.spec.ts`: identity, representations, ordering, replay, malformed input, failure and abort.
- `toolCalls.graph.spec.ts`: real SDK interleaving, complete-only chunks and stream segments.
- `service.spec.ts` and the Express controller spec: both response modes, actual serializers, fallback flush and failure/usage ordering.
- `toolCalls.graph.spec.ts`: real SDK run with an internally executed tool, plus legacy interleaving and segments.
- `service.spec.ts` and the Express controller spec: both response modes, actual serializers, internal-call suppression, accepted client calls, claim discard and failure behavior.
These tests do not run a live provider, real tool side effects, a distributed multi-agent deployment or a persisted resume. There is no new database, cache, authorization policy or migration. Code and built packages must deploy together. No cross-version event identity is invented when the upstream source omits it.
These tests do not run a live provider, a distributed multi-agent deployment or a persisted resume. The graph test executes a local tool but does not exercise the mounted HTTP server. There is no new database, cache, authorization policy or migration. Code and built packages must deploy together.