feat: update event client (TanStack#128)

* feat: update event client

* feat: update event client

* ci: apply automated fixes

* changeset

* update deps

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: AlemTuzlak

.changeset/fluffy-sites-exist.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/ai-devtools-core': patch
+'@tanstack/ai': patch
+---
+
+update event client

.github/instructions/copilot-instructions.md

@@ -24,8 +24,7 @@ Write tests for any new functionality.
 When defining new types, first check if the types exist somewhere and re-use them, do not create new types that are similar to existing ones.
 
 When modifying existing functionality, ensure backward compatibility unless there's a strong reason to introduce breaking changes. If breaking changes are necessary, document them clearly in the relevant documentation files.
-
-When subscribing to an event using `aiEventClient.on` in the devtools packages, always add the option `{ withEventTarget: false }` as the second argument to prevent over-subscriptions in the devtools.
+ 
 
 Under no circumstances should casting `as any` be used in the codebase. Always strive to find or create the appropriate type definitions. Avoid casting unless absolutely neccessary, and even then, prefer using `satisfies` for type assertions to maintain type safety.
 

docs/config.json

@@ -19,7 +19,7 @@
         },
         {
           "label": "Devtools",
-          "to": "getting-started/devtools"        
+          "to": "getting-started/devtools"
         }
       ]
     },
@@ -62,6 +62,10 @@
           "label": "Connection Adapters",
           "to": "guides/connection-adapters"
         },
+        {
+          "label": "Observability",
+          "to": "guides/observability"
+        },
         {
           "label": "Per-Model Type Safety",
           "to": "guides/per-model-type-safety"
@@ -542,4 +546,4 @@
       ]
     }
   ]
-}
+}

docs/guides/observability.md

@@ -0,0 +1,52 @@
+# Event client
+
+The `@tanstack/ai` package offers you an event client for observability and debugging purposes.
+It's a fully type-safe decoupled event-driven system that emits events whenever they are internally
+triggered and you can subscribe to those events for observability.
+
+Because the same event client is used for both the TanStack Devtools system and observability locally it will work
+by subscribing to the event bus and emitting events to/from the event bus into the listeners by default. If you 
+want to subscribe to events in production as well you need to pass in a third argument to the `on` function,
+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. 
+
+## 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
+subscribe on the server/client respectfully. 
+
+Here is an example for the server:
+```ts
+import { aiEventClient } from "@tanstack/ai/event-client";
+
+// server.ts file or wherever the root of your server is
+aiEventClient.on("chat:started", e => {
+  // implement whatever you need to here
+})
+// rest of your server logic
+const app = new Server();
+app.get()
+```
+
+## Client events
+
+Listening on the client is the same approach, just subscribe to the events:
+
+```tsx
+// App.tsx
+import { aiEventClient } from "@tanstack/ai/event-client";
+
+const App = () => {
+  useEffect(() => {
+    const cleanup = aiEventClient.on("client:tool-call-updated", e => {
+      // do whatever you need to do
+    })
+    return cleanup;
+  },[])
+  return <div></div>
+}
+```
+
+ 

docs/reference/variables/aiEventClient.md

@@ -9,4 +9,4 @@ title: aiEventClient
 const aiEventClient: AiEventClient;
 ```
 
-Defined in: [event-client.ts:387](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/event-client.ts#L387)
+Defined in: [event-client.ts:307](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/event-client.ts#L307)

examples/ts-solid-chat/package.json

@@ -39,7 +39,7 @@
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",
-    "@tanstack/devtools-event-client": "^0.3.5",
+    "@tanstack/devtools-event-client": "^0.4.0",
     "@tanstack/devtools-vite": "^0.3.11",
     "@testing-library/dom": "^10.4.1",
     "@types/node": "^24.10.1",