refactor(cookbooks): run tools with runTools() and stream raw chunks

[vishxrad]

Stacked on #1258. The cookbooks run their tools with the OpenAI SDK's runTools() instead of the hand-written tool loop, and stream raw completion chunks to Agent Interface, following the self-hosted template (route, page).

Summary

• Tool loop removed. Each cookbook's src/lib/tool-loop.ts is gone (about 150 lines each). The chat route calls gateway.chat.completions.runTools() with the tool's existing JSON schema plus its executor, typed with the SDK's own runnable-tool types (no casts).
• Raw chunks to the browser. The route forwards the runner's completion chunks as server-sent events, the format Gateway streams. The page reads them with openAIAdapter() and openAIMessageFormat, as in the template, so the route no longer builds AG-UI events.
• Same round caps. maxChatCompletions is 3, 4 and 3, matching the old maxRounds.
• Same first-round errors. The route waits for the first completion before responding (runner.emitted("connect") raced with runner.done()), so a rejected key or rate limit still returns Gateway's HTTP status.
• Docs. The step 4 and step 5 code samples, READMEs, file tables, and tool module comments describe runTools() and openAIAdapter().

What changes for readers

• No tool results in Behind the scenes. Chat Completions has no chunk for a tool result, and openAIAdapter() reads only text and tool-call chunks. Behind the scenes shows each call with its arguments, but the call stays at "Calling …" with no result. The docs and Verify steps say so.
• Tool arguments stream in, as they do from Gateway.
• Parallel tools. Tools the model calls in one completion run in parallel, and results go back to the model in call order.
• Tool errors. runTools() ends the run when a tool throws. Each route wraps its executor so the error goes back to the model as the tool result, as the old loop did.
• Later errors are generic. An error after the first completion ends the stream, and Agent Interface shows "Something went wrong: Failed to fetch" instead of Gateway's message.
• No forced final answer. The old loop set tool_choice: "none" on its last round. maxChatCompletions just stops, so a run that hits the cap on a tool call ends without an answer.

Docs correction

The pages said "a rejected key, rate limit, or unknown model returns as an HTTP error". An unknown model doesn't: Gateway accepts it with 200 and fails inside the stream, with the old loop too. The pages now say "a rejected key or rate limit".

Test plan

• tsc --noEmit in all three cookbooks
• npm run verify in all three cookbooks, on the first commit (before switching to raw chunks)
• npm run verify after switching to raw chunks
• Analytics, raw chunks, in the browser: the fastest-laps starter streams the pre-tool text, the query_lap_times call with its arguments, and the table. The call has no result.
• Document comparison, raw chunks, in the browser: two search_documents calls in one round
• Analytics, raw chunks, invalid OPENUI_MODEL: Agent Interface shows "Something went wrong: Failed to fetch"
• Invalid THESYS_API_KEY: /api/chat returns HTTP 401 with Gateway's message (tested on the first commit; this path is unchanged)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openui-docs	Ready	Preview	Sep 29, 2026 10:03am UTC