@agent-native/core 0.133.2 → 0.134.0

package/dist/tracking/redaction.js

@@ -0,0 +1,85 @@
+/**
+ * Bounding and redaction helpers shared by every exception emitter.
+ *
+ * Kept free of `process.env` and Node built-ins so the browser bundle can use
+ * the same rules — an exception shaped one way on the server and another way
+ * in the client is how a leak ships in only one of them.
+ */
+export const MAX_MESSAGE_LENGTH = 1000;
+export const MAX_STACK_LENGTH = 8000;
+export const MAX_TAGS = 30;
+export const MAX_EXTRA_KEYS = 30;
+export const MAX_EXTRA_VALUE_LENGTH = 1000;
+const SECRET_RE = /\b(?:bearer|basic)\s+[^\s]+/gi;
+export const SECRET_KEY_RE = /(?:authorization|cookie|set[-_]?cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)/i;
+export function redact(value) {
+    return value
+        .replace(SECRET_RE, (match) => `${match.split(/\s+/, 1)[0]} <redacted>`)
+        .replace(/([A-Za-z0-9_$.-]*(?:authorization|cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)[A-Za-z0-9_$.-]*\s*[:=]\s*)([^\s,;}]+)/gi, "$1<redacted>");
+}
+export function boundedText(value, max) {
+    const text = typeof value === "string" ? value : String(value ?? "");
+    const safe = redact(text);
+    return safe.length > max ? safe.slice(0, max) : safe;
+}
+export function safeValue(value, depth = 2) {
+    if (value == null ||
+        typeof value === "boolean" ||
+        typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "string")
+        return boundedText(value, MAX_EXTRA_VALUE_LENGTH);
+    if (depth <= 0)
+        return boundedText(value, MAX_EXTRA_VALUE_LENGTH);
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map((item) => safeValue(item, depth - 1));
+    }
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (Object.keys(out).length >= MAX_EXTRA_KEYS)
+                break;
+            const safeKey = boundedText(key, 100);
+            out[safeKey] = SECRET_KEY_RE.test(safeKey)
+                ? "<redacted>"
+                : safeValue(child, depth - 1);
+        }
+        return out;
+    }
+    return boundedText(value, MAX_EXTRA_VALUE_LENGTH);
+}
+export function safeTags(tags) {
+    const out = {};
+    for (const [key, value] of Object.entries(tags ?? {})) {
+        if (Object.keys(out).length >= MAX_TAGS)
+            break;
+        // Skip, don't stop: callers build tag objects with optional entries
+        // (`{ ...tags, route, method, userAgent }`), so breaking on the first
+        // undefined dropped every tag after it depending on key order.
+        if (value == null)
+            continue;
+        const safeKey = boundedText(key, 100);
+        out[safeKey] = SECRET_KEY_RE.test(safeKey)
+            ? "<redacted>"
+            : boundedText(value, 200);
+    }
+    return out;
+}
+/** Split an unknown thrown value into bounded, redacted type/message/stack. */
+export function exceptionParts(error) {
+    if (error instanceof Error) {
+        return {
+            type: boundedText(error.name || "Error", 200),
+            message: boundedText(error.message || error.name || "Error", MAX_MESSAGE_LENGTH),
+            ...(error.stack
+                ? { stack: boundedText(error.stack, MAX_STACK_LENGTH) }
+                : {}),
+        };
+    }
+    return {
+        type: "Error",
+        message: boundedText(error, MAX_MESSAGE_LENGTH),
+    };
+}
+//# sourceMappingURL=redaction.js.map

package/dist/tracking/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../src/tracking/redaction.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bounding and redaction helpers shared by every exception emitter.\n *\n * Kept free of `process.env` and Node built-ins so the browser bundle can use\n * the same rules — an exception shaped one way on the server and another way\n * in the client is how a leak ships in only one of them.\n */\n\nexport const MAX_MESSAGE_LENGTH = 1000;\nexport const MAX_STACK_LENGTH = 8000;\nexport const MAX_TAGS = 30;\nexport const MAX_EXTRA_KEYS = 30;\nexport const MAX_EXTRA_VALUE_LENGTH = 1000;\n\nconst SECRET_RE = /\\b(?:bearer|basic)\\s+[^\\s]+/gi;\n\nexport const SECRET_KEY_RE =\n  /(?:authorization|cookie|set[-_]?cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)/i;\n\nexport function redact(value: string): string {\n  return value\n    .replace(SECRET_RE, (match) => `${match.split(/\\s+/, 1)[0]} <redacted>`)\n    .replace(\n      /([A-Za-z0-9_$.-]*(?:authorization|cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)[A-Za-z0-9_$.-]*\\s*[:=]\\s*)([^\\s,;}]+)/gi,\n      \"$1<redacted>\",\n    );\n}\n\nexport function boundedText(value: unknown, max: number): string {\n  const text = typeof value === \"string\" ? value : String(value ?? \"\");\n  const safe = redact(text);\n  return safe.length > max ? safe.slice(0, max) : safe;\n}\n\nexport function safeValue(value: unknown, depth = 2): unknown {\n  if (\n    value == null ||\n    typeof value === \"boolean\" ||\n    typeof value === \"number\"\n  ) {\n    return value;\n  }\n  if (typeof value === \"string\")\n    return boundedText(value, MAX_EXTRA_VALUE_LENGTH);\n  if (depth <= 0) return boundedText(value, MAX_EXTRA_VALUE_LENGTH);\n  if (Array.isArray(value)) {\n    return value.slice(0, 20).map((item) => safeValue(item, depth - 1));\n  }\n  if (typeof value === \"object\") {\n    const out: Record<string, unknown> = {};\n    for (const [key, child] of Object.entries(value)) {\n      if (Object.keys(out).length >= MAX_EXTRA_KEYS) break;\n      const safeKey = boundedText(key, 100);\n      out[safeKey] = SECRET_KEY_RE.test(safeKey)\n        ? \"<redacted>\"\n        : safeValue(child, depth - 1);\n    }\n    return out;\n  }\n  return boundedText(value, MAX_EXTRA_VALUE_LENGTH);\n}\n\nexport function safeTags(\n  tags: Record<string, string | undefined> | undefined,\n): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of Object.entries(tags ?? {})) {\n    if (Object.keys(out).length >= MAX_TAGS) break;\n    // Skip, don't stop: callers build tag objects with optional entries\n    // (`{ ...tags, route, method, userAgent }`), so breaking on the first\n    // undefined dropped every tag after it depending on key order.\n    if (value == null) continue;\n    const safeKey = boundedText(key, 100);\n    out[safeKey] = SECRET_KEY_RE.test(safeKey)\n      ? \"<redacted>\"\n      : boundedText(value, 200);\n  }\n  return out;\n}\n\nexport interface ExceptionParts {\n  type: string;\n  message: string;\n  stack?: string;\n}\n\n/** Split an unknown thrown value into bounded, redacted type/message/stack. */\nexport function exceptionParts(error: unknown): ExceptionParts {\n  if (error instanceof Error) {\n    return {\n      type: boundedText(error.name || \"Error\", 200),\n      message: boundedText(\n        error.message || error.name || \"Error\",\n        MAX_MESSAGE_LENGTH,\n      ),\n      ...(error.stack\n        ? { stack: boundedText(error.stack, MAX_STACK_LENGTH) }\n        : {}),\n    };\n  }\n  return {\n    type: \"Error\",\n    message: boundedText(error, MAX_MESSAGE_LENGTH),\n  };\n}\n"]}

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