Open History to see the last commit
1import { aiEventClient } from './index.js'
2
3// Local mirrors of @tanstack/ai middleware types — do not import from `@tanstack/ai`
4// here: during `@tanstack/ai`'s own build that resolves to `dist/*.d.ts` while the
5// engine compiles from `src/`, producing incompatible duplicate types.
6
7interface DevtoolsModelMessage {
8 role: string
9 content: unknown
10 toolCalls?: unknown
11}
12
13type DevtoolsSystemPrompt = string | { content: string; metadata?: unknown }
14
15interface DevtoolsUsage {
16 promptTokens: number
17 completionTokens: number
18 totalTokens: number
19}
20
21interface DevtoolsTextMessageContentChunk {
22 type: 'TEXT_MESSAGE_CONTENT'
23 content?: string
24 delta: string
25}
26interface DevtoolsToolCallStartChunk {
27 type: 'TOOL_CALL_START'
28 toolCallId: string
29 toolCallName: string
30 index?: number
31}
32interface DevtoolsToolCallArgsChunk {
33 type: 'TOOL_CALL_ARGS'
34 toolCallId: string
35 delta: string
36}
37interface DevtoolsToolCallEndChunk {
38 type: 'TOOL_CALL_END'
39 toolCallId: string
40 result?: string
41}
42interface DevtoolsToolCallResultChunk {
43 type: 'TOOL_CALL_RESULT'
44 toolCallId: string
45 content?: string
46}
47interface DevtoolsRunFinishedChunk {
48 type: 'RUN_FINISHED'
49 finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
50 usage?: DevtoolsUsage
51}
52interface DevtoolsRunErrorChunk {
53 type: 'RUN_ERROR'
54 message?: string
55 code?: string
56 error?: { message?: string; code?: string }
57}
58interface DevtoolsStepFinishedChunk {
59 type: 'STEP_FINISHED'
60 content?: string
61 delta?: string
62}
63type DevtoolsKnownChunk =
64 | DevtoolsTextMessageContentChunk
65 | DevtoolsToolCallStartChunk
66 | DevtoolsToolCallArgsChunk
67 | DevtoolsToolCallEndChunk
68 | DevtoolsToolCallResultChunk
69 | DevtoolsRunFinishedChunk
70 | DevtoolsRunErrorChunk
71 | DevtoolsStepFinishedChunk
72
73// The engine emits more chunk types than this middleware acts on
74// (TEXT_MESSAGE_START, MESSAGES_SNAPSHOT, REASONING_*, CUSTOM, etc.); the
75// onChunk signature accepts the open shape, and isKnownChunk narrows to the
76// closed discriminated union before the switch.
77type DevtoolsStreamChunk = DevtoolsKnownChunk | { type: string }
78
79const KNOWN_CHUNK_TYPES: ReadonlySet<DevtoolsKnownChunk['type']> = new Set([
80 'TEXT_MESSAGE_CONTENT',
81 'TOOL_CALL_START',
82 'TOOL_CALL_ARGS',
83 'TOOL_CALL_END',
84 'TOOL_CALL_RESULT',
85 'RUN_FINISHED',
86 'RUN_ERROR',
87 'STEP_FINISHED',
88])
89
90function isKnownChunk(chunk: DevtoolsStreamChunk): chunk is DevtoolsKnownChunk {
91 return (KNOWN_CHUNK_TYPES as ReadonlySet<string>).has(chunk.type)
92}
93
94interface DevtoolsMiddlewareContext {
95 requestId: string
96 streamId: string
97 runId: string
98 threadId: string
99 conversationId?: string
100 provider: string
101 model: string
102 source: 'client' | 'server'
103 systemPrompts: ReadonlyArray<DevtoolsSystemPrompt>
104 toolNames?: Array<string>
105 options?: Record<string, unknown>
106 modelOptions?: Record<string, unknown>
107 messageCount: number
108 hasTools: boolean
109 streaming: boolean
110 messages: ReadonlyArray<DevtoolsModelMessage>
111 createId: (prefix: string) => string
112}
113
114interface DevtoolsIterationInfo {
115 iteration: number
116 messageId: string
117}
118
119interface DevtoolsToolPhaseCompleteInfo {
120 toolCalls: Array<unknown>
121 needsApproval: Array<{
122 toolCallId: string
123 toolName: string
124 input: unknown
125 approvalId: string
126 }>
127 needsClientExecution: Array<{
128 toolCallId: string
129 toolName: string
130 input: unknown
131 }>
132 results: Array<{
133 toolCallId: string
134 toolName: string
135 result: unknown
136 duration?: number
137 }>
138}
139
140interface DevtoolsFinishInfo {
141 content: string
142 finishReason: string | null
143 duration: number
144 usage?: {
145 promptTokens: number
146 completionTokens: number
147 totalTokens: number
148 }
149}
150
151// Observation-only middleware returned by {@link devtoolsMiddleware}.
152// Structurally compatible with `ChatMiddleware` from `@tanstack/ai`.
153export interface DevtoolsChatMiddleware {
154 name?: string
155 onStart?: (ctx: DevtoolsMiddlewareContext) => void | Promise<void>
156 onIteration?: (
157 ctx: DevtoolsMiddlewareContext,
158 info: DevtoolsIterationInfo,
159 ) => void | Promise<void>
160 onChunk?: (
161 ctx: DevtoolsMiddlewareContext,
162 chunk: DevtoolsStreamChunk,
163 ) => void | Promise<void>
164 onToolPhaseComplete?: (
165 ctx: DevtoolsMiddlewareContext,
166 info: DevtoolsToolPhaseCompleteInfo,
167 ) => void | Promise<void>
168 onFinish?: (
169 ctx: DevtoolsMiddlewareContext,
170 info: DevtoolsFinishInfo,
171 ) => void | Promise<void>
172}
173
174// Wrap an emit so a misbehaving subscriber cannot bubble into the host chat
175// engine. Instrumentation must never break the host app.
176const safeEmit: typeof aiEventClient.emit = (...args) => {
177 try {
178 aiEventClient.emit(...args)
179 } catch (error) {
180 console.error(
181 `[ai-devtools] subscriber threw while handling "${String(args[0])}" event`,
182 error,
183 )
184 }
185}
186
187function buildEventContext(ctx: DevtoolsMiddlewareContext) {
188 return {
189 requestId: ctx.requestId,
190 streamId: ctx.streamId,
191 runId: ctx.runId,
192 threadId: ctx.threadId,
193 provider: ctx.provider,
194 model: ctx.model,
195 clientId: ctx.conversationId,
196 source: ctx.source,
197 // Devtools wire payload is plain strings; per-prompt metadata is
198 // irrelevant for observation and would require devtools-UI changes to
199 // render. Project metadata away here so the wire shape is unchanged.
200 systemPrompts:
201 ctx.systemPrompts.length > 0
202 ? ctx.systemPrompts.map((p) => (typeof p === 'string' ? p : p.content))
203 : undefined,
204 toolNames: ctx.toolNames,
205 options: ctx.options,
206 modelOptions: ctx.modelOptions,
207 messageCount: ctx.messageCount,
208 hasTools: ctx.hasTools,
209 streaming: ctx.streaming,
210 }
211}
212
213/**
214 * Extract text content from a ModelMessage content field.
215 */
216function getContentString(content: DevtoolsModelMessage['content']): string {
217 if (typeof content === 'string') return content
218 if (!Array.isArray(content)) return ''
219 return (
220 content
221 .map((part) =>
222 part &&
223 typeof part === 'object' &&
224 (part as { type?: string }).type === 'text'
225 ? String((part as { content?: unknown }).content ?? '')
226 : '',
227 )
228 .join('') || ''
229 )
230}
231
232/**
233 * Internal devtools middleware that emits all DevTools events.
234 * Auto-injected as the FIRST middleware in the TextEngine.
235 *
236 * All hooks are observation-only — `onChunk` returns void to pass through
237 * without transforming chunks.
238 */
239export function devtoolsMiddleware(): DevtoolsChatMiddleware {
240 // Local mutable state — tracked here because the devtools middleware
241 // runs first, before the engine updates ctx.currentMessageId / ctx.accumulatedContent
242 let localMessageId: string | null = null
243 let localAccumulatedContent = ''
244 let currentIteration = -1
245 let iterationStartTime = 0
246 const activeToolCalls = new Map<string, { toolName: string; index: number }>()
247
248 return {
249 name: 'devtools',
250
251 onStart(ctx) {
252 // Emit text:request:started
253 safeEmit('text:request:started', {
254 ...buildEventContext(ctx),
255 timestamp: Date.now(),
256 })
257
258 // Emit text:message:created for initial messages
259 const messages = ctx.messages
260 const messagesToEmit = ctx.conversationId
261 ? messages.slice(-1).filter((m) => m.role === 'user')
262 : messages
263
264 messagesToEmit.forEach((message, index) => {
265 const messageIndex = ctx.conversationId ? messages.length - 1 : index
266 const messageId = ctx.createId('msg')
267 const base = buildEventContext(ctx)
268 const content = getContentString(message.content)
269
270 safeEmit('text:message:created', {
271 ...base,
272 messageId,
273 role: message.role as 'user' | 'assistant' | 'system' | 'tool',
274 content,
275 toolCalls: message.toolCalls as never,
276 messageIndex,
277 timestamp: Date.now(),
278 })
279
280 if (message.role === 'user') {
281 safeEmit('text:message:user', {
282 ...base,
283 messageId,
284 role: 'user' as const,
285 content,
286 messageIndex,
287 timestamp: Date.now(),
288 })
289 }
290 })
291 },
292
293 onIteration(ctx: DevtoolsMiddlewareContext, info: DevtoolsIterationInfo) {
294 const now = Date.now()
295
296 // Emit completed for previous iteration (it ended with tool_calls if we got here)
297 if (currentIteration >= 0) {
298 safeEmit('text:iteration:completed', {
299 ...buildEventContext(ctx),
300 iteration: currentIteration,
301 messageId: localMessageId || undefined,
302 duration: now - iterationStartTime,
303 finishReason: 'tool_calls',
304 timestamp: now,
305 })
306 }
307
308 // Track new iteration
309 currentIteration = info.iteration
310 iterationStartTime = now
311 localMessageId = info.messageId
312 localAccumulatedContent = ''
313
314 // Emit iteration:started with config snapshot
315 safeEmit('text:iteration:started', {
316 ...buildEventContext(ctx),
317 iteration: info.iteration,
318 messageId: info.messageId,
319 timestamp: now,
320 })
321
322 // Emit assistant message placeholder
323 safeEmit('text:message:created', {
324 ...buildEventContext(ctx),
325 messageId: info.messageId,
326 role: 'assistant' as const,
327 content: '',
328 timestamp: now,
329 })
330 },
331
332 onChunk(ctx, rawChunk) {
333 if (!isKnownChunk(rawChunk)) return
334 const chunk = rawChunk
335 const base = buildEventContext(ctx)
336
337 switch (chunk.type) {
338 case 'TEXT_MESSAGE_CONTENT': {
339 if (chunk.content) {
340 localAccumulatedContent = chunk.content
341 } else {
342 localAccumulatedContent += chunk.delta
343 }
344 safeEmit('text:chunk:content', {
345 ...base,
346 messageId: localMessageId || undefined,
347 content: localAccumulatedContent,
348 delta: chunk.delta,
349 timestamp: Date.now(),
350 })
351 break
352 }
353 case 'TOOL_CALL_START': {
354 const toolIndex = chunk.index ?? 0
355 const toolName = chunk.toolCallName
356 activeToolCalls.set(chunk.toolCallId, {
357 toolName,
358 index: toolIndex,
359 })
360 safeEmit('text:chunk:tool-call', {
361 ...base,
362 messageId: localMessageId || undefined,
363 toolCallId: chunk.toolCallId,
364 toolName,
365 index: toolIndex,
366 arguments: '',
367 timestamp: Date.now(),
368 })
369 break
370 }
371 case 'TOOL_CALL_ARGS': {
372 const active = activeToolCalls.get(chunk.toolCallId)
373 safeEmit('text:chunk:tool-call', {
374 ...base,
375 messageId: localMessageId || undefined,
376 toolCallId: chunk.toolCallId,
377 toolName: active?.toolName ?? '',
378 index: active?.index ?? 0,
379 arguments: chunk.delta,
380 timestamp: Date.now(),
381 })
382 break
383 }
384 case 'TOOL_CALL_END': {
385 activeToolCalls.delete(chunk.toolCallId)
386 safeEmit('text:chunk:tool-result', {
387 ...base,
388 messageId: localMessageId || undefined,
389 toolCallId: chunk.toolCallId,
390 result: chunk.result || '',
391 timestamp: Date.now(),
392 })
393 break
394 }
395 case 'TOOL_CALL_RESULT': {
396 // Server-executed tool results arrive on the spec-compliant
397 // TOOL_CALL_RESULT event (the adapter's TOOL_CALL_END carries only
398 // the parsed input). Surface them to devtools from here so results
399 // still show up now that the post-execution END is no longer
400 // re-emitted (#519).
401 safeEmit('text:chunk:tool-result', {
402 ...base,
403 messageId: localMessageId || undefined,
404 toolCallId: chunk.toolCallId,
405 result: chunk.content || '',
406 timestamp: Date.now(),
407 })
408 break
409 }
410 case 'RUN_FINISHED': {
411 safeEmit('text:chunk:done', {
412 ...base,
413 messageId: localMessageId || undefined,
414 finishReason: chunk.finishReason ?? null,
415 usage: chunk.usage,
416 timestamp: Date.now(),
417 })
418 if (chunk.usage) {
419 safeEmit('text:usage', {
420 ...base,
421 messageId: localMessageId || undefined,
422 usage: chunk.usage,
423 timestamp: Date.now(),
424 })
425 }
426 break
427 }
428 case 'RUN_ERROR': {
429 const errorMessage =
430 chunk.message ??
431 chunk.error?.message ??
432 `[ai-devtools] RUN_ERROR chunk had no message; raw chunk: ${JSON.stringify(chunk)}`
433 safeEmit('text:chunk:error', {
434 ...base,
435 messageId: localMessageId || undefined,
436 error: errorMessage,
437 timestamp: Date.now(),
438 })
439 break
440 }
441 case 'STEP_FINISHED': {
442 if (chunk.content || chunk.delta) {
443 safeEmit('text:chunk:thinking', {
444 ...base,
445 messageId: localMessageId || undefined,
446 content: chunk.content || '',
447 delta: chunk.delta,
448 timestamp: Date.now(),
449 })
450 }
451 break
452 }
453 }
454
455 // Return void — observation only, pass through unchanged
456 },
457
458 onToolPhaseComplete(ctx, info: DevtoolsToolPhaseCompleteInfo) {
459 const base = buildEventContext(ctx)
460
461 // Emit text:message:created for assistant message with tool calls
462 if (info.toolCalls.length > 0) {
463 safeEmit('text:message:created', {
464 ...base,
465 messageId: localMessageId ?? ctx.createId('msg'),
466 role: 'assistant' as const,
467 content: localAccumulatedContent || '',
468 toolCalls: info.toolCalls as never,
469 timestamp: Date.now(),
470 })
471 }
472
473 // Emit tools:approval:requested for each pending approval
474 for (const approval of info.needsApproval) {
475 safeEmit('tools:approval:requested', {
476 ...base,
477 messageId: localMessageId || undefined,
478 toolCallId: approval.toolCallId,
479 toolName: approval.toolName,
480 input: approval.input,
481 approvalId: approval.approvalId,
482 timestamp: Date.now(),
483 })
484 }
485
486 // Emit tools:input:available for each client tool
487 for (const clientTool of info.needsClientExecution) {
488 safeEmit('tools:input:available', {
489 ...base,
490 messageId: localMessageId || undefined,
491 toolCallId: clientTool.toolCallId,
492 toolName: clientTool.toolName,
493 input: clientTool.input,
494 timestamp: Date.now(),
495 })
496 }
497
498 // Emit tools:call:completed and text:message:created (tool role) for each result
499 for (const result of info.results) {
500 safeEmit('tools:call:completed', {
501 ...base,
502 messageId: localMessageId || undefined,
503 toolCallId: result.toolCallId,
504 toolName: result.toolName,
505 result: result.result,
506 duration: result.duration ?? 0,
507 timestamp: Date.now(),
508 })
509
510 const content = JSON.stringify(result.result)
511 safeEmit('text:message:created', {
512 ...base,
513 messageId: ctx.createId('msg'),
514 role: 'tool' as const,
515 content,
516 timestamp: Date.now(),
517 })
518 }
519 },
520
521 onFinish(ctx, info) {
522 const now = Date.now()
523
524 // Emit completed for the final iteration
525 if (currentIteration >= 0) {
526 safeEmit('text:iteration:completed', {
527 ...buildEventContext(ctx),
528 iteration: currentIteration,
529 messageId: localMessageId || undefined,
530 duration: now - iterationStartTime,
531 finishReason: info.finishReason || undefined,
532 usage: info.usage,
533 timestamp: now,
534 })
535 }
536
537 safeEmit('text:request:completed', {
538 ...buildEventContext(ctx),
539 content: info.content,
540 messageId: localMessageId || undefined,
541 finishReason: info.finishReason || undefined,
542 usage: info.usage,
543 duration: info.duration,
544 timestamp: now,
545 })
546 },
547 }
548}