@agent-native/core 0.133.2 → 0.134.0

package/src/tracking/providers.ts

@@ -13,6 +13,7 @@
  * automatically by the core-routes plugin).
  */
 
+import { reshapeTrackedExceptionProperties } from "./posthog-exception.js";
 import { registerTrackingProvider } from "./registry.js";
 import type { TrackingProvider, TrackingEvent } from "./types.js";
 
@@ -162,27 +163,61 @@ function isPostHogAiObservabilityEvent(eventName: string): boolean {
   return eventName.startsWith("$ai_");
 }
 
-function createPostHogProvider(apiKey: string, host: string): TrackingProvider {
+/**
+ * `$ai_*` and `$exception` are ingested through PostHog's dedicated endpoint
+ * rather than `/capture/`, and `$exception` additionally has to carry
+ * `$exception_list` — the framework's own `captureException()` emits camelCase
+ * fields that PostHog would otherwise render as an empty, ungroupable issue.
+ */
+function createPostHogProvider(
+  apiKey: string,
+  host: string,
+  errorTracking: boolean,
+): TrackingProvider {
+  const sendToEventsEndpoint = (
+    event: TrackingEvent,
+    properties: Record<string, unknown> | undefined,
+    distinctId: string,
+  ): void => {
+    enqueue(
+      `${host}/i/v0/e/`,
+      JSON.stringify({
+        api_key: apiKey,
+        event: event.name,
+        properties: {
+          distinct_id: distinctId,
+          ...properties,
+          timestamp: event.timestamp,
+        },
+      }),
+    );
+  };
+
   return {
     name: "posthog",
     track(event: TrackingEvent) {
       const distinctId = event.userId || "anonymous";
       if (isPostHogAiObservabilityEvent(event.name)) {
-        enqueue(
-          `${host}/i/v0/e/`,
-          JSON.stringify({
-            api_key: apiKey,
-            event: event.name,
-            properties: {
-              distinct_id: distinctId,
-              ...event.properties,
-              timestamp: event.timestamp,
-            },
-          }),
-        );
+        sendToEventsEndpoint(event, event.properties, distinctId);
         return;
       }
 
+      if (event.name === "$exception") {
+        // `POSTHOG_ERROR_TRACKING=false` keeps product analytics flowing while
+        // another backend owns crashes. Drop rather than downgrade to
+        // `/capture/`: a malformed exception is what this branch exists to
+        // prevent.
+        if (!errorTracking) return;
+        const reshaped = reshapeTrackedExceptionProperties(event.properties);
+        if (reshaped) {
+          sendToEventsEndpoint(event, reshaped, distinctId);
+          return;
+        }
+        // No recognizable exception fields. Fall through to `/capture/` so the
+        // event is still recorded as-is rather than becoming an issue with
+        // nothing in it.
+      }
+
       enqueue(
         `${host}/capture/`,
         JSON.stringify({
@@ -213,6 +248,42 @@ function createPostHogProvider(apiKey: string, host: string): TrackingProvider {
   };
 }
 
+/**
+ * Send one event to PostHog only, bypassing the provider fan-out.
+ *
+ * For payloads whose *shape* is PostHog-specific and whose *content* other
+ * backends must not receive. `track()` broadcasts to every configured provider,
+ * so a PostHog-only integration (e.g. enabling a survey id) would otherwise
+ * start exporting that integration's content — including user-authored text —
+ * to Mixpanel, Amplitude, webhooks, and Agent Native Analytics as a side
+ * effect nobody opted into.
+ *
+ * Returns `false` when PostHog is not configured, so callers can tell "not
+ * sent" from "sent".
+ */
+export function sendPostHogEvent(
+  name: string,
+  properties: Record<string, unknown>,
+  distinctId: string,
+): boolean {
+  const apiKey = process.env.POSTHOG_API_KEY;
+  if (!apiKey) return false;
+  const host = (process.env.POSTHOG_HOST || POSTHOG_DEFAULT_HOST).replace(
+    /\/+$/,
+    "",
+  );
+  enqueue(
+    `${host}/capture/`,
+    JSON.stringify({
+      api_key: apiKey,
+      event: name,
+      distinct_id: distinctId,
+      properties: { ...properties, timestamp: new Date().toISOString() },
+    }),
+  );
+  return true;
+}
+
 // ─── Mixpanel ──────────────────────────────────────────────────────────────
 
 function createMixpanelProvider(token: string): TrackingProvider {
@@ -383,7 +454,13 @@ export function registerBuiltinProviders(): void {
       /\/+$/,
       "",
     );
-    registerTrackingProvider(createPostHogProvider(posthogKey, host));
+    registerTrackingProvider(
+      createPostHogProvider(
+        posthogKey,
+        host,
+        process.env.POSTHOG_ERROR_TRACKING?.trim().toLowerCase() !== "false",
+      ),
+    );
   }
 
   const mixpanelToken = process.env.MIXPANEL_TOKEN;

package/src/tracking/redaction.ts

@@ -0,0 +1,105 @@
+/**
+ * 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: string): string {
+  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: unknown, max: number): string {
+  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: unknown, depth = 2): unknown {
+  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: Record<string, unknown> = {};
+    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: Record<string, string | undefined> | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  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;
+}
+
+export interface ExceptionParts {
+  type: string;
+  message: string;
+  stack?: string;
+}
+
+/** Split an unknown thrown value into bounded, redacted type/message/stack. */
+export function exceptionParts(error: unknown): ExceptionParts {
+  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),
+  };
+}