@agent-native/core 0.133.2 → 0.134.0

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1646
+- core files: 1652
 - toolkit files: 168
-- template files: 7414
+- template files: 7421

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @agent-native/core
 
+## 0.134.0
+
+### Minor Changes
+
+- 46cd162: Make PostHog a first-class error-reporting and LLM-observability backend, and fix
+  the malformed exception events it was already receiving.
+
+  `captureException()` emitted an event named `$exception` carrying camelCase
+  properties. PostHog ingests anything by that name and renders it as an issue, but
+  it groups and symbolicates from `$exception_list` — so every PostHog-configured
+  app was already collecting exceptions that arrived empty and ungroupable, which
+  reads as coverage rather than as a failure. The PostHog provider now reshapes
+  those into a real `$exception_list` with parsed stack frames.
+
+  Route errors no longer depend on Sentry. The Nitro `error` hook lived inside
+  `sentry-plugin.ts`, which returns early when no `SENTRY_DSN` is set, so an app
+  running PostHog alone reported no route errors at all. The hook moved to
+  `core-routes-plugin.ts` and goes through the provider-agnostic `captureError()`
+  registry, so every configured backend receives it. The ~150 lines of
+  production-tuned drop rules (expected 4xx, permission rejections, Lambda
+  freeze/thaw `socket hang up`) moved out of Sentry's `beforeSend` into
+  `server/error-noise-filter.ts` and now apply to every backend — without them a
+  second backend receives a firehose. Server exceptions are also attributed to the
+  in-flight user instead of landing under `anonymous`.
+
+  Browser exceptions go to PostHog when `POSTHOG_PUBLIC_KEY` / `VITE_POSTHOG_KEY`
+  is set, posted directly rather than relayed through `/_agent-native/track`, which
+  requires a session and would drop every signed-out crash. `POSTHOG_API_KEY` is
+  deliberately not a fallback for the public key: that value is inlined into the
+  public HTML shell. Note that PostHog does not symbolicate without uploaded source
+  maps, so minified browser stacks stay minified.
+
+  LLM observability now emits the full PostHog trace tree. Previously a run
+  produced a single `$ai_generation` labelled `agent_run` whose `$ai_parent_id`
+  pointed at a span that was never sent, so PostHog wrapped it in a placeholder
+  trace with no steps. Runs now emit `$ai_trace`, one `$ai_span` per tool call, and
+  a generation parented to the trace. Tool calls ship inside `$ai_output_choices`
+  even with content capture off, because that is the only thing PostHog derives
+  `$ai_tools_called` from. The previously dead `capturePrompts` flag is now wired
+  and gates `$ai_input` and assistant text; disabled fields are omitted rather than
+  sent empty, and oversized content is replaced with an explicit truncation marker
+  instead of being silently shortened. `$ai_error` became a structured object with
+  the terminal code and retryability, and errors captured during a run carry the
+  run's `$ai_trace_id` so an issue and its trace resolve to each other.
+
+  Feedback previously emitted only for thumbs; category and free-text submissions
+  emitted nothing. All four now report, with `sentiment` still limited to thumbs so
+  a category follow-up does not double-count the vote. PostHog surfaces feedback in
+  LLM analytics only through a `survey sent` event, so that is emitted too when
+  `POSTHOG_AI_FEEDBACK_SURVEY_ID` is configured — and not at all when it is unset,
+  rather than inventing a survey id.
+
+  Agent traces carry the browser session as `$session_id` (read from a new
+  `X-Agent-Native-Session-Id` header) so a trace joins its session replay, distinct
+  from `$ai_session_id`, which remains the conversation thread.
+
+## 0.133.3
+
+### Patch Changes
+
+- 9258da4: Preserve nested object parameters when browser clients call GET actions.
+
 ## 0.133.2
 
 ### Patch Changes

package/corpus/core/docs/content/observability.mdx

@@ -256,6 +256,7 @@ All settings are stored in the `observability-config` key:
   capturePrompts: false,   // Store prompt content in traces
   captureToolArgs: false,  // Store action input arguments
   captureToolResults: false, // Store action results
+  captureLlmSpans: true,   // Emit one $ai_span per tool call to PostHog
   evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
   exporters: []            // OTLP export targets
 }
@@ -291,6 +292,39 @@ All auto-mounted at `/_agent-native/observability/`:
 
 All endpoints support `?since=N` (ms timestamp) and `?limit=N` query params.
 
+## PostHog LLM analytics {#posthog}
+
+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.
+`$ai_session_id` is the conversation thread; the browser session is sent
+separately as `$session_id` so a trace links to its session replay.
+
+Tool calls always appear (PostHog derives its tool tags from them), but their
+**arguments** require `captureToolArgs` and message content requires
+`capturePrompts`. When those are off the fields are omitted entirely rather than
+sent empty, so an unrecorded prompt is never mistaken for an empty one.
+
+Errors carry a structured `$ai_error` with the terminal code and whether the
+failure was retryable, and exceptions captured during a run carry the run's
+`$ai_trace_id` — so an issue in error tracking and the trace it came from link
+to each other.
+
+### Feedback in PostHog
+
+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.
+
 ## Export to external platforms {#export}
 
 Send traces to Langfuse, Datadog, Grafana, or any OTel-compatible backend:
@@ -331,10 +365,16 @@ The agent loop emits three span kinds:
 
 Spans are finished with OK/ERROR status and record the error message on failure. Zero/sentinel attribute values are pruned so spans aren't cluttered with noise. This OTel layer is purely additive to the in-house `agent_trace_spans` / `agent_trace_summaries` tables that power the dashboard above — both are produced from the same run events.
 
-## Error reporting (Sentry) {#sentry}
+## Error reporting (Sentry or PostHog) {#sentry}
 
 Server-side errors that escape Nitro route handlers are reported to Sentry when a DSN is configured. Without it the SDK silently no-ops, so it's safe to leave the env vars unset in dev. Browser and server events can go to the same Sentry project; split them into separate projects only when you want operational separation for ownership, volume, quotas, or alert routing.
 
