@agent-native/core 0.172.3 → 0.172.4

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/tracking/providers.js

@@ -140,11 +140,16 @@ function createPostHogProvider(apiKey, host, errorTracking) {
         enqueue(`${host}/i/v0/e/`, JSON.stringify({
             api_key: apiKey,
             event: event.name,
+            // Top level, NOT inside `properties`: PostHog reads the event time from
+            // the payload root and treats a `properties.timestamp` as an ordinary
+            // custom property, stamping the event with its ingestion time instead.
+            // An agent run emits its whole tree in one burst at the end, so that
+            // collapsed a five-minute waterfall into the 100ms it took to flush.
+            timestamp: event.timestamp,
             properties: {
                 distinct_id: distinctId,
                 ...properties,
                 ...(event.sessionId ? { $session_id: event.sessionId } : {}),
-                timestamp: event.timestamp,
             },
         }));
     };
@@ -176,10 +181,10 @@ function createPostHogProvider(apiKey, host, errorTracking) {
                 api_key: apiKey,
                 event: event.name,
                 distinct_id: distinctId,
+                timestamp: event.timestamp,
                 properties: {
                     ...event.properties,
                     ...(event.sessionId ? { $session_id: event.sessionId } : {}),
-                    timestamp: event.timestamp,
                 },
             }));
         },
@@ -218,7 +223,8 @@ export function sendPostHogEvent(name, properties, distinctId) {
         api_key: apiKey,
         event: name,
         distinct_id: distinctId,
-        properties: { ...properties, timestamp: new Date().toISOString() },
+        timestamp: new Date().toISOString(),
+        properties,
     }));
     return true;
 }

package/docs/content/observability.mdx

@@ -297,13 +297,24 @@ All endpoints support `?since=N` (ms timestamp) and `?limit=N` query params.
 When `POSTHOG_API_KEY` is set, every instrumented run is mirrored to PostHog's
 LLM analytics as a full trace tree:
 
-| Event            | Emitted per | Carries                                                 |
-| ---------------- | ----------- | ------------------------------------------------------- |
-| `$ai_trace`      | agent run   | Latency, error state, token totals, cost                |
-| `$ai_generation` | model call  | Model, provider, tokens, cost, tool definitions offered |
-| `$ai_span`       | tool call   | Tool name, duration, error state                        |
-
-Nodes share the run id as `$ai_trace_id`, so PostHog renders one tree per run.
+| Event            | Emitted per      | Carries                                                   |
+| ---------------- | ---------------- | --------------------------------------------------------- |
+| `$ai_trace`      | agent run        | Run name, totals, terminal state, run-level failure       |
+| `$ai_generation` | model round-trip | Prompt, answer, model, tokens, cost, latency, stop reason |
+| `$ai_span`       | tool call        | Tool name, duration, failure class                        |
+
+Nodes share the run id as `$ai_trace_id`, so PostHog renders one tree per run,
+with each tool span under the generation that requested it. A run's tool
+definitions are never sent: they are the same catalogue on every call, and a
+call is identified by its name in `$ai_output_choices` and by its own span.
+
+`$ai_is_error` means a different thing at each level, and never travels without
+`$ai_error` and `$ai_error_type`. On a generation it is the model call itself
+failing — a provider error, a dropped stream. On a span it is a tool that
+crashed or returned an error. On the trace it is the run: a step budget, a
+timeout, a no-progress cut-off, or a tool that stopped the run. A run that
+failed after the model answered leaves its generations green, because they did
+not fail.
 `$ai_session_id` is the conversation thread; the browser session is sent
 separately as `$session_id` so a trace links to its session replay.
 
@@ -337,9 +348,15 @@ to each other.
 
 Thumbs, category, and free-text feedback all emit `$ai_feedback`. PostHog's LLM
 analytics feedback view reads a `survey sent` event instead, so set
-`POSTHOG_AI_FEEDBACK_SURVEY_ID` (and `POSTHOG_AI_FEEDBACK_SURVEY_QUESTION_ID`
-for multi-question surveys) to populate it. Without a survey id no survey event
-is sent.
+`POSTHOG_AI_FEEDBACK_SURVEY_ID` to the survey PostHog creates from a trace's
+**Feedback** tab. That one id is the whole configuration; without it no survey
+event is sent.
+
+A thumbs vote answers the survey's first question as PostHog's choice index
+(`1` up, `2` down) and the free text after a thumbs-down answers the follow-up
+question, so the text never lands where the rating belongs. Both carry one
+submission id per rated message, which is how PostHog joins them into a single
+response, and a thumbs-down stays marked incomplete until its follow-up arrives.
 
 ## Export to external platforms {#export}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.172.3",
+  "version": "0.172.4",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -429,8 +429,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.8",
-    "@agent-native/toolkit": "^0.16.11"
+    "@agent-native/toolkit": "^0.16.11",
+    "@agent-native/recap-cli": "0.5.8"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",