TanStack AI version#
@tanstack/ai 1.2.0, @tanstack/ai-openai 1.1.1, @tanstack/openai-base 1.0.2
Framework/Library version#
Server-side only: Node.js v24.19.0, Fastify 5.12.5
Describe the bug and the steps to reproduce it#
When using openaiCompatibleText from @tanstack/ai-openai/compatible, the runId passed to
chat() is ignored. Each model call in the agent loop gets a newly generated runId, so in any
run with a tool call:
- the
runId passed to chat() (e.g. via chatParamsFromRequest, where it is required) never
appears in the stream
RUN_STARTED is emitted once with the first call's generated id
- each loop iteration emits its own
RUN_FINISHED with a different generated id, so the final
RUN_FINISHED refers to a run that was never started
For AG-UI clients this breaks run tracking: RUN_STARTED / RUN_FINISHED no longer bracket one
run (https://docs.ag-ui.com/concepts/events).
Steps to reproduce#
- Call
chat() with openaiCompatibleText(...), one server tool, threadId, and
runId: 'run-from-client'.
- The model calls the tool on the first iteration and answers on the second.
- Log
runId on all RUN_* events.
Actual#
RUN_STARTED runId = openai-compatible-1794220019151-jrsd5qd6gri
RUN_FINISHED runId = openai-compatible-1794220019151-jrsd5qd6gri
RUN_FINISHED runId = openai-compatible-1794220019173-waqi8ytzkqk <- never started
Expected#
RUN_STARTED runId = run-from-client
RUN_FINISHED runId = run-from-client
RUN_FINISHED runId = run-from-client
This is how the OpenAI Responses adapter and @tanstack/ai-anthropic already behave.
Cause#
openaiCompatibleText extends OpenAIBaseChatCompletionsTextAdapter from @tanstack/openai-base,
whose chatStream() never reads options.runId:
const aguiState = {
runId: generateId(this.name),
threadId: options.threadId,
messageId: generateId(this.name),
hasEmittedRunStarted: false
};
structuredOutputStream() in the same file has the same pattern. For comparison:
openai-base Responses adapter: runId: options.runId ?? generateId(this.name)
@tanstack/ai-anthropic 1.1.1: const runId = options.runId ?? genId();
Suggested fix#
- runId: generateId(this.name),
+ runId: options.runId ?? generateId(this.name),
in both chatStream() and structuredOutputStream() of chat-completions-text.ts. This should also
fix any other adapter built on the Chat Completions base.
Your Minimal, Reproducible Example - (Sandbox Highly Recommended)#
https://codesandbox.io/p/devbox/inconsistent-runid-for-openaicompatibletext-r99qv4
Screenshots or Videos (Optional)#
No response
Do you intend to try to help solve this bug with your own PR?#
Yes, I think I know how to fix it and will discuss it in the comments of this issue
Terms & Code of Conduct#