+Sentry is not required. Error reporting fans out to every configured backend, so
+setting only `POSTHOG_API_KEY` gives full server-side error tracking with no
+Sentry project at all — see [Tracking](/docs/tracking#posthog-error-tracking).
+Configure both and each error goes to both. The noise-filtering rules below are
+shared by every backend rather than being Sentry-specific.
+
 | Surface            | SDK               | Env var                                                        | Notes                                                                 |
 | ------------------ | ----------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
 | Browser / SPA      | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN`, or `SENTRY_DSN` | Captures unhandled errors and route-change breadcrumbs in the client. |

package/corpus/core/docs/content/tracking.mdx

@@ -89,6 +89,31 @@ Set an env var and the provider auto-registers at server startup. No code change
 
 Multiple providers can be active simultaneously. Every event goes to all of them.
 
+## PostHog error tracking {#posthog-error-tracking}
+
+With `POSTHOG_API_KEY` set, PostHog also receives server exceptions — no Sentry
+DSN required. Server errors are captured automatically from the framework's
+route error hook and attributed to the signed-in user, with production-tuned
+noise filtering (expected 4xx responses, permission rejections, and serverless
+socket churn are dropped rather than reported).
+
+| Env var                  | Purpose                                                             |
+| ------------------------ | ------------------------------------------------------------------- |
+| `POSTHOG_ERROR_TRACKING` | Set to `false` to keep analytics but send exceptions somewhere else |
+| `POSTHOG_PUBLIC_KEY`     | Enables browser exception capture (also read as `VITE_POSTHOG_KEY`) |
+| `POSTHOG_PUBLIC_HOST`    | Browser ingest host (defaults to `POSTHOG_HOST`)                    |
+
+`POSTHOG_PUBLIC_KEY` is separate from `POSTHOG_API_KEY` on purpose: the public
+key is inlined into the HTML served to every visitor, so the server key is never
+used as a fallback for it.
+
+<Callout tone="info">
+  PostHog does not symbolicate stack traces without uploaded source maps, so
+  **minified browser stacks stay minified**. Server-side stacks are unaffected.
+  If you need symbolicated browser traces today, keep Sentry configured
+  alongside PostHog — both receive every captured error.
+</Callout>
+
 ## API {#api}
 
 ### `track(name, properties?, meta?)` {#track}

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.133.2",
+  "version": "0.134.0",
   "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": {

package/corpus/core/src/agent/run-manager.ts

@@ -735,6 +735,7 @@ export function startRun(
   ) => {
     captureError(error, {
       route: "/_agent-native/agent-chat",
+      aiTraceId: runId,
       tags: {
         source: "agent-run-manager",
         phase,
@@ -1022,6 +1023,7 @@ export function startRun(
               phase: "abort-check",
               consecutiveFailures: String(consecutiveAbortCheckFailures),
             },
+            aiTraceId: runId,
             extra: { runId, threadId },
           });
           if (!abort.signal.aborted) {
@@ -1065,6 +1067,7 @@ export function startRun(
                 phase: "heartbeat",
                 consecutiveFailures: String(consecutiveHeartbeatFailures),
               },
+              aiTraceId: runId,
               extra: { runId, threadId },
             });
           }
@@ -1108,6 +1111,7 @@ export function startRun(
     const errorCode = getRunErrorCode(error);
     captureError(error, {
       route: "/_agent-native/agent-chat",
+      aiTraceId: runId,
       tags: {
         source: "agent-run-manager",
         phase,
@@ -1686,6 +1690,7 @@ function subscribeFromSQL(
         };
         captureError(error, {
           route: "/_agent-native/agent-chat/runs/:id/events",
+          aiTraceId: runId,
           tags: {
             source: "agent-run-manager",
             phase: "sql-subscription-poll",
@@ -2313,6 +2318,7 @@ export async function abortRunDurably(
     // the request report the abort it did complete.
     captureError(error, {
       route: "/_agent-native/agent-chat/runs/:id/abort",
+      aiTraceId: runId,
       tags: {
         source: "agent-run-manager",
         phase: "abort-run",
@@ -2356,6 +2362,7 @@ export async function abortTurnDurably(
     // visible rather than silent.
     captureError(error, {
       route: "/_agent-native/agent-chat/runs/:id/abort",
+      aiTraceId: runId,
       tags: { source: "agent-run-manager", phase: "abort-turn" },
       extra: { runId, reason, ...ref },
     });

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -18,6 +18,7 @@ import {
   clearActiveRun,
   setPendingTurn,
 } from "./active-run-state.js";
+import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { captureError } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
 import { formatChatErrorText, normalizeChatError } from "./error-format.js";
@@ -2075,6 +2076,15 @@ export function createAgentChatAdapter(
         } catch {
           // Non-browser or Intl unavailable — tool calls will fall back to UTC.
         }
+        try {
+          // Lets the run's `$ai_*` events carry PostHog's `$session_id`, so an
+          // agent trace joins to the session replay it happened in.
+          const sessionId = getOrCreateAnalyticsSessionId();
+          if (sessionId) headers["x-agent-native-session-id"] = sessionId;
+          // coercion-ok: replay linkage must not block sending the message
+        } catch {
+          // Analytics session unavailable — traces just lose replay linkage.
+        }
         // Surface hint — the server uses this to keep code-editing dev tools
         // out of the app-rendered sidebar. The outer dev frame passes
         // "dev-frame" explicitly; the reusable in-product chat defaults to

package/corpus/core/src/client/analytics.ts

@@ -5,6 +5,7 @@ import {
   llmConnectionTrackingProperties,
   type LlmConnectionStatus,
 } from "../shared/llm-connection.js";
+import { toPostHogExceptionProperties } from "../tracking/posthog-exception.js";
 import {
   getOrCreateAnalyticsAnonymousId,
   getOrCreateAnalyticsSessionId,
@@ -54,6 +55,14 @@ declare global {
     __AGENT_NATIVE_CONFIG__?: {
       sentryDsn?: string;
       sentryEnvironment?: string;
+      /**
+       * Public PostHog project key + host. Publishable and identical for every
+       * visitor, so it ships inside the CDN-cached SSR shell alongside the
+       * Sentry DSN. Absent when no public key is configured.
+       */
+      posthogKey?: string;
+      posthogHost?: string;
+      posthogErrorTracking?: boolean;
       /**
        * Hosted Realtime Gateway config. Impersonal (same for every visitor),
        * so it is safe inside the CDN-cached SSR shell — unlike the per-user
@@ -442,6 +451,15 @@ function applyTrackingIdentity(
   return next;
 }
 
+/**
+ * The signed-in user id used to attribute browser events, or `undefined` when
+ * signed out. Same value the server attributes its events to (email, falling
+ * back to the auth user id), so a person is one person across both.
+ */
+function getTrackingUserId(): string | undefined {
+  return _trackingIdentity?.userId;
+}
+
 function getOrCreateAnonymousId(): string | undefined {
   return getOrCreateAnalyticsAnonymousId();
 }
@@ -1313,6 +1331,89 @@ function exceptionEventProperties(
   };
 }
 
+/**
+ * Resolve browser PostHog config, or `undefined` when error capture should not
+ * reach PostHog. Reads the SSR-injected shell config first, then Vite env for
+ * static/SPA builds that never render through the SSR handler.
+ */
+function posthogErrorConfig(): { key: string; host: string } | undefined {
+  const shell = window.__AGENT_NATIVE_CONFIG__;
+  if (shell?.posthogErrorTracking === false) return undefined;
+  const env = import.meta.env as Record<string, string | undefined>;
+  // Static/SPA builds never render through the SSR handler, so they never see
+  // the shell config that carries the server-side opt-out. Without this a
+  // Vite-only deployment could not honour `POSTHOG_ERROR_TRACKING=false`
+  // short of deleting the public key.
+  if (env?.VITE_POSTHOG_ERROR_TRACKING?.trim().toLowerCase() === "false") {
+    return undefined;
+  }
+  const key = shell?.posthogKey || env?.VITE_POSTHOG_KEY;
+  if (!key) return undefined;
+  const host = (
+    shell?.posthogHost ||
+    env?.VITE_POSTHOG_HOST ||
+    "https://us.i.posthog.com"
+  ).replace(/\/+$/, "");
+  return { key, host };
+}
+
+/**
+ * Send the exception straight to PostHog's event endpoint.
+ *
+ * Not relayed through `/_agent-native/track`: that route requires a resolved
+ * session, so every signed-out crash would be dropped without a trace.
+ *
+ * `distinct_id` uses the signed-in user id when we have one so browser events
+ * join the server's events for the same person; otherwise the stable anonymous
+ * id, which `$identify` later aliases on login.
+ */
+function sendPostHogExceptionEvent(event: CapturedExceptionEvent): void {
+  const config = posthogErrorConfig();
+  if (!config) return;
+
+  try {
+    const session = errorCaptureSessionContext();
+    const body = JSON.stringify({
+      api_key: config.key,
+      event: AGENT_NATIVE_EXCEPTION_EVENT_NAME,
+      properties: {
+        distinct_id: getTrackingUserId() || session.anonymousId || "anonymous",
+        ...toPostHogExceptionProperties({
+          type: event.type,
+          value: event.message,
+          stack: event.stack,
+          handled: event.handled,
+          level: event.level,
+        }),
+        $current_url: event.url,
+        $session_id: session.sessionId,
+        ...(session.replayId ? { $replay_id: session.replayId } : {}),
+        ...(event.release ? { release: event.release } : {}),
+        ...(event.environment ? { environment: event.environment } : {}),
+        ...(event.tags ? { exceptionTags: event.tags } : {}),
+        source: "browser",
+      },
+      timestamp: event.occurredAt,
+    });
+    const endpoint = `${config.host}/i/v0/e/`;
+
+    if (navigator.sendBeacon) {
+      // text/plain avoids a CORS preflight the page may not survive.
+      const blob = new Blob([body], { type: "text/plain;charset=UTF-8" });
+      if (navigator.sendBeacon(endpoint, blob)) return;
+    }
+    fetch(endpoint, {
+      method: "POST",
+      body,
+      keepalive: true,
+      headers: { "Content-Type": "text/plain;charset=UTF-8" },
+    }).catch(() => {});
+    // coercion-ok: throwing would replace the page's real error
+  } catch {
+    // Error reporting must never mask the original failure.
+  }
+}
+
 function sendExceptionEvent(event: CapturedExceptionEvent): void {
   // Route through the existing first-party analytics ingest as a dedicated
   // `$exception` event. This reuses the public-key auth + sendBeacon/keepalive
@@ -1322,6 +1423,7 @@ function sendExceptionEvent(event: CapturedExceptionEvent): void {
     AGENT_NATIVE_EXCEPTION_EVENT_NAME,
     exceptionEventProperties(event),
   );
+  sendPostHogExceptionEvent(event);
 }
 
 function emitExceptionToReplay(event: CapturedExceptionEvent): void {
@@ -1339,7 +1441,9 @@ function errorCaptureAutoEnabled(): boolean {
     _agentNativeAnalyticsPublicKey ||
     (import.meta.env as Record<string, string | undefined>)
       ?.VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY;
-  return !!publicKey;
+  // A PostHog public key is an equally explicit opt-in — an app running
+  // PostHog and no Agent Native Analytics should still report browser crashes.
+  return !!publicKey || !!posthogErrorConfig();
 }
 
 function maybeInstallErrorCapture(

package/corpus/core/src/client/use-action.ts

@@ -207,6 +207,12 @@ function appendActionQueryParam(
     }
     return;
   }
+  if (typeof value === "object") {
+    // defineAction restores JSON strings when the schema expects an object.
+    // Preserve nested GET params instead of collapsing them to "[object Object]".
+    qs.append(key, JSON.stringify(value));
+    return;
+  }
   qs.append(key, String(value));
 }
 

package/corpus/core/src/deploy/build.ts

@@ -1157,6 +1157,39 @@ function getSentryClientConfigScript() {
   );
 }
 
+function getPostHogClientConfigScript() {
+  // MUST stay consistent with resolvePublicPostHogConfig in
+  // server/posthog-config.ts (worker bundles a string copy; it can't import it).
+  // Never falls back to POSTHOG_API_KEY — that key can be a private one and
+  // this string is inlined into the public, CDN-cached HTML shell.
+  const env = globalThis.process?.env || {};
+  const posthogKey = firstNonEmpty(
+    env.POSTHOG_PUBLIC_KEY,
+    env.VITE_POSTHOG_KEY,
+    env.VITE_POSTHOG_PUBLIC_KEY,
+  );
+  if (!posthogKey) return null;
+  const posthogHost = (
+    firstNonEmpty(
+      env.POSTHOG_PUBLIC_HOST,
+      env.VITE_POSTHOG_HOST,
+      env.POSTHOG_HOST,
+    ) || "https://us.i.posthog.com"
+  ).replace(/\\/+$/, "");
+  const config = {
+    posthogKey,
+    posthogHost,
+    posthogErrorTracking:
+      (env.POSTHOG_ERROR_TRACKING || "").trim().toLowerCase() !== "false",
+  };
+  return (
+    '<script data-agent-native-posthog-config>' +
+    'window.__AGENT_NATIVE_CONFIG__=Object.assign({},window.__AGENT_NATIVE_CONFIG__,' +
+    JSON.stringify(config) +
+    ");</script>"
+  );
+}
+
 function getRealtimeClientConfigScript() {
   // MUST stay byte-for-byte consistent with resolveRealtimeClientConfig in
   // server/sentry-config.ts (worker bundles a string copy; it can't import it).
@@ -1330,7 +1363,11 @@ function applyImmutableAssetCacheHeaders(response, request) {
 
 async function rewriteMountedResponse(response, basePath, pathname, request) {
   const clientConfigScript =
-    [getSentryClientConfigScript(), getRealtimeClientConfigScript()]
+    [
+      getSentryClientConfigScript(),
+      getPostHogClientConfigScript(),
+      getRealtimeClientConfigScript(),
+    ]
       .filter(Boolean)
       .join("") || null;
   const headers = new Headers(response.headers);