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
/**
* Open Responses API Service
*
* Core service for processing Open Responses API requests.
* Handles input conversion, message formatting, and request validation.
*/
import {
ContentTypes,
isCodeEnvironmentMode,
isCodeWorkspaceSelections,
} from 'librechat-data-provider';
import type { Response as ServerResponse } from 'express';
import type {
FunctionCallOutputItemParam,
RequestValidationResult,
FunctionCallItemParam,
ResponseRequest,
ResponseContext,
InputContent,
ModelContent,
InputItem,
Response,
Usage,
} from './types';
import type { UsageMetadata } from '~/stream/interfaces/IJobStore';
import {
writeDone,
emitResponseCompleted,
emitMessageItemAdded,
emitMessageItemDone,
emitTextContentPartAdded,
emitOutputTextDelta,
emitOutputTextDone,
emitTextContentPartDone,
emitFunctionCallItemAdded,
emitFunctionCallArgumentsDelta,
emitFunctionCallArgumentsDone,
emitFunctionCallItemDone,
emitFunctionCallOutputItem,
emitReasoningItemAdded,
emitReasoningContentPartAdded,
emitReasoningDelta,
emitReasoningDone,
emitReasoningContentPartDone,
emitReasoningItemDone,
type StreamHandlerConfig,
} from './handlers';
import { declaredClientToolNames, validateClientTools } from './clientTools';
import { aggregateCollectedUsage } from '../usage';
interface ResponseUsageAccumulator {
inputTokens: number;
outputTokens: number;
cachedTokens: number;
}
interface ModelUsageMetadata {
input_tokens?: number;
output_tokens?: number;
input_token_details?: {
cache_creation?: number;
cache_read?: number;
};
cache_creation_input_tokens?: number;
cache_read_input_tokens?: number;
}
function accumulateResponseUsage(
target: ResponseUsageAccumulator,
usage: ModelUsageMetadata,
): void {
target.inputTokens += usage.input_tokens ?? 0;
target.outputTokens += usage.output_tokens ?? 0;
target.cachedTokens +=
(usage.input_token_details?.cache_read ?? 0) + (usage.cache_read_input_tokens ?? 0);
}
/* =============================================================================
* REQUEST VALIDATION
* ============================================================================= */
/**
* Validate a request body
*/
export function validateResponseRequest(body: unknown): RequestValidationResult {
if (!body || typeof body !== 'object') {
return { valid: false, error: 'Request body is required' };
}
const request = body as Record<string, unknown>;
if (
request.code_environment_mode !== undefined &&
!isCodeEnvironmentMode(request.code_environment_mode)
) {
return { valid: false, error: 'code_environment_mode is invalid' };
}
if (
request.code_workspaces !== undefined &&
!isCodeWorkspaceSelections(request.code_workspaces)
) {
return {
valid: false,
error: 'code_workspaces must contain unique environment/workspace selections',
};
}
// Required: model
if (!request.model || typeof request.model !== 'string') {
return { valid: false, error: 'model is required and must be a string' };
}
// Required: input (string or array)
if (request.input === undefined || request.input === null) {
return { valid: false, error: 'input is required' };
}
if (typeof request.input !== 'string' && !Array.isArray(request.input)) {
return { valid: false, error: 'input must be a string or array of items' };
}
// Optional validations
if (request.stream !== undefined && typeof request.stream !== 'boolean') {
return { valid: false, error: 'stream must be a boolean' };
}
if (request.temperature !== undefined) {
const temp = request.temperature as number;
if (typeof temp !== 'number' || temp < 0 || temp > 2) {
return { valid: false, error: 'temperature must be a number between 0 and 2' };
}
}
if (request.max_output_tokens !== undefined) {
if (typeof request.max_output_tokens !== 'number' || request.max_output_tokens < 1) {
return { valid: false, error: 'max_output_tokens must be a positive number' };
}
}
if (
request.previous_response_id !== undefined &&
typeof request.previous_response_id !== 'string'
) {
return { valid: false, error: 'previous_response_id must be a string' };
}
const clientToolsError = validateClientTools(request.tools);
if (clientToolsError !== undefined) {
return { valid: false, error: clientToolsError };
}
if (Array.isArray(request.input)) {
const toolExchangeError = validateInputToolExchanges(
request.input as InputItem[],
declaredClientToolNames(request.tools),
);
if (toolExchangeError !== undefined) {
return { valid: false, error: toolExchangeError };
}
}
return { valid: true, request: request as unknown as ResponseRequest };
}
function isNonEmptyString(value: unknown): value is string {
return typeof value === 'string' && value !== '';
}
/**
* Validates the replayed tool exchanges in `input`.
*
* A turn is persisted as text, so `previous_response_id` does not carry a tool
* exchange: replaying the `function_call` together with its
* `function_call_output` is the only supported continuation. For a tool the
* caller executes, both halves are therefore required, and an unpaired half is
* the caller's error rather than something to hand to the provider — an
* unanswered tool call reaches the model as a malformed conversation and comes
* back as an opaque upstream failure.
*
* A call to a tool the *server* owns is not held to that rule. The server emits
* a `function_call` for its own tools but no `function_call_output`, so the
* usual continuation — appending the previous response's `output` to the next
* request's `input` — carries calls the caller cannot answer and never could.
* Those are dropped in {@link convertInputToMessages} instead of refused here.
*
* @returns An error message, or `undefined` when every exchange is well formed.
*/
export function validateInputToolExchanges(
input: InputItem[],
clientToolNames: ReadonlySet<string> = new Set<string>(),
): string | undefined {
const callIds = new Set<string>();
const clientCallIds = new Set<string>();
const outputCallIds = new Set<string>();
for (const item of input) {
if (item == null || typeof item !== 'object') {
continue;
}
if (item.type === 'function_call') {
const call = item as Partial<FunctionCallItemParam>;
if (!isNonEmptyString(call.call_id)) {
return 'each function_call requires a non-empty string call_id';
}
if (!isNonEmptyString(call.name)) {
return `function_call ${call.call_id} requires a non-empty string name`;
}
if (typeof call.arguments !== 'string') {
return `function_call ${call.call_id} requires arguments as a JSON string`;
}
if (callIds.has(call.call_id)) {
return `duplicate function_call call_id: ${call.call_id}`;
}
callIds.add(call.call_id);
if (clientToolNames.has(call.name)) {
clientCallIds.add(call.call_id);
}
continue;
}
if (item.type === 'function_call_output') {
const output = item as Partial<FunctionCallOutputItemParam>;
if (!isNonEmptyString(output.call_id)) {
return 'each function_call_output requires a non-empty string call_id';
}
if (typeof output.output !== 'string') {
return `function_call_output ${output.call_id} requires output as a string`;
}
if (outputCallIds.has(output.call_id)) {
return `duplicate function_call_output call_id: ${output.call_id}`;
}
outputCallIds.add(output.call_id);
}
}
for (const callId of clientCallIds) {
if (!outputCallIds.has(callId)) {
return `function_call ${callId} has no function_call_output in input; replay both items to continue a tool exchange`;
}
}
for (const callId of outputCallIds) {
if (!callIds.has(callId)) {
return `function_call_output ${callId} has no matching function_call in input`;
}
}
return undefined;
}
/**
* Check if validation failed
*/
export function isValidationFailure(
result: RequestValidationResult,
): result is { valid: false; error: string } {
return !result.valid;
}
/* =============================================================================
* INPUT CONVERSION
* ============================================================================= */
/** A replayed tool exchange, in the content-part shape LibreChat persists. */
export interface InternalToolCallPart {
type: ContentTypes.TOOL_CALL;
tool_call: {
id: string;
name: string;
/** Raw JSON string as the caller sent it; `formatAgentMessages` parses it. */
args: string;
/** The caller's result for this call. Present on every replayed pair. */
output: string;
};
}
/**
* Internal message format (LibreChat-compatible).
*
* There is deliberately no `tool` role and no `tool_call_id`: a tool result
* belongs to the `tool_call` part of the assistant turn that made the call.
* `formatMessage` has no branch for a tool role, so such a message formats as a
* SystemMessage and breaks the conversation for providers that accept a system
* message only in first position.
*/
export interface InternalMessage {
role: 'system' | 'user' | 'assistant';
content:
| string
| Array<{ type: string; text?: string; image_url?: unknown } | InternalToolCallPart>;
name?: string;
}
/**
* Convert Open Responses input to internal message format.
* Handles both string input and array of items.
*/
export function convertInputToMessages(input: string | InputItem[]): InternalMessage[] {
// Simple string input becomes a user message
if (typeof input === 'string') {
return [{ role: 'user', content: input }];
}
const messages: InternalMessage[] = [];
const outputsByCallId = collectFunctionCallOutputs(input);
/**
* The assistant message collecting the current run of consecutive
* `function_call` items. A parallel batch arrives as several calls in a row
* and belongs on ONE assistant turn, so providers that pair tool results
* against the calls of a single turn see the batch as it was issued.
*/
let pendingToolCallMessage: InternalMessage | null = null;
for (const item of input) {
if (item.type === 'item_reference') {
// Skip item references - they're handled by previous_response_id
continue;
}
if (item.type !== 'function_call') {
pendingToolCallMessage = null;
}
if (item.type === 'message') {
const messageItem = item as {
type: 'message';
role: string;
content: string | (InputContent | ModelContent)[];
};
let content: InternalMessage['content'];
if (typeof messageItem.content === 'string') {
content = messageItem.content;
} else if (Array.isArray(messageItem.content)) {
content = messageItem.content
.filter((part): part is InputContent | ModelContent => part != null)
.map((part) => {
if (part.type === 'input_text' || part.type === 'output_text') {
return { type: 'text', text: (part as { text?: string }).text ?? '' };
}
if (part.type === 'refusal') {
return { type: 'text', text: (part as { refusal?: string }).refusal ?? '' };
}
if (part.type === 'input_image') {
return {
type: 'image_url',
image_url: {
url: (part as { image_url?: string }).image_url,
detail: (part as { detail?: string }).detail,
},
};
}
if (part.type === 'input_file') {
const filePart = part as { filename?: string };
return { type: 'text', text: `[File: ${filePart.filename ?? 'unknown'}]` };
}
return null;
})
.filter((part): part is NonNullable<typeof part> => part != null);
} else {
content = '';
}
// Map developer role to system (LibreChat convention)
let role: InternalMessage['role'];
if (messageItem.role === 'developer') {
role = 'system';
} else if (messageItem.role === 'user') {
role = 'user';
} else if (messageItem.role === 'assistant') {
role = 'assistant';
} else if (messageItem.role === 'system') {
role = 'system';
} else {
role = 'user';
}
messages.push({ role, content });
}
/**
* A replayed call and its result become ONE `tool_call` content part on an
* assistant message, which is how LibreChat persists a tool exchange and
* the only shape `formatAgentMessages` reads: it emits the provider's
* tool-use block from the part and the paired tool result from
* `tool_call.output`. The OpenAI-style `{ role: 'tool' }` message this
* used to produce has no branch in `formatMessage`, which turned it into a
* SystemMessage mid-conversation — rejected outright by providers that
* allow a system message only as the first one.
*
* `function_call_output` items are consumed here through `outputsByCallId`,
* not emitted on their own; ingress validation has already established
* that a caller-executed call has exactly one output and vice versa.
*
* A call with no output is one of the server's own, replayed from a
* previous response that never carried a result for it. It is dropped:
* replaying it with an empty result would put an unanswered tool call in
* front of the provider, which is what the pairing rule exists to prevent.
*/
if (item.type === 'function_call') {
const fcItem = item as FunctionCallItemParam;
const output = outputsByCallId.get(fcItem.call_id);
if (output === undefined) {
continue;
}
const part: InternalToolCallPart = {
type: ContentTypes.TOOL_CALL,
tool_call: {
id: fcItem.call_id,
name: fcItem.name,
args: fcItem.arguments,
output,
},
};
if (pendingToolCallMessage != null && Array.isArray(pendingToolCallMessage.content)) {
pendingToolCallMessage.content.push(part);
} else {
pendingToolCallMessage = { role: 'assistant', content: [part] };
messages.push(pendingToolCallMessage);
}
}
// Reasoning items are typically not passed back as input
// They're model-generated and may be encrypted
}
return messages;
}
/** Indexes every `function_call_output` in the input by its `call_id`. */
function collectFunctionCallOutputs(input: InputItem[]): Map<string, string> {
const outputs = new Map<string, string>();
for (const item of input) {
if (item.type === 'function_call_output') {
const fcoItem = item as FunctionCallOutputItemParam;
outputs.set(fcoItem.call_id, fcoItem.output);
}
}
return outputs;
}
/* =============================================================================
* ERROR RESPONSE
* ============================================================================= */
/**
* Send an error response in Open Responses format
*/
export function sendResponsesErrorResponse(
res: ServerResponse,
statusCode: number,
message: string,
type: string = 'invalid_request',
code?: string,
): void {
res.status(statusCode).json({
error: {
type,
message,
code: code ?? null,
param: null,
},
});
}
/* =============================================================================
* RESPONSE CONTEXT
* ============================================================================= */
/**
* Generate a unique response ID
*/
export function generateResponseId(): string {
return `resp_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 8)}`;
}
/**
* Create a response context from request
*/
export function createResponseContext(
request: ResponseRequest,
responseId?: string,
): ResponseContext {
return {
responseId: responseId ?? generateResponseId(),
model: request.model,
createdAt: Math.floor(Date.now() / 1000),
previousResponseId: request.previous_response_id,
instructions: request.instructions,
};
}
/* =============================================================================
* STREAMING SETUP
* ============================================================================= */
/**
* Set up streaming response headers
*/
export function setupStreamingResponse(res: ServerResponse): void {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.setHeader('X-Accel-Buffering', 'no');
res.flushHeaders();
}
/* =============================================================================
* STREAM HANDLER FACTORY
* ============================================================================= */
/**
* State for tracking streaming progress
*/
interface StreamState {
messageStarted: boolean;
messageContentStarted: boolean;
reasoningStarted: boolean;
reasoningContentStarted: boolean;
activeToolCalls: Set<string>;
completedToolCalls: Set<string>;
/** Calls to a caller-executed tool — the subset the run has to terminate itself. */
clientToolCalls: Set<string>;
}
/** One streamed argument fragment, as the agents SDK forwards LangChain tool call chunks. */
interface ToolCallChunk {
id?: string;
index?: number;
args?: string;
}
/**
* Arguments as they appear on a completed model message, keyed by call id.
*
* The agents SDK only streams argument fragments when the provider sends the call in pieces; a
* call that arrives whole is dispatched with its arguments already parsed and no deltas follow.
* The completed message carries both cases, so it is the reliable source for any call whose
* arguments never arrived as fragments.
*/
function completedToolCallArguments(data: unknown): Array<{ id: string; args: string }> {
const endData = data as { output?: { tool_calls?: Array<{ id?: string; args?: unknown }> } };
const toolCalls = endData?.output?.tool_calls;
if (!Array.isArray(toolCalls)) {
return [];
}
const resolved: Array<{ id: string; args: string }> = [];
for (const tc of toolCalls) {
const id = tc.id ?? '';
if (!id || tc.args == null) {
continue;
}
resolved.push({ id, args: typeof tc.args === 'string' ? tc.args : JSON.stringify(tc.args) });
}
return resolved;
}
interface ToolCallChunkResolver {
registerStep: (stepId: string, callIds: string[]) => void;
resolve: (stepId: string, chunk: ToolCallChunk) => string | undefined;
}
/**
* Matches a streamed argument fragment to the tool call it belongs to.
*
* A chunk's `index` is provider-relative: Anthropic numbers content blocks, so thinking and text
* blocks consume values, and the numbering restarts on every step. It is therefore not an offset
* into the run's tool calls, and using it as one appends arguments to the wrong call as soon as a
* run makes more than one. Chunks are matched by id, falling back to the index recorded alongside
* that id within the same step, and finally to a step that holds exactly one call.
*/
function createToolCallChunkResolver(): ToolCallChunkResolver {
const indexToCallId = new Map<string, Map<number, string>>();
const stepCallIds = new Map<string, string[]>();
return {
registerStep: (stepId: string, callIds: string[]): void => {
stepCallIds.set(stepId, callIds);
},
resolve: (stepId: string, chunk: ToolCallChunk): string | undefined => {
let byIndex = indexToCallId.get(stepId);
if (!byIndex) {
byIndex = new Map<number, string>();
indexToCallId.set(stepId, byIndex);
}
if (chunk.id != null && chunk.id !== '') {
if (chunk.index != null) {
byIndex.set(chunk.index, chunk.id);
}
return chunk.id;
}
if (chunk.index != null) {
const mapped = byIndex.get(chunk.index);
if (mapped != null) {
return mapped;
}
}
const callIds = stepCallIds.get(stepId);
return callIds?.length === 1 ? callIds[0] : undefined;
},
};
}
/**
* Create LibreChat event handlers that emit Open Responses events
*/
export function createResponsesEventHandlers(config: StreamHandlerConfig): {
handlers: Record<string, { handle: (event: string, data: unknown) => void }>;
state: StreamState;
finalizeStream: (usage?: Usage) => void;
emitClientToolDeferral: (callId: string, output: string) => void;
} {
const state: StreamState = {
messageStarted: false,
messageContentStarted: false,
reasoningStarted: false,
reasoningContentStarted: false,
activeToolCalls: new Set(),
completedToolCalls: new Set(),
clientToolCalls: new Set(),
};
const chunkResolver = createToolCallChunkResolver();
let modelEndedClientCalls: Set<string> | undefined;
let pendingClientToolDeferrals: Map<string, string> | undefined;
/**
* Ensure message item is started
*/
const ensureMessageStarted = (): void => {
if (!state.messageStarted) {
emitMessageItemAdded(config);
state.messageStarted = true;
}
};
/**
* Ensure message content part is started
*/
const ensureMessageContentStarted = (): void => {
ensureMessageStarted();
if (!state.messageContentStarted) {
emitTextContentPartAdded(config);
state.messageContentStarted = true;
}
};
/**
* Ensure reasoning item is started
*/
const ensureReasoningStarted = (): void => {
if (!state.reasoningStarted) {
emitReasoningItemAdded(config);
state.reasoningStarted = true;
}
};
/**
* Ensure reasoning content part is started
*/
const ensureReasoningContentStarted = (): void => {
ensureReasoningStarted();
if (!state.reasoningContentStarted) {
emitReasoningContentPartAdded(config);
state.reasoningContentStarted = true;
}
};
/**
* Closes a caller-executed call that the server answered itself, and emits
* the answer as a `function_call_output` item.
*
* Without the output item the call is indistinguishable from one handed back
* for the caller to run, so a caller would execute a tool the model was told
* to re-issue — and a side-effecting tool would run twice.
*/
const deliverClientToolDeferral = (callId: string, output: string): void => {
if (state.completedToolCalls.has(callId)) {
return;
}
state.completedToolCalls.add(callId);
emitFunctionCallArgumentsDone(config, callId);
emitFunctionCallItemDone(config, callId);
emitFunctionCallOutputItem(config, callId, output);
};
const emitClientToolDeferral = (callId: string, output: string): void => {
if (!state.activeToolCalls.has(callId) || state.completedToolCalls.has(callId)) {
return;
}
// A tool-execute event can beat the model-end event that contains the
// authoritative arguments. Keep the result pending until they arrive.
if (modelEndedClientCalls?.has(callId)) {
deliverClientToolDeferral(callId, output);
return;
}
(pendingClientToolDeferrals ??= new Map()).set(callId, output);
};
/**
* Terminate the still-open calls to a caller-executed tool.
*
* `on_tool_end` terminates a call the server ran, which a caller-executed
* tool never is — the whole point is that the server hands it back. Without
* this, a streaming caller gets `output_item.added` plus argument deltas and
* then `response.completed`, with no `function_call_arguments.done` to mark
* the arguments final, and the item it is expected to act on stays
* `in_progress` inside a response that claims to be completed. A caller that
* waits for the terminating event before running the tool, as the streaming
* lifecycle tells it to, would wait forever.
*
* Deliberately limited to those calls. A server tool left open is the
* separate, pre-existing symptom of `on_tool_end` never reaching this module
* (the controller replaces the handler rather than composing with it); fixing
* that belongs at the wiring, not here, and closing such calls from
* finalization would change the event stream of every request that declares
* no client tool.
*
* Idempotent in both directions: a call already closed by `on_tool_end` is
* skipped, and marking it closed keeps `on_tool_end` from emitting a second
* pair afterwards. Arguments are complete by this point — `on_chat_model_end`
* backfills a delta for any call whose arguments the provider sent whole
* rather than streamed.
*/
const closeOpenClientToolCalls = (): void => {
for (const callId of state.clientToolCalls) {
if (state.completedToolCalls.has(callId)) {
continue;
}
state.completedToolCalls.add(callId);
emitFunctionCallArgumentsDone(config, callId);
emitFunctionCallItemDone(config, callId);
}
};
/**
* Close any open content streams
*/
const closeOpenStreams = (): void => {
// Close message content if open
if (state.messageContentStarted) {
emitOutputTextDone(config);
emitTextContentPartDone(config);
state.messageContentStarted = false;
}
// Close message item if open
if (state.messageStarted) {
emitMessageItemDone(config);
state.messageStarted = false;
}
// Close reasoning content if open
if (state.reasoningContentStarted) {
emitReasoningDone(config);
emitReasoningContentPartDone(config);
state.reasoningContentStarted = false;
}
// Close reasoning item if open
if (state.reasoningStarted) {
emitReasoningItemDone(config);
state.reasoningStarted = false;
}
};
const handlers = {
/**
* Handle text message deltas
*/
on_message_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };
const content = deltaData?.delta?.content;
if (Array.isArray(content)) {
for (const part of content) {
if (part.type === 'text' && part.text) {
ensureMessageContentStarted();
emitOutputTextDelta(config, part.text);
}
}
}
},
},
/**
* Handle reasoning deltas
*/
on_reasoning_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as {
delta?: { content?: Array<{ type: string; text?: string; think?: string }> };
};
const content = deltaData?.delta?.content;
if (Array.isArray(content)) {
for (const part of content) {
const text = part.think || part.text;
if (text) {
ensureReasoningContentStarted();
emitReasoningDelta(config, text);
}
}
}
},
},
/**
* Handle run step (tool call initiation)
*/
on_run_step: {
handle: (_event: string, data: unknown): void => {
const stepData = data as {
id?: string;
stepDetails?: { type: string; tool_calls?: Array<{ id?: string; name?: string }> };
};
const stepDetails = stepData?.stepDetails;
if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
// Close any open message/reasoning before tool calls
closeOpenStreams();
const stepCallIds: string[] = [];
for (const tc of stepDetails.tool_calls) {
const callId = tc.id ?? '';
const name = tc.name ?? '';
if (!callId) {
continue;
}
stepCallIds.push(callId);
if (!state.activeToolCalls.has(callId)) {
state.activeToolCalls.add(callId);
/* Recorded at announcement, while the name is in hand: the
terminating events are emitted much later, from finalization,
where only the call id is available. */
if (config.clientToolNames?.has(name) === true) {
state.clientToolCalls.add(callId);
}
emitFunctionCallItemAdded(config, callId, name);
}
}
chunkResolver.registerStep(stepData?.id ?? '', stepCallIds);
}
},
},
/**
* Handle run step delta (tool call argument streaming)
*/
on_run_step_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as {
id?: string;
delta?: { type: string; tool_calls?: ToolCallChunk[] };
};
const delta = deltaData?.delta;
if (delta?.type === 'tool_calls' && delta.tool_calls) {
for (const tc of delta.tool_calls) {
// Resolved before the empty-args check so an id-bearing opening chunk is recorded.
const callId = chunkResolver.resolve(deltaData?.id ?? '', tc);
const args = typeof tc.args === 'string' ? tc.args : '';
if (!args || !callId) {
continue;
}
emitFunctionCallArgumentsDelta(config, callId, args);
}
}
},
},
/**
* Handle tool end (tool execution complete)
*/
on_tool_end: {
handle: (_event: string, data: unknown): void => {
const toolData = data as { tool_call_id?: string; output?: string };
const callId = toolData?.tool_call_id;
const output = toolData?.output ?? '';
if (callId && state.activeToolCalls.has(callId) && !state.completedToolCalls.has(callId)) {
state.completedToolCalls.add(callId);
// Complete the function call item
emitFunctionCallArgumentsDone(config, callId);
emitFunctionCallItemDone(config, callId);
// Emit the function call output (internal tool result)
emitFunctionCallOutputItem(config, callId, output);
}
},
},
/**
* Handle chat model end (usage collection)
*/
on_chat_model_end: {
handle: (_event: string, data: unknown): void => {
const endData = data as {
output?: {
usage_metadata?: ModelUsageMetadata;
};
};
const usage = endData?.output?.usage_metadata;
if (usage) {
accumulateResponseUsage(config.tracker.usage, usage);
}
for (const { id, args } of completedToolCallArguments(data)) {
if (!state.activeToolCalls.has(id)) {
continue;
}
const streamed = config.tracker.accumulatedArguments.get(id) ?? '';
// An early handoff mark changes the SDK's step key. If a later
// index-only chunk lands on that new step, recover just the missing
// suffix without duplicating fragments already sent over SSE.
if (args.startsWith(streamed) && args.length > streamed.length) {
emitFunctionCallArgumentsDelta(config, id, args.slice(streamed.length));
}
if (state.clientToolCalls.has(id)) {
(modelEndedClientCalls ??= new Set()).add(id);
const deferred = pendingClientToolDeferrals?.get(id);
if (deferred !== undefined) {
pendingClientToolDeferrals?.delete(id);
deliverClientToolDeferral(id, deferred);
}
}
}
},
},
};
/**
* Finalize the stream - close open items and emit completed
*/
const finalizeStream = (usage?: Usage): void => {
closeOpenStreams();
for (const [callId, output] of pendingClientToolDeferrals ?? []) {
deliverClientToolDeferral(callId, output);
}
// A later step can announce a sibling before its arguments or deferral
// are settled. Only terminate handoffs after the run has completed.
closeOpenClientToolCalls();
emitResponseCompleted(config, usage);
writeDone(config.res);
};
return { handlers, state, finalizeStream, emitClientToolDeferral };
}
/* =============================================================================
* NON-STREAMING AGGREGATOR
* ============================================================================= */
/**
* Aggregator for non-streaming responses
*/
export interface ResponseAggregator {
textChunks: string[];
reasoningChunks: string[];
toolCalls: Map<
string,
{
id: string;
name: string;
arguments: string;
}
>;
toolOutputs: Map<string, string>;
usage: {
inputTokens: number;
outputTokens: number;
reasoningTokens: number;
cachedTokens: number;
};
addText: (text: string) => void;
addReasoning: (text: string) => void;
getText: () => string;
getReasoning: () => string;
}
/**
* Create an aggregator for non-streaming responses
*/
export function createResponseAggregator(): ResponseAggregator {
const aggregator: ResponseAggregator = {
textChunks: [],
reasoningChunks: [],
toolCalls: new Map(),
toolOutputs: new Map(),
usage: {
inputTokens: 0,
outputTokens: 0,
reasoningTokens: 0,
cachedTokens: 0,
},
addText: (text: string) => {
aggregator.textChunks.push(text);
},
addReasoning: (text: string) => {
aggregator.reasoningChunks.push(text);
},
getText: () => aggregator.textChunks.join(''),
getReasoning: () => aggregator.reasoningChunks.join(''),
};
return aggregator;
}
/**
* Build a non-streaming response from aggregator
* Includes all required fields per Open Responses spec
*/
export function buildAggregatedResponse(
context: ResponseContext,
aggregator: ResponseAggregator,
usageOverride?: Usage,
): Response {
const output: Response['output'] = [];
// Add reasoning item if present
const reasoningText = aggregator.getReasoning();
if (reasoningText) {
output.push({
type: 'reasoning',
id: `reason_${Date.now().toString(36)}`,
status: 'completed',
content: [{ type: 'reasoning_text', text: reasoningText }],
summary: [],
});
}
// Add function calls and outputs
for (const [callId, tc] of aggregator.toolCalls) {
output.push({
type: 'function_call',
id: `fc_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,
call_id: callId,
name: tc.name,
arguments: tc.arguments,
status: 'completed',
});
const toolOutput = aggregator.toolOutputs.get(callId);
if (toolOutput) {
output.push({
type: 'function_call_output',
id: `fco_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,
call_id: callId,
output: toolOutput,
status: 'completed',
});
}
}
// Add message item if there's text (or always add one if no other output)
const text = aggregator.getText();
if (text || output.length === 0) {
output.push({
type: 'message',
id: `msg_${Date.now().toString(36)}`,
role: 'assistant',
status: 'completed',
content: text ? [{ type: 'output_text', text, annotations: [], logprobs: [] }] : [],
});
}
return {
// Required fields per Open Responses spec
id: context.responseId,
object: 'response',
created_at: context.createdAt,
completed_at: Math.floor(Date.now() / 1000),
status: 'completed',
incomplete_details: null,
model: context.model,
previous_response_id: context.previousResponseId ?? null,
instructions: context.instructions ?? null,
output,
error: null,
tools: context.tools ?? [],
/** Not forwarded to the model, so reporting the request's ask would misstate the run. */
tool_choice: 'auto',
truncation: 'disabled',
parallel_tool_calls: true,
text: { format: { type: 'text' } },
temperature: 1,
top_p: 1,
presence_penalty: 0,
frequency_penalty: 0,
top_logprobs: 0,
reasoning: null,
user: null,
usage: usageOverride ?? {
input_tokens: aggregator.usage.inputTokens,
output_tokens: aggregator.usage.outputTokens,
total_tokens: aggregator.usage.inputTokens + aggregator.usage.outputTokens,
input_tokens_details: { cached_tokens: aggregator.usage.cachedTokens },
output_tokens_details: { reasoning_tokens: aggregator.usage.reasoningTokens },
},
max_output_tokens: null,
max_tool_calls: null,
store: false,
background: false,
service_tier: 'default',
metadata: {},
safety_identifier: null,
prompt_cache_key: null,
};
}
/** Build provider-normalized Responses API usage from every billed call. */
export function buildResponsesUsage(
collectedUsage: ReadonlyArray<UsageMetadata | null | undefined>,
): Usage {
const { total, primary, subagent } = aggregateCollectedUsage(collectedUsage);
return {
input_tokens: total.inputTokens,
output_tokens: total.outputTokens,
total_tokens: total.totalTokens,
input_tokens_details: { cached_tokens: total.cacheReadTokens },
output_tokens_details: { reasoning_tokens: total.reasoningTokens },
primary: {
input_tokens: primary.inputTokens,
output_tokens: primary.outputTokens,
total_tokens: primary.totalTokens,
},
subagent: {
input_tokens: subagent.inputTokens,
output_tokens: subagent.outputTokens,
total_tokens: subagent.totalTokens,
},
};
}
/**
* Create event handlers for non-streaming aggregation
*/
export function createAggregatorEventHandlers(aggregator: ResponseAggregator): Record<
string,
{
handle: (event: string, data: unknown) => void;
}
> {
const activeToolCalls = new Set<string>();
const chunkResolver = createToolCallChunkResolver();
return {
on_message_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };
const content = deltaData?.delta?.content;
if (Array.isArray(content)) {
for (const part of content) {
if (part.type === 'text' && part.text) {
aggregator.addText(part.text);
}
}
}
},
},
on_reasoning_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as {
delta?: { content?: Array<{ type: string; text?: string; think?: string }> };
};
const content = deltaData?.delta?.content;
if (Array.isArray(content)) {
for (const part of content) {
const text = part.think || part.text;
if (text) {
aggregator.addReasoning(text);
}
}
}
},
},
on_run_step: {
handle: (_event: string, data: unknown): void => {
const stepData = data as {
id?: string;
stepDetails?: {
type: string;
tool_calls?: Array<{ id?: string; name?: string; args?: unknown }>;
};
};
const stepDetails = stepData?.stepDetails;
if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
const stepCallIds: string[] = [];
for (const tc of stepDetails.tool_calls) {
const callId = tc.id ?? '';
const name = tc.name ?? '';
if (!callId) {
continue;
}
stepCallIds.push(callId);
if (!activeToolCalls.has(callId)) {
activeToolCalls.add(callId);
// A provider that does not stream its arguments delivers them here instead.
const seeded = typeof tc.args === 'string' ? tc.args : '';
aggregator.toolCalls.set(callId, { id: callId, name, arguments: seeded });
}
}
chunkResolver.registerStep(stepData?.id ?? '', stepCallIds);
}
},
},
on_run_step_delta: {
handle: (_event: string, data: unknown): void => {
const deltaData = data as {
id?: string;
delta?: { type: string; tool_calls?: ToolCallChunk[] };
};
const delta = deltaData?.delta;
if (delta?.type === 'tool_calls' && delta.tool_calls) {
for (const tc of delta.tool_calls) {
// Resolved before the empty-args check so an id-bearing opening chunk is recorded.
const callId = chunkResolver.resolve(deltaData?.id ?? '', tc);
const args = typeof tc.args === 'string' ? tc.args : '';
if (!args || !callId) {
continue;
}
const existing = aggregator.toolCalls.get(callId);
if (existing) {
existing.arguments += args;
}
}
}
},
},
on_tool_end: {
handle: (_event: string, data: unknown): void => {
const toolData = data as { tool_call_id?: string; output?: string };
const callId = toolData?.tool_call_id;
const output = toolData?.output ?? '';
if (callId) {
aggregator.toolOutputs.set(callId, output);
}
},
},
on_chat_model_end: {
handle: (_event: string, data: unknown): void => {
const endData = data as {
output?: {
usage_metadata?: ModelUsageMetadata;
};
};
const usage = endData?.output?.usage_metadata;
if (usage) {
accumulateResponseUsage(aggregator.usage, usage);
}
for (const { id, args } of completedToolCallArguments(data)) {
const existing = aggregator.toolCalls.get(id);
if (existing && existing.arguments === '') {
existing.arguments = args;
}
}
},
},
};
}