feat: improve the event system to emit more data and conventionalize …

README.md

@@ -45,6 +45,7 @@ A powerful, type-safe AI SDK for building AI-powered applications.
 - Headless chat state management with adapters (SSE, HTTP stream, custom)
 - Isomorphic type-safe tools with server/client execution
 - **Enhanced integration with TanStack Start** - Share implementations between AI tools and server functions
+- **Observability events** - Structured, typed events for text, tools, image, speech, transcription, and video ([docs](./docs/guides/observability.md))
 
 ### <a href="https://tanstack.com/ai">Read the docs →</b></a>
 

docs/guides/observability.md

@@ -18,6 +18,22 @@ the `{ withEventTarget: true }` option.
 This will not only emit to the event bus (which is not present in production), but to the current eventTarget that
 you will be able to listen to. 
 
+## Event naming scheme
+
+Events follow the format `<system-part>:<what-it-does>`.
+
+- Text: `text:request:started`, `text:message:created`, `text:chunk:content`, `text:usage`
+- Tools: `tools:approval:requested`, `tools:call:completed`, `tools:result:added`
+- Summarize: `summarize:request:started`, `summarize:usage`
+- Image: `image:request:started`, `image:usage`
+- Speech: `speech:request:started`, `speech:usage`
+- Transcription: `transcription:request:started`, `transcription:usage`
+- Video: `video:request:started`, `video:usage`
+- Client: `client:created`, `client:loading:changed`, `client:messages:cleared`
+
+Every event includes all metadata available at the time of emission (model, provider,
+system prompts, request and message IDs, options, and tool names).
+
 ## Server events
 
 There are both events that happen on the server and on the client, if you want to listen to either side you just need to
@@ -28,7 +44,7 @@ Here is an example for the server:
 import { aiEventClient } from "@tanstack/ai/event-client";
 
 // server.ts file or wherever the root of your server is
-aiEventClient.on("chat:started", e => {
+aiEventClient.on("text:request:started", e => {
   // implement whatever you need to here
 })
 // rest of your server logic
@@ -46,7 +62,7 @@ import { aiEventClient } from "@tanstack/ai/event-client";
 
 const App = () => {
   useEffect(() => {
-    const cleanup = aiEventClient.on("client:tool-call-updated", e => {
+    const cleanup = aiEventClient.on("tools:call:updated", e => {
       // do whatever you need to do
     })
     return cleanup;
@@ -55,4 +71,17 @@ const App = () => {
 }
 ```
 
+## Reconstructing chat
+
+To rebuild a chat timeline from events, listen for:
+
+- `text:message:created` (full message content)
+- `text:message:user` (explicit user message events)
+- `text:chunk:*` (streaming content, tool calls, tool results, thinking)
+- `tools:*` (approvals, input availability, call completion)
+- `text:request:completed` (final completion + usage)
+
+This set is sufficient to replay the conversation end-to-end for observability and
+telemetry systems.
+
 

examples/ts-react-chat/src/routes/api.tanchat.ts

@@ -94,10 +94,13 @@ export const Route = createFileRoute('/api/tanchat')({
             }),
           openrouter: () =>
             createChatOptions({
-              adapter: openRouterText('openrouter/auto'),
+              adapter: openRouterText('openai/gpt-5.1'),
               modelOptions: {
                 models: ['openai/chatgpt-4o-latest'],
                 route: 'fallback',
+                reasoning: {
+                  effort: 'medium',
+                },
               },
             }),
           gemini: () =>

packages/typescript/ai-client/src/chat-client.ts

@@ -160,13 +160,16 @@ export class ChatClient {
           input: any
           approvalId: string
         }) => {
-          this.events.approvalRequested(
-            this.currentMessageId || '',
-            args.toolCallId,
-            args.toolName,
-            args.input,
-            args.approvalId,
-          )
+          if (this.currentStreamId) {
+            this.events.approvalRequested(
+              this.currentStreamId,
+              this.currentMessageId || '',
+              args.toolCallId,
+              args.toolName,
+              args.input,
+              args.approvalId,
+            )
+          }
         },
       },
     })
@@ -210,7 +213,10 @@ export class ChatClient {
       parts: [],
       createdAt: new Date(),
     }
-    this.events.messageAppended(assistantMessage)
+    this.events.messageAppended(
+      assistantMessage,
+      this.currentStreamId || undefined,
+    )
 
     // Process each chunk
     for await (const chunk of source) {

packages/typescript/ai-client/src/events.ts

@@ -17,7 +17,7 @@ export abstract class ChatClientEventEmitter {
    */
   protected abstract emitEvent(
     eventName: string,
-    data?: Record<string, any>,
+    data?: Record<string, unknown>,
   ): void
 
   /**
@@ -33,14 +33,14 @@ export abstract class ChatClientEventEmitter {
    * Emit loading state changed event
    */
   loadingChanged(isLoading: boolean): void {
-    this.emitEvent('client:loading-changed', { isLoading })
+    this.emitEvent('client:loading:changed', { isLoading })
   }
 
   /**
    * Emit error state changed event
    */
   errorChanged(error: string | null): void {
-    this.emitEvent('client:error-changed', {
+    this.emitEvent('client:error:changed', {
       error,
     })
   }
@@ -49,12 +49,8 @@ export abstract class ChatClientEventEmitter {
    * Emit text update events (combines processor and client events)
    */
   textUpdated(streamId: string, messageId: string, content: string): void {
-    this.emitEvent('processor:text-updated', {
+    this.emitEvent('text:chunk:content', {
       streamId,
-      content,
-    })
-
-    this.emitEvent('client:assistant-message-updated', {
       messageId,
       content,
     })
@@ -71,15 +67,8 @@ export abstract class ChatClientEventEmitter {
     state: string,
     args: string,
   ): void {
-    this.emitEvent('processor:tool-call-state-changed', {
+    this.emitEvent('tools:call:updated', {
       streamId,
-      toolCallId,
-      toolName,
-      state,
-      arguments: args,
-    })
-
-    this.emitEvent('client:tool-call-updated', {
       messageId,
       toolCallId,
       toolName,
@@ -91,22 +80,6 @@ export abstract class ChatClientEventEmitter {
   /**
    * Emit tool result state change event
    */
-  toolResultStateChanged(
-    streamId: string,
-    toolCallId: string,
-    content: string,
-    state: string,
-    error?: string,
-  ): void {
-    this.emitEvent('processor:tool-result-state-changed', {
-      streamId,
-      toolCallId,
-      content,
-      state,
-      error,
-    })
-  }
-
   /**
    * Emit thinking update event
    */
@@ -116,7 +89,7 @@ export abstract class ChatClientEventEmitter {
     content: string,
     delta?: string,
   ): void {
-    this.emitEvent('stream:chunk:thinking', {
+    this.emitEvent('text:chunk:thinking', {
       streamId,
       messageId,
       content,
@@ -128,13 +101,15 @@ export abstract class ChatClientEventEmitter {
    * Emit approval requested event
    */
   approvalRequested(
+    streamId: string,
     messageId: string,
     toolCallId: string,
     toolName: string,
-    input: any,
+    input: unknown,
     approvalId: string,
   ): void {
-    this.emitEvent('client:approval-requested', {
+    this.emitEvent('tools:approval:requested', {
+      streamId,
       messageId,
       toolCallId,
       toolName,
@@ -146,26 +121,34 @@ export abstract class ChatClientEventEmitter {
   /**
    * Emit message appended event
    */
-  messageAppended(uiMessage: UIMessage): void {
-    const contentPreview = uiMessage.parts
-      .filter((p) => p.type === 'text')
-      .map((p) => (p as any).content)
+  messageAppended(uiMessage: UIMessage, streamId?: string): void {
+    const content = uiMessage.parts
+      .filter((part) => part.type === 'text')
+      .map((part) => part.content)
       .join(' ')
-      .substring(0, 100)
 
-    this.emitEvent('client:message-appended', {
+    this.emitEvent('text:message:created', {
+      streamId,
       messageId: uiMessage.id,
       role: uiMessage.role,
-      contentPreview,
+      content,
+      parts: uiMessage.parts,
     })
   }
 
   /**
    * Emit message sent event
    */
   messageSent(messageId: string, content: string): void {
-    this.emitEvent('client:message-sent', {
+    this.emitEvent('text:message:created', {
+      messageId,
+      role: 'user',
+      content,
+    })
+
+    this.emitEvent('text:message:user', {
       messageId,
+      role: 'user',
       content,
     })
   }
@@ -190,7 +173,7 @@ export abstract class ChatClientEventEmitter {
    * Emit messages cleared event
    */
   messagesCleared(): void {
-    this.emitEvent('client:messages-cleared')
+    this.emitEvent('client:messages:cleared')
   }
 
   /**
@@ -199,10 +182,10 @@ export abstract class ChatClientEventEmitter {
   toolResultAdded(
     toolCallId: string,
     toolName: string,
-    output: any,
+    output: unknown,
     state: string,
   ): void {
-    this.emitEvent('tool:result-added', {
+    this.emitEvent('tools:result:added', {
       toolCallId,
       toolName,
       output,
@@ -218,7 +201,7 @@ export abstract class ChatClientEventEmitter {
     toolCallId: string,
     approved: boolean,
   ): void {
-    this.emitEvent('tool:approval-responded', {
+    this.emitEvent('tools:approval:responded', {
       approvalId,
       toolCallId,
       approved,
@@ -235,14 +218,19 @@ export class DefaultChatClientEventEmitter extends ChatClientEventEmitter {
    */
   protected emitEvent(eventName: string, data?: Record<string, any>): void {
     // For client:* and tool:* events, automatically add clientId and timestamp
-    if (eventName.startsWith('client:') || eventName.startsWith('tool:')) {
+    if (
+      eventName.startsWith('client:') ||
+      eventName.startsWith('tools:') ||
+      eventName.startsWith('text:')
+    ) {
       aiEventClient.emit(eventName as any, {
         ...data,
         clientId: this.clientId,
+        source: 'client',
         timestamp: Date.now(),
       })
     } else {
-      // For other events (e.g., processor:*), just add timestamp
+      // For other events, just add timestamp
       aiEventClient.emit(eventName as any, {
         ...data,
         timestamp: Date.now(),