Open History to see the last commit
1import { createFileRoute } from '@tanstack/react-router'
2import {
3 chat,
4 chatParamsFromRequestBody,
5 maxIterations,
6 toServerSentEventsResponse,
7 toolDefinition,
8} from '@tanstack/ai'
9import type { ChatMiddleware, StreamChunk } from '@tanstack/ai'
10import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
11import { guitarRecommendationSchema } from '@/lib/schemas'
12import {
13 getPhaseCapture,
14 recordOnFinish,
15 recordPhase,
16 recordYieldedChunk,
17 resetPhaseCapture,
18} from '@/lib/phase-capture'
19import { SpanStatusCode } from '@opentelemetry/api'
20import type {
21 AttributeValue,
22 Attributes,
23 Context,
24 Histogram,
25 Meter,
26 MetricOptions,
27 Span,
28 SpanContext,
29 SpanStatus,
30 Tracer,
31} from '@opentelemetry/api'
32import { z } from 'zod'
33import { createTextAdapter } from '@/lib/providers'
34import {
35 getOtelCapture,
36 recordOtelEvent,
37 recordOtelException,
38 recordOtelHistogram,
39 recordOtelSpan,
40 resetOtelCapture,
41} from '@/lib/otel-capture'
42
43// The otel capture endpoint is only useful during E2E runs. Gate both the
44// POST 'otel' mode and the GET capture fetch behind this flag so the route
45// cannot be used as an oracle in a production-like build.
46const OTEL_TEST_ENABLED =
47 process.env.E2E_TEST === '1' || process.env.NODE_ENV !== 'production'
48
49const weatherTool = toolDefinition({
50 name: 'get_weather',
51 description: 'Get weather',
52 inputSchema: z.object({ city: z.string() }),
53}).server(async (args) =>
54 JSON.stringify({ city: args.city, temperature: 72, condition: 'sunny' }),
55)
56
57const chunkTransformMiddleware: ChatMiddleware = {
58 name: 'chunk-transform',
59 onChunk(_ctx, chunk) {
60 if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {
61 return {
62 ...chunk,
63 delta: '[MW] ' + chunk.delta,
64 content: '[MW] ' + (chunk.content || ''),
65 }
66 }
67 return chunk
68 },
69}
70
71const toolSkipMiddleware: ChatMiddleware = {
72 name: 'tool-skip',
73 onBeforeToolCall(_ctx, hookCtx) {
74 if (hookCtx.toolName === 'get_weather') {
75 return {
76 type: 'skip' as const,
77 result: JSON.stringify({ skipped: true, reason: 'middleware' }),
78 }
79 }
80 return undefined
81 },
82}
83
84/**
85 * Per-testId recorder used by `phase-recorder` mode.
86 *
87 * Captures every `ctx.phase` observed during `onChunk` and counts `onFinish`
88 * invocations. The capture is stored in a module-global keyed by `testId` so
89 * the page can fetch it via `GET /api/middleware-test?testId=...&kind=phase`
90 * after the run finishes.
91 *
92 * Why a factory: middleware closes over `captureId` so we don't have to thread
93 * a per-request shim through global state.
94 */
95function createPhaseRecorderMiddleware(captureId: string): ChatMiddleware {
96 return {
97 name: 'phase-recorder',
98 onChunk(ctx, chunk) {
99 recordPhase(captureId, ctx.phase)
100 return chunk
101 },
102 onFinish() {
103 recordOnFinish(captureId)
104 },
105 }
106}
107
108/**
109 * Wraps a chat stream so every chunk that leaves `chat()` (post-middleware)
110 * is recorded into the per-testId phase capture as a yielded chunk. Used by
111 * `phase-recorder` mode to let the spec assert what the consumer actually
112 * sees — distinct from what `onChunk` observes inside the middleware chain.
113 */
114async function* teeForPhaseCapture(
115 source: AsyncIterable<StreamChunk>,
116 captureId: string,
117): AsyncIterable<StreamChunk> {
118 for await (const chunk of source) {
119 recordYieldedChunk(captureId, { type: chunk.type })
120 yield chunk
121 }
122}
123
124// Minimal in-memory tracer/meter. Captures into a per-testId bucket so that
125// the Playwright spec can fetch the recorded state via GET after the stream
126// finishes. Not exported — only used to build otelMiddleware for the test.
127function createCaptureTracer(captureId: string): Tracer {
128 let spanSeq = 0
129 const tracer: Tracer = {
130 startSpan(name, options = {}, _ctx?: Context): Span {
131 const id = `span-${spanSeq++}`
132 const attrs: Record<string, AttributeValue> = {}
133 for (const [k, v] of Object.entries(options.attributes ?? {})) {
134 if (v !== undefined) attrs[k] = v as AttributeValue
135 }
136 recordOtelSpan(captureId, {
137 id,
138 name,
139 kind: options.kind,
140 attributes: attrs,
141 status: SpanStatusCode.UNSET,
142 events: [],
143 exceptions: [],
144 ended: false,
145 })
146 const status: SpanStatus = { code: SpanStatusCode.UNSET }
147 let ended = false
148 const span: Span = {
149 spanContext(): SpanContext {
150 return { traceId: 'capture-trace', spanId: id, traceFlags: 1 }
151 },
152 setAttribute(key, value) {
153 attrs[key] = value as AttributeValue
154 recordOtelSpan(captureId, { id, patch: { attributes: { ...attrs } } })
155 return span
156 },
157 setAttributes(next) {
158 for (const [k, v] of Object.entries(next)) {
159 attrs[k] = v as AttributeValue
160 }
161 recordOtelSpan(captureId, { id, patch: { attributes: { ...attrs } } })
162 return span
163 },
164 addEvent(eventName, eventAttrs) {
165 recordOtelEvent(captureId, id, {
166 name: eventName,
167 attributes: eventAttrs as Attributes | undefined,
168 })
169 return span
170 },
171 addLink() {
172 return span
173 },
174 addLinks() {
175 return span
176 },
177 setStatus(next) {
178 status.code = next.code
179 status.message = next.message
180 recordOtelSpan(captureId, {
181 id,
182 patch: { status: next.code, statusMessage: next.message },
183 })
184 return span
185 },
186 updateName(next) {
187 recordOtelSpan(captureId, { id, patch: { name: next } })
188 return span
189 },
190 end() {
191 ended = true
192 recordOtelSpan(captureId, { id, patch: { ended: true } })
193 },
194 isRecording() {
195 return !ended
196 },
197 recordException(exception, exceptionAttrs) {
198 recordOtelException(captureId, id, {
199 exception: String(
200 (exception as { message?: string } | undefined)?.message ??
201 exception,
202 ),
203 attributes: exceptionAttrs as Attributes | undefined,
204 })
205 },
206 }
207 return span
208 },
209 // Minimal implementation — our middleware never calls startActiveSpan.
210 // eslint-disable-next-line @typescript-eslint/no-explicit-any
211 startActiveSpan(...args: Array<any>) {
212 const fn = args[args.length - 1] as (span: Span) => unknown
213 const name = args[0] as string
214 const span = tracer.startSpan(name, {})
215 try {
216 return fn(span)
217 } finally {
218 span.end()
219 }
220 },
221 }
222 return tracer
223}
224
225function createCaptureMeter(captureId: string): Meter {
226 const histogram = (name: string, options?: MetricOptions): Histogram => ({
227 record(value: number, attributes?: Attributes) {
228 recordOtelHistogram(captureId, {
229 name,
230 value,
231 attributes,
232 unit: options?.unit,
233 })
234 },
235 })
236 return {
237 createHistogram: histogram,
238 // eslint-disable-next-line @typescript-eslint/no-explicit-any
239 } as any as Meter
240}
241
242export const Route = createFileRoute('/api/middleware-test')({
243 server: {
244 handlers: {
245 POST: async ({ request }) => {
246 if (request.signal?.aborted) return new Response(null, { status: 499 })
247 const abortController = new AbortController()
248
249 let params
250 try {
251 params = await chatParamsFromRequestBody(await request.json())
252 } catch (error) {
253 return new Response(
254 error instanceof Error ? error.message : 'Bad request',
255 { status: 400 },
256 )
257 }
258
259 const fp = params.forwardedProps as Record<string, unknown>
260 const scenario =
261 typeof fp.scenario === 'string' ? fp.scenario : 'basic-text'
262 const middlewareMode =
263 typeof fp.middlewareMode === 'string' ? fp.middlewareMode : 'none'
264 const testId: string | undefined =
265 typeof fp.testId === 'string' ? fp.testId : undefined
266 const aimockPort: number | undefined =
267 fp.aimockPort != null ? Number(fp.aimockPort) : undefined
268
269 try {
270 const adapterOptions = createTextAdapter(
271 'openai',
272 undefined,
273 aimockPort,
274 testId,
275 )
276
277 const middleware: Array<ChatMiddleware> = []
278
279 if (middlewareMode === 'chunk-transform')
280 middleware.push(chunkTransformMiddleware)
281 if (middlewareMode === 'tool-skip')
282 middleware.push(toolSkipMiddleware)
283 if (middlewareMode === 'phase-recorder') {
284 if (!testId) {
285 return new Response(
286 JSON.stringify({
287 error: 'phase-recorder mode requires testId',
288 }),
289 {
290 status: 400,
291 headers: { 'Content-Type': 'application/json' },
292 },
293 )
294 }
295 resetPhaseCapture(testId)
296 middleware.push(createPhaseRecorderMiddleware(testId))
297 }
298 if (middlewareMode === 'otel') {
299 if (!OTEL_TEST_ENABLED) {
300 return new Response(null, { status: 404 })
301 }
302 if (!testId) {
303 return new Response(
304 JSON.stringify({ error: 'otel mode requires testId' }),
305 {
306 status: 400,
307 headers: { 'Content-Type': 'application/json' },
308 },
309 )
310 }
311 resetOtelCapture(testId)
312 middleware.push(
313 otelMiddleware({
314 tracer: createCaptureTracer(testId),
315 meter: createCaptureMeter(testId),
316 captureContent: true,
317 }),
318 )
319 }
320
321 const tools = scenario === 'with-tool' ? [weatherTool] : []
322
323 // The two `structured-output*` scenarios both bind the same
324 // guitar schema; they differ only in what the spec asserts (phases
325 // observed vs RUN_STARTED/RUN_FINISHED uniqueness). A single
326 // outputSchema branch keeps the route narrow.
327 const isStructured =
328 scenario === 'structured-output' ||
329 scenario === 'structured-output-stream'
330
331 const rawStream = isStructured
332 ? chat({
333 ...adapterOptions,
334 messages: params.messages,
335 middleware,
336 threadId: params.threadId,
337 runId: params.runId,
338 outputSchema: guitarRecommendationSchema,
339 stream: true,
340 abortController,
341 })
342 : chat({
343 ...adapterOptions,
344 messages: params.messages,
345 tools,
346 middleware,
347 threadId: params.threadId,
348 runId: params.runId,
349 agentLoopStrategy: maxIterations(10),
350 abortController,
351 })
352
353 // Tee the post-middleware stream when `phase-recorder` is active
354 // so the spec can assert on what the consumer ultimately sees
355 // (e.g. exactly one RUN_STARTED/RUN_FINISHED pair).
356 const stream =
357 middlewareMode === 'phase-recorder' && testId
358 ? teeForPhaseCapture(rawStream, testId)
359 : rawStream
360
361 return toServerSentEventsResponse(stream, { abortController })
362 } catch (error: any) {
363 console.error('[api.middleware-test] Error:', error.message)
364 if (error.name === 'AbortError' || abortController.signal.aborted) {
365 return new Response(null, { status: 499 })
366 }
367 return new Response(JSON.stringify({ error: error.message }), {
368 status: 500,
369 headers: { 'Content-Type': 'application/json' },
370 })
371 }
372 },
373 GET: async ({ request }) => {
374 const url = new URL(request.url)
375 const testId = url.searchParams.get('testId')
376 const kind = url.searchParams.get('kind')
377
378 // Phase capture is independent of OTEL — keep it available without
379 // requiring the OTEL_TEST_ENABLED gate so that the structured-output
380 // middleware spec works under any harness build configuration.
381 if (kind === 'phase') {
382 if (!testId) {
383 return new Response(
384 JSON.stringify({ error: 'testId query param required' }),
385 {
386 status: 400,
387 headers: { 'Content-Type': 'application/json' },
388 },
389 )
390 }
391 return new Response(JSON.stringify(getPhaseCapture(testId)), {
392 headers: { 'Content-Type': 'application/json' },
393 })
394 }
395
396 // OTEL capture remains gated — the GET cannot act as an oracle in a
397 // production-like build.
398 if (!OTEL_TEST_ENABLED) {
399 return new Response(null, { status: 404 })
400 }
401 if (!testId) {
402 return new Response(
403 JSON.stringify({ error: 'testId query param required' }),
404 {
405 status: 400,
406 headers: { 'Content-Type': 'application/json' },
407 },
408 )
409 }
410 return new Response(JSON.stringify(getOtelCapture(testId)), {
411 headers: { 'Content-Type': 'application/json' },
412 })
413 },
414 },
415 },
416})