@tanstack/ai 0.2.2 → 0.3.0

package/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>
 

package/dist/esm/activities/chat/index.js

@@ -15,7 +15,7 @@ class TextEngine {
     this.totalChunkCount = 0;
     this.currentMessageId = null;
     this.accumulatedContent = "";
-    this.doneChunk = null;
+    this.finishedEvent = null;
     this.shouldEmitStreamEnd = true;
     this.earlyTermination = false;
     this.toolPhase = "continue";
@@ -66,61 +66,56 @@ class TextEngine {
   }
   beforeRun() {
     this.streamStartTime = Date.now();
-    const {
-      model,
-      tools,
-      temperature,
-      topP,
-      maxTokens,
-      metadata,
-      modelOptions,
-      conversationId
-    } = this.params;
+    const { tools, temperature, topP, maxTokens, metadata } = this.params;
     const options = {};
     if (temperature !== void 0) options.temperature = temperature;
     if (topP !== void 0) options.topP = topP;
     if (maxTokens !== void 0) options.maxTokens = maxTokens;
     if (metadata !== void 0) options.metadata = metadata;
-    aiEventClient.emit("text:started", {
-      requestId: this.requestId,
-      streamId: this.streamId,
-      model,
-      provider: this.adapter.name,
-      messageCount: this.initialMessageCount,
-      hasTools: !!tools && tools.length > 0,
-      streaming: true,
-      timestamp: Date.now(),
-      clientId: conversationId,
-      toolNames: tools?.map((t) => t.name),
-      options: Object.keys(options).length > 0 ? options : void 0,
-      modelOptions
-    });
-    aiEventClient.emit("stream:started", {
-      streamId: this.streamId,
-      model,
-      provider: this.adapter.name,
+    this.eventOptions = Object.keys(options).length > 0 ? options : void 0;
+    this.eventToolNames = tools?.map((t) => t.name);
+    aiEventClient.emit("text:request:started", {
+      ...this.buildTextEventContext(),
       timestamp: Date.now()
     });
+    const messagesToEmit = this.params.conversationId ? this.messages.slice(-1).filter((m) => m.role === "user") : this.messages;
+    messagesToEmit.forEach((message, index) => {
+      const messageIndex = this.params.conversationId ? this.messages.length - 1 : index;
+      const messageId = this.createId("msg");
+      const baseContext = this.buildTextEventContext();
+      const content = this.getContentString(message.content);
+      aiEventClient.emit("text:message:created", {
+        ...baseContext,
+        messageId,
+        role: message.role,
+        content,
+        toolCalls: message.toolCalls,
+        messageIndex,
+        timestamp: Date.now()
+      });
+      if (message.role === "user") {
+        aiEventClient.emit("text:message:user", {
+          ...baseContext,
+          messageId,
+          role: "user",
+          content,
+          messageIndex,
+          timestamp: Date.now()
+        });
+      }
+    });
   }
   afterRun() {
     if (!this.shouldEmitStreamEnd) {
       return;
     }
     const now = Date.now();
-    aiEventClient.emit("text:completed", {
-      requestId: this.requestId,
-      streamId: this.streamId,
-      model: this.params.model,
+    aiEventClient.emit("text:request:completed", {
+      ...this.buildTextEventContext(),
       content: this.accumulatedContent,
       messageId: this.currentMessageId || void 0,
       finishReason: this.lastFinishReason || void 0,
-      usage: this.doneChunk?.usage,
-      timestamp: now
-    });
-    aiEventClient.emit("stream:ended", {
-      requestId: this.requestId,
-      streamId: this.streamId,
-      totalChunks: this.totalChunkCount,
+      usage: this.finishedEvent?.usage,
       duration: now - this.streamStartTime,
       timestamp: now
     });
@@ -141,7 +136,15 @@ class TextEngine {
   beginIteration() {
     this.currentMessageId = this.createId("msg");
     this.accumulatedContent = "";
-    this.doneChunk = null;
+    this.finishedEvent = null;
+    const baseContext = this.buildTextEventContext();
+    aiEventClient.emit("text:message:created", {
+      ...baseContext,
+      messageId: this.currentMessageId,
+      role: "assistant",
+      content: "",
+      timestamp: Date.now()
+    });
   }
   async *streamModelResponse() {
     const { temperature, topP, maxTokens, metadata, modelOptions } = this.params;
@@ -176,102 +179,107 @@ class TextEngine {
   }
   handleStreamChunk(chunk) {
     switch (chunk.type) {
-      case "content":
-        this.handleContentChunk(chunk);
+      // AG-UI Events
+      case "TEXT_MESSAGE_CONTENT":
+        this.handleTextMessageContentEvent(chunk);
+        break;
+      case "TOOL_CALL_START":
+        this.handleToolCallStartEvent(chunk);
         break;
-      case "tool_call":
-        this.handleToolCallChunk(chunk);
+      case "TOOL_CALL_ARGS":
+        this.handleToolCallArgsEvent(chunk);
         break;
-      case "tool_result":
-        this.handleToolResultChunk(chunk);
+      case "TOOL_CALL_END":
+        this.handleToolCallEndEvent(chunk);
         break;
-      case "done":
-        this.handleDoneChunk(chunk);
+      case "RUN_FINISHED":
+        this.handleRunFinishedEvent(chunk);
         break;
-      case "error":
-        this.handleErrorChunk(chunk);
+      case "RUN_ERROR":
+        this.handleRunErrorEvent(chunk);
         break;
-      case "thinking":
-        this.handleThinkingChunk(chunk);
+      case "STEP_FINISHED":
+        this.handleStepFinishedEvent(chunk);
         break;
     }
   }
-  handleContentChunk(chunk) {
-    this.accumulatedContent = chunk.content;
-    aiEventClient.emit("stream:chunk:content", {
-      streamId: this.streamId,
+  // ===========================
+  // AG-UI Event Handlers
+  // ===========================
+  handleTextMessageContentEvent(chunk) {
+    if (chunk.content) {
+      this.accumulatedContent = chunk.content;
+    } else {
+      this.accumulatedContent += chunk.delta;
+    }
+    aiEventClient.emit("text:chunk:content", {
+      ...this.buildTextEventContext(),
       messageId: this.currentMessageId || void 0,
-      content: chunk.content,
+      content: this.accumulatedContent,
       delta: chunk.delta,
       timestamp: Date.now()
     });
   }
-  handleToolCallChunk(chunk) {
-    this.toolCallManager.addToolCallChunk(chunk);
-    aiEventClient.emit("stream:chunk:tool-call", {
-      streamId: this.streamId,
+  handleToolCallStartEvent(chunk) {
+    this.toolCallManager.addToolCallStartEvent(chunk);
+    aiEventClient.emit("text:chunk:tool-call", {
+      ...this.buildTextEventContext(),
       messageId: this.currentMessageId || void 0,
-      toolCallId: chunk.toolCall.id,
-      toolName: chunk.toolCall.function.name,
-      index: chunk.index,
-      arguments: chunk.toolCall.function.arguments,
+      toolCallId: chunk.toolCallId,
+      toolName: chunk.toolName,
+      index: chunk.index ?? 0,
+      arguments: "",
       timestamp: Date.now()
     });
   }
-  handleToolResultChunk(chunk) {
-    aiEventClient.emit("stream:chunk:tool-result", {
-      streamId: this.streamId,
+  handleToolCallArgsEvent(chunk) {
+    this.toolCallManager.addToolCallArgsEvent(chunk);
+    aiEventClient.emit("text:chunk:tool-call", {
+      ...this.buildTextEventContext(),
       messageId: this.currentMessageId || void 0,
       toolCallId: chunk.toolCallId,
-      result: chunk.content,
+      toolName: "",
+      index: 0,
+      arguments: chunk.delta,
       timestamp: Date.now()
     });
   }
-  handleDoneChunk(chunk) {
-    if (this.doneChunk?.finishReason === "tool_calls" && chunk.finishReason === "stop") {
-      this.lastFinishReason = chunk.finishReason;
-      aiEventClient.emit("stream:chunk:done", {
-        streamId: this.streamId,
-        messageId: this.currentMessageId || void 0,
-        finishReason: chunk.finishReason,
-        usage: chunk.usage,
-        timestamp: Date.now()
-      });
-      if (chunk.usage) {
-        aiEventClient.emit("usage:tokens", {
-          requestId: this.requestId,
-          streamId: this.streamId,
-          messageId: this.currentMessageId || void 0,
-          model: this.params.model,
-          usage: chunk.usage,
-          timestamp: Date.now()
-        });
-      }
-      return;
-    }
-    this.doneChunk = chunk;
-    this.lastFinishReason = chunk.finishReason;
-    aiEventClient.emit("stream:chunk:done", {
-      streamId: this.streamId,
+  handleToolCallEndEvent(chunk) {
+    this.toolCallManager.completeToolCall(chunk);
+    aiEventClient.emit("text:chunk:tool-result", {
+      ...this.buildTextEventContext(),
+      messageId: this.currentMessageId || void 0,
+      toolCallId: chunk.toolCallId,
+      result: chunk.result || "",
+      timestamp: Date.now()
+    });
+  }
+  handleRunFinishedEvent(chunk) {
+    aiEventClient.emit("text:chunk:done", {
+      ...this.buildTextEventContext(),
       messageId: this.currentMessageId || void 0,
       finishReason: chunk.finishReason,
       usage: chunk.usage,
       timestamp: Date.now()
     });
     if (chunk.usage) {
-      aiEventClient.emit("usage:tokens", {
-        requestId: this.requestId,
-        streamId: this.streamId,
+      aiEventClient.emit("text:usage", {
+        ...this.buildTextEventContext(),
         messageId: this.currentMessageId || void 0,
-        model: this.params.model,
         usage: chunk.usage,
         timestamp: Date.now()
       });
     }
+    if (this.finishedEvent?.finishReason === "tool_calls" && chunk.finishReason === "stop") {
+      this.lastFinishReason = chunk.finishReason;
+      return;
+    }
+    this.finishedEvent = chunk;
+    this.lastFinishReason = chunk.finishReason;
   }
-  handleErrorChunk(chunk) {
-    aiEventClient.emit("stream:chunk:error", {
-      streamId: this.streamId,
+  handleRunErrorEvent(chunk) {
+    aiEventClient.emit("text:chunk:error", {
+      ...this.buildTextEventContext(),
       messageId: this.currentMessageId || void 0,
       error: chunk.error.message,
       timestamp: Date.now()
@@ -279,29 +287,23 @@ class TextEngine {
     this.earlyTermination = true;
     this.shouldEmitStreamEnd = false;
   }
-  handleThinkingChunk(chunk) {
-    aiEventClient.emit("stream:chunk:thinking", {
-      streamId: this.streamId,
-      messageId: this.currentMessageId || void 0,
-      content: chunk.content,
-      delta: chunk.delta,
-      timestamp: Date.now()
-    });
+  handleStepFinishedEvent(chunk) {
+    if (chunk.content || chunk.delta) {
+      aiEventClient.emit("text:chunk:thinking", {
+        ...this.buildTextEventContext(),
+        messageId: this.currentMessageId || void 0,
+        content: chunk.content || "",
+        delta: chunk.delta,
+        timestamp: Date.now()
+      });
+    }
   }
   async *checkForPendingToolCalls() {
     const pendingToolCalls = this.getPendingToolCallsFromMessages();
     if (pendingToolCalls.length === 0) {
       return "continue";
     }
-    const doneChunk = this.createSyntheticDoneChunk();
-    aiEventClient.emit("text:iteration", {
-      requestId: this.requestId,
-      streamId: this.streamId,
-      iterationNumber: this.iterationCount + 1,
-      messageCount: this.messages.length,
-      toolCallCount: pendingToolCalls.length,
-      timestamp: Date.now()
-    });
+    const finishEvent = this.createSyntheticFinishedEvent();
     const { approvals, clientToolResults } = this.collectClientState();
     const executionResult = await executeToolCalls(
       pendingToolCalls,
@@ -312,13 +314,13 @@ class TextEngine {
     if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
       for (const chunk of this.emitApprovalRequests(
         executionResult.needsApproval,
-        doneChunk
+        finishEvent
       )) {
         yield chunk;
       }
       for (const chunk of this.emitClientToolInputs(
         executionResult.needsClientExecution,
-        doneChunk
+        finishEvent
       )) {
         yield chunk;
       }
@@ -327,7 +329,7 @@ class TextEngine {
     }
     const toolResultChunks = this.emitToolResults(
       executionResult.results,
-      doneChunk
+      finishEvent
     );
     for (const chunk of toolResultChunks) {
       yield chunk;
@@ -340,19 +342,11 @@ class TextEngine {
       return;
     }
     const toolCalls = this.toolCallManager.getToolCalls();
-    const doneChunk = this.doneChunk;
-    if (!doneChunk || toolCalls.length === 0) {
+    const finishEvent = this.finishedEvent;
+    if (!finishEvent || toolCalls.length === 0) {
       this.setToolPhase("stop");
       return;
     }
-    aiEventClient.emit("text:iteration", {
-      requestId: this.requestId,
-      streamId: this.streamId,
-      iterationNumber: this.iterationCount + 1,
-      messageCount: this.messages.length,
-      toolCallCount: toolCalls.length,
-      timestamp: Date.now()
-    });
     this.addAssistantToolCallMessage(toolCalls);
     const { approvals, clientToolResults } = this.collectClientState();
     const executionResult = await executeToolCalls(
@@ -364,13 +358,13 @@ class TextEngine {
     if (executionResult.needsApproval.length > 0 || executionResult.needsClientExecution.length > 0) {
       for (const chunk of this.emitApprovalRequests(
         executionResult.needsApproval,
-        doneChunk
+        finishEvent
       )) {
         yield chunk;
       }
       for (const chunk of this.emitClientToolInputs(
         executionResult.needsClientExecution,
-        doneChunk
+        finishEvent
       )) {
         yield chunk;
       }
@@ -379,7 +373,7 @@ class TextEngine {
     }
     const toolResultChunks = this.emitToolResults(
       executionResult.results,
-      doneChunk
+      finishEvent
     );
     for (const chunk of toolResultChunks) {
       yield chunk;
@@ -388,9 +382,10 @@ class TextEngine {
     this.setToolPhase("continue");
   }
   shouldExecuteToolPhase() {
-    return this.doneChunk?.finishReason === "tool_calls" && this.tools.length > 0 && this.toolCallManager.hasToolCalls();
+    return this.finishedEvent?.finishReason === "tool_calls" && this.tools.length > 0 && this.toolCallManager.hasToolCalls();
   }
   addAssistantToolCallMessage(toolCalls) {
+    const messageId = this.currentMessageId ?? this.createId("msg");
     this.messages = [
       ...this.messages,
       {
@@ -399,6 +394,14 @@ class TextEngine {
         toolCalls
       }
     ];
+    aiEventClient.emit("text:message:created", {
+      ...this.buildTextEventContext(),
+      messageId,
+      role: "assistant",
+      content: this.accumulatedContent || "",
+      toolCalls,
+      timestamp: Date.now()
+    });
   }
   collectClientState() {
     const approvals = /* @__PURE__ */ new Map();
@@ -418,11 +421,11 @@ class TextEngine {
     }
     return { approvals, clientToolResults };
   }
-  emitApprovalRequests(approvals, doneChunk) {
+  emitApprovalRequests(approvals, finishEvent) {
     const chunks = [];
     for (const approval of approvals) {
-      aiEventClient.emit("stream:approval-requested", {
-        streamId: this.streamId,
+      aiEventClient.emit("tools:approval:requested", {
+        ...this.buildTextEventContext(),
         messageId: this.currentMessageId || void 0,
         toolCallId: approval.toolCallId,
         toolName: approval.toolName,
@@ -431,26 +434,28 @@ class TextEngine {
         timestamp: Date.now()
       });
       chunks.push({
-        type: "approval-requested",
-        id: doneChunk.id,
-        model: doneChunk.model,
+        type: "CUSTOM",
         timestamp: Date.now(),
-        toolCallId: approval.toolCallId,
-        toolName: approval.toolName,
-        input: approval.input,
-        approval: {
-          id: approval.approvalId,
-          needsApproval: true
+        model: finishEvent.model,
+        name: "approval-requested",
+        data: {
+          toolCallId: approval.toolCallId,
+          toolName: approval.toolName,
+          input: approval.input,
+          approval: {
+            id: approval.approvalId,
+            needsApproval: true
+          }
         }
       });
     }
     return chunks;
   }
-  emitClientToolInputs(clientRequests, doneChunk) {
+  emitClientToolInputs(clientRequests, finishEvent) {
     const chunks = [];
     for (const clientTool of clientRequests) {
-      aiEventClient.emit("stream:tool-input-available", {
-        streamId: this.streamId,
+      aiEventClient.emit("tools:input:available", {
+        ...this.buildTextEventContext(),
         messageId: this.currentMessageId || void 0,
         toolCallId: clientTool.toolCallId,
         toolName: clientTool.toolName,
@@ -458,23 +463,24 @@ class TextEngine {
         timestamp: Date.now()
       });
       chunks.push({
-        type: "tool-input-available",
-        id: doneChunk.id,
-        model: doneChunk.model,
+        type: "CUSTOM",
         timestamp: Date.now(),
-        toolCallId: clientTool.toolCallId,
-        toolName: clientTool.toolName,
-        input: clientTool.input
+        model: finishEvent.model,
+        name: "tool-input-available",
+        data: {
+          toolCallId: clientTool.toolCallId,
+          toolName: clientTool.toolName,
+          input: clientTool.input
+        }
       });
     }
     return chunks;
   }
-  emitToolResults(results, doneChunk) {
+  emitToolResults(results, finishEvent) {
     const chunks = [];
     for (const result of results) {
-      aiEventClient.emit("tool:call-completed", {
-        requestId: this.requestId,
-        streamId: this.streamId,
+      aiEventClient.emit("tools:call:completed", {
+        ...this.buildTextEventContext(),
         messageId: this.currentMessageId || void 0,
         toolCallId: result.toolCallId,
         toolName: result.toolName,
@@ -483,15 +489,14 @@ class TextEngine {
         timestamp: Date.now()
       });
       const content = JSON.stringify(result.result);
-      const chunk = {
-        type: "tool_result",
-        id: doneChunk.id,
-        model: doneChunk.model,
+      chunks.push({
+        type: "TOOL_CALL_END",
         timestamp: Date.now(),
+        model: finishEvent.model,
         toolCallId: result.toolCallId,
-        content
-      };
-      chunks.push(chunk);
+        toolName: result.toolName,
+        result: content
+      });
       this.messages = [
         ...this.messages,
         {
@@ -500,6 +505,13 @@ class TextEngine {
           toolCallId: result.toolCallId
         }
       ];
+      aiEventClient.emit("text:message:created", {
+        ...this.buildTextEventContext(),
+        messageId: this.createId("msg"),
+        role: "tool",
+        content,
+        timestamp: Date.now()
+      });
     }
     return chunks;
   }
@@ -520,10 +532,10 @@ class TextEngine {
     }
     return pending;
   }
-  createSyntheticDoneChunk() {
+  createSyntheticFinishedEvent() {
     return {
-      type: "done",
-      id: this.createId("pending"),
+      type: "RUN_FINISHED",
+      runId: this.createId("pending"),
       model: this.params.model,
       timestamp: Date.now(),
       finishReason: "tool_calls"
@@ -542,6 +554,28 @@ class TextEngine {
   isAborted() {
     return !!this.effectiveSignal?.aborted;
   }
+  buildTextEventContext() {
+    return {
+      requestId: this.requestId,
+      streamId: this.streamId,
+      provider: this.adapter.name,
+      model: this.params.model,
+      clientId: this.params.conversationId,
+      source: "server",
+      systemPrompts: this.systemPrompts.length > 0 ? this.systemPrompts : void 0,
+      toolNames: this.eventToolNames,
+      options: this.eventOptions,
+      modelOptions: this.params.modelOptions,
+      messageCount: this.initialMessageCount,
+      hasTools: this.tools.length > 0,
+      streaming: true
+    };
+  }
+  getContentString(content) {
+    if (typeof content === "string") return content;
+    const text = content?.map((part) => part.type === "text" ? part.content : "").join("") || "";
+    return text;
+  }
   setToolPhase(phase) {
     this.toolPhase = phase;
     if (phase === "wait") {