mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 15:33:45 +00:00
🚞 fix: Route Accepted Tool Calls Through the Live Agents API (#16401)
Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
parent
a329e01ac7
commit
19e01607e8
3 changed files with 184 additions and 212 deletions
|
|
@ -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 () => {
|
||||
|
|
|
|||
|
|
@ -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(),
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue