@agent-native/core 0.133.2 → 0.134.0

package/corpus/core/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -232,6 +232,7 @@ All tables are dialect-agnostic (SQLite + Postgres) and strictly additive.
 | `packages/core/src/observability/types.ts` | Shared type definitions |
 | `packages/core/src/observability/store.ts` | SQL tables + CRUD |
 | `packages/core/src/observability/traces.ts` | Auto-instrumentation |
+| `packages/core/src/observability/posthog-ai.ts` | `$ai_trace` / `$ai_span` / `survey sent` emission, content bounding, `$ai_error` |
 | `packages/core/src/observability/feedback.ts` | Feedback + Frustration Index |
 | `packages/core/src/observability/evals.ts` | Eval engine (3 layers) |
 | `packages/core/src/observability/experiments.ts` | A/B testing system |
@@ -272,16 +273,17 @@ The loop emits `agent.run` (with `agent.run_id`, `agent.thread_id`, `agent.user_
 
 ## Tracking Bridge
 
-Instrumented agent loops also emit one server-side tracking event per completed
-LLM generation:
-
-- Event name: `$ai_generation`
-- Provider path: `track()` from `@agent-native/core/tracking`, so configured
-  PostHog, Agent Native Analytics, Mixpanel, Amplitude, and webhook providers
-  receive it through the same best-effort fan-out as other tracking events.
-- PostHog shape: uses AI Observability properties such as `$ai_trace_id`,
-  `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`,
-  `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and `$ai_is_error`.
+Instrumented agent loops emit server-side tracking events for every run through
+`track()` from `@agent-native/core/tracking`, so configured PostHog, Agent Native
+Analytics, Mixpanel, Amplitude, and webhook providers receive them through the
+same best-effort fan-out as other tracking events.
+
+- Events: `$ai_trace` per run, `$ai_span` per tool call, and `$ai_generation`
+  per model call. Every node carries the run id as `$ai_trace_id` and links
+  upward through `$ai_parent_id` so a backend can rebuild the tree.
+  `$ai_session_id` is the thread; the browser session is separate and ships as
+  `$session_id`, read from `X-Agent-Native-Session-Id` via
+  `RequestContext.browserSessionId`. Emission lives in `posthog-ai.ts`.
 - Agent Native Analytics shape: the same event lands in `analytics_events` with
   mirrored query-friendly properties such as `run_id`, `thread_id`,
   `cost_cents_x100`, `duration_ms`, `tool_calls`, `successful_tools`,
@@ -293,6 +295,30 @@ LLM generation:
   `parent_run_id` when available. `parent_turn_id` is separate because one
   logical turn may span multiple concrete runs.
 
+Constraints that are not visible from the emit site:
+
+- **One generation per run, not per model round-trip.** The engine layer reports
+  aggregate usage through `onUsage` and exposes no per-step hook, so a multi-step
+  run collapses into a single generation carrying the whole message list.
+  Per-round-trip latency and intermediate turns are unavailable without a new
+  seam in `ai-sdk-engine.ts` / `builder-engine.ts`. Do not describe the current
+  output as per-step.
+- **Disabled capture omits the field rather than sending an empty one.** An
+  empty array is indistinguishable from a run that genuinely had no messages.
+  Truncated content is marked, and a run over the span cap stamps
+  `$ai_spans_dropped` — a truncated run must not read as a complete one.
+- **The structural tool-call list ships even when content capture is off.**
+  Backends derive their tool tags from tool-call blocks inside the output
+  choices and from nothing else, so tool names (without arguments) are always
+  emitted. The parallel first-party `tools` array stays because the dashboards
+  read it; that duplication is deliberate, not cleanup.
+- **Only thumbs carry `sentiment`.** All four feedback types are reported, but a
+  category follow-up to a thumbs-down is detail about the same vote — counting
+  it again inflates the metric.
+- **Never invent an external id to make an integration light up.** Survey-based
+  feedback is emitted only when a real survey id is configured, and nothing is
+  sent otherwise.
+
 Do not build a separate LLM-observability ingestion API unless there is a clear
 reason the tracking provider registry cannot express the use case. Keep prompt,
 tool input, and model output content out of tracking by default; use the existing

package/corpus/core/src/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -79,7 +79,7 @@ Set the env var and the provider auto-registers at startup. No SDK dependencies
 
 | Provider               | Env vars                                                                                                                                           |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PostHog                | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`)                                                    |
+| PostHog                | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`), `POSTHOG_ERROR_TRACKING=false` (optional opt-out) |
 | Mixpanel               | `MIXPANEL_TOKEN`                                                                                                                                   |
 | Amplitude              | `AMPLITUDE_API_KEY`                                                                                                                                |
 | Agent Native Analytics | `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` (server), `AGENT_NATIVE_ANALYTICS_ENDPOINT` (optional, defaults to `https://analytics.agent-native.com/track`) |
@@ -89,6 +89,56 @@ Multiple providers can be active simultaneously. All receive every event.
 
 Browser-side `trackEvent()` also forwards to Agent Native Analytics when `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` is present. Use `VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT` to override the default browser endpoint. The built-in Agent Native Analytics sender is quiet on localhost/local dev by default; set `AGENT_NATIVE_ANALYTICS_ALLOW_LOCALHOST=true` only for an intentional local ingestion test.
 
+## Error Capture
+
+Exceptions fan out through `server/capture-error.ts` to every registered
+backend — Sentry, PostHog, and the tracking providers — from one `captureError()`
+call. Backends are additive: configuring a second one does not displace the
+first, and no backend is required for the others to work.
+
+Emit through `captureError()` / `captureException()`. Never hand-roll a
+`track("$exception", …)`: each backend needs its own payload shape and the
+providers build it.
+
+- **Provider-agnostic wiring must not live in a provider plugin.** The Nitro
+  `error` hook is in `core-routes-plugin.ts`, not `sentry-plugin.ts`, because
+  that plugin returns early when no `SENTRY_DSN` is set — hooking route errors
+  there meant an app on any other backend silently reported none.
+- **Every backend applies `server/error-noise-filter.ts`.** It holds
+  production-tuned drop rules (expected 4xx, access-control rejections, Lambda
+  freeze/thaw `socket hang up`). A backend that skips it receives a firehose;
+  the `socket hang up` rule alone is ~10k events/day.
+- **A backend can accept a malformed payload and still show a count.** PostHog
+  ingested the framework's camelCase `$exception` for a long time and rendered
+  empty, ungroupable issues — which reads as coverage, not as breakage. When
+  adding or changing a backend, check what an event looks like in its UI, not
+  just that the request returned 200.
+- **Attribute the error.** Without a user id, server exceptions land under
+  `anonymous` and split one person in two against their browser events. Pass
+  `aiTraceId` for anything inside an agent run so the issue and the LLM trace
+  resolve to each other.
+
+Symbolication is per-backend and not automatic: the framework uploads no source
+maps to PostHog, so minified browser stacks stay minified there. Known gap, not
+a bug to re-diagnose.
+
+### Browser keys and the SSR shell
+
+Public keys (`POSTHOG_PUBLIC_KEY`, the Sentry client DSN) ship inside the
+CDN-cached SSR shell — publishable and identical for every visitor. Server keys
+never do, and are never a fallback for a public one: `POSTHOG_API_KEY` may be a
+private key and this value lands in public HTML.
+
+Browser errors post directly to the backend rather than through
+`/_agent-native/track`, because that route requires a resolved session and
+relaying would drop every signed-out crash.
+
+When adding a client config field, update **both** `server/posthog-config.ts`
+and the mirrored worker emitter in `deploy/build.ts` — the worker bundles a
+string copy and cannot import the module, so a one-sided edit drops the config
+silently in deployed builds. `posthog-config.spec.ts` pins the two outputs
+together.
+
 ## Default Baseline Events
 
 Template roots call `configureTracking()` once during app startup. That installs default browser pageview tracking for hosted apps:
@@ -199,6 +249,10 @@ interface TrackingEvent {
 | `packages/core/src/tracking/registry.ts`  | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()`                                            |
 | `packages/core/src/tracking/providers.ts` | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
 | `packages/core/src/tracking/types.ts`     | `TrackingEvent` and `TrackingProvider` interfaces                                                                   |
+| `packages/core/src/tracking/posthog-exception.ts` | `$exception_list` builder + stack-frame parser (isomorphic: server and browser)                             |
+| `packages/core/src/tracking/redaction.ts` | Shared bounding/redaction helpers used by every exception emitter                                                   |
+| `packages/core/src/server/error-noise-filter.ts` | Provider-agnostic drop rules, applied by both Sentry `beforeSend` and the route error hook                   |
+| `packages/core/src/server/posthog-config.ts` | Public browser PostHog config (mirrored in `deploy/build.ts`)                                                    |
 
 ## Related Skills
 

package/corpus/core/src/tracking/error-capture.ts

@@ -1,5 +1,11 @@
 import { trackingIdentityProperties } from "../observability/tracking-identity.js";
 import type { CaptureErrorContext } from "../server/capture-error.js";
+import {
+  boundedText,
+  exceptionParts,
+  safeTags,
+  safeValue,
+} from "./redaction.js";
 import { track } from "./registry.js";
 
 export type TrackingExceptionLevel =
@@ -17,95 +23,13 @@ export interface TrackingExceptionContext extends CaptureErrorContext {
   environment?: string;
   runtime?: "node" | "cli";
   source?: "server" | "cli";
-}
-
-const MAX_MESSAGE_LENGTH = 1000;
-const MAX_STACK_LENGTH = 8000;
-const MAX_TAGS = 30;
-const MAX_EXTRA_KEYS = 30;
-const MAX_EXTRA_VALUE_LENGTH = 1000;
-const SECRET_RE = /\b(?:bearer|basic)\s+[^\s]+/gi;
-const SECRET_KEY_RE =
-  /(?:authorization|cookie|set[-_]?cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)/i;
-
-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>",
-    );
-}
-
-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;
-}
-
-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);
-}
-
-function exceptionParts(error: unknown): {
-  type: string;
-  message: string;
-  stack?: string;
-} {
-  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),
-  };
-}
-
-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 || value == null) break;
-    const safeKey = boundedText(key, 100);
-    out[safeKey] = SECRET_KEY_RE.test(safeKey)
-      ? "<redacted>"
-      : boundedText(value, 200);
-  }
-  return out;
+  /**
+   * Who the exception is attributed to. Without it every server exception is
+   * ingested as `anonymous`, which splits one person into two in any backend
+   * that also receives their browser events.
+   */
+  userId?: string;
+  orgId?: string;
 }
 
 /** Emit a bounded, redacted Node/CLI exception through first-party tracking. */
@@ -125,26 +49,37 @@ export function captureException(
       ...context.extra,
       ...(context.contexts ? { contexts: context.contexts } : {}),
     });
-    track("$exception", {
-      ...trackingIdentityProperties(),
-      exceptionType: parts.type,
-      exceptionMessage: parts.message,
-      ...(parts.stack ? { exceptionStack: parts.stack } : {}),
-      handled: context.handled ?? true,
-      level: context.level ?? "error",
-      occurredAt: new Date().toISOString(),
-      runtime: context.runtime ?? "node",
-      source: context.source ?? "server",
-      ...(context.route ? { url: boundedText(context.route, 500) } : {}),
-      ...(context.release
-        ? { release: boundedText(context.release, 200) }
-        : {}),
-      ...(context.environment
-        ? { environment: boundedText(context.environment, 100) }
-        : {}),
-      ...(Object.keys(tags).length ? { exceptionTags: tags } : {}),
-      ...(extra && typeof extra === "object" ? { exceptionExtra: extra } : {}),
-    });
+    track(
+      "$exception",
+      {
+        ...trackingIdentityProperties(),
+        exceptionType: parts.type,
+        exceptionMessage: parts.message,
+        ...(parts.stack ? { exceptionStack: parts.stack } : {}),
+        handled: context.handled ?? true,
+        level: context.level ?? "error",
+        occurredAt: new Date().toISOString(),
+        runtime: context.runtime ?? "node",
+        source: context.source ?? "server",
+        ...(context.route ? { url: boundedText(context.route, 500) } : {}),
+        ...(context.release
+          ? { release: boundedText(context.release, 200) }
+          : {}),
+        ...(context.environment
+          ? { environment: boundedText(context.environment, 100) }
+          : {}),
+        ...(context.orgId ? { orgId: boundedText(context.orgId, 200) } : {}),
+        // Top-level so error tracking and LLM analytics join on it.
+        ...(context.aiTraceId
+          ? { $ai_trace_id: boundedText(context.aiTraceId, 200) }
+          : {}),
+        ...(Object.keys(tags).length ? { exceptionTags: tags } : {}),
+        ...(extra && typeof extra === "object"
+          ? { exceptionExtra: extra }
+          : {}),
+      },
+      context.userId ? { userId: context.userId } : undefined,
+    );
   } catch {
     // Error reporting must never mask the original failure.
   }

package/corpus/core/src/tracking/index.ts

@@ -12,4 +12,15 @@ export {
   type TrackingExceptionContext,
   type TrackingExceptionLevel,
 } from "./error-capture.js";
+export {
+  errorToPostHogExceptionProperties,
+  parseStackFrames,
+  reshapeTrackedExceptionProperties,
+  toPostHogExceptionProperties,
+  type PostHogExceptionEntry,
+  type PostHogExceptionInput,
+  type PostHogExceptionLevel,
+  type PostHogExceptionProperties,
+  type PostHogStackFrame,
+} from "./posthog-exception.js";
 export type { TrackingProvider, TrackingEvent } from "./types.js";

package/corpus/core/src/tracking/posthog-exception.ts

@@ -0,0 +1,305 @@
+/**
+ * Build PostHog error-tracking payloads from a raw JS error or from the
+ * camelCase exception properties the framework's own `captureException()`
+ * emits.
+ *
+ * PostHog's error tracking only groups and renders an issue when the event
+ * carries `$exception_list` with per-frame stack data. An event named
+ * `$exception` without it is ingested and displayed as an empty, ungroupable
+ * issue — which is worse than no event, because the count looks like coverage.
+ *
+ * Frame parsing follows posthog-js (itself derived from Sentry's TraceKit
+ * fork), because PostHog's ingestion is written against that shape:
+ *   - `Error: …` header lines are skipped, not parsed as frames
+ *   - lines over 1 KB are skipped (the regexes backtrack)
+ *   - frames are capped at 50 and reversed to oldest-call-first
+ *   - an unresolvable function name is `?`, never empty
+ *
+ * Runs unchanged in Node and the browser: no `process`, no Node built-ins.
+ *
+ * @see https://posthog.com/docs/error-tracking/installation/manual
+ */
+
+import {
+  MAX_MESSAGE_LENGTH,
+  MAX_STACK_LENGTH,
+  boundedText,
+  exceptionParts,
+} from "./redaction.js";
+
+/** Matches posthog-js's `UNKNOWN_FUNCTION`. */
+const UNKNOWN_FUNCTION = "?";
+const STACKTRACE_FRAME_LIMIT = 50;
+const MAX_STACK_LINE_LENGTH = 1024;
+
+const ERROR_HEADER_RE = /\S*Error: /;
+const WEBPACK_ERROR_RE = /\(error: (.*)\)/;
+
+// "    at fn (file:1:2)" / "    at async Foo.bar (/app/x.js:2:3)" / "    at /app/x.js:1:2"
+const V8_FRAME_RE =
+  /^\s*at (?:async )?(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+)|([^)]+))\)?\s*$/;
+// "fn@https://example.com/s.js:1:2" / "@https://example.com/s.js:1:2"
+const GECKO_FRAME_RE = /^\s*(.*?)@(.+?)(?::(\d+))?(?::(\d+))?\s*$/;
+
+export type PostHogExceptionLevel =
+  | "fatal"
+  | "error"
+  | "warning"
+  | "info"
+  | "debug";
+
+export interface PostHogStackFrame {
+  /**
+   * Always `"custom"`. PostHog reserves the language-specific platforms for
+   * frames it will try to symbolicate against uploaded source maps; we upload
+   * none, so claiming one would render every minified frame as a failed
+   * resolution rather than as the raw frame it is.
+   */
+  platform: "custom";
+  lang: string;
+  function: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+  in_app: boolean;
+  resolved: boolean;
+}
+
+export interface PostHogExceptionEntry {
+  type: string;
+  value: string;
+  mechanism: { handled: boolean; synthetic: boolean; type?: string };
+  stacktrace?: { type: "raw"; frames: PostHogStackFrame[] };
+}
+
+export interface PostHogExceptionProperties {
+  $exception_list: PostHogExceptionEntry[];
+  $exception_level: PostHogExceptionLevel;
+  $exception_fingerprint?: string;
+  [key: string]: unknown;
+}
+
+export interface PostHogExceptionInput {
+  /** Error class name, e.g. `TypeError`. */
+  type: string;
+  /** Error message. */
+  value: string;
+  /** Raw `error.stack` string, when available. */
+  stack?: string;
+  /** `false` for errors that crashed the request/page rather than being caught. */
+  handled?: boolean;
+  /** `true` when the framework synthesized the error from a non-Error throw. */
+  synthetic?: boolean;
+  /** Mechanism label, e.g. `onunhandledrejection`, `nitro.error`. */
+  mechanismType?: string;
+  level?: PostHogExceptionLevel;
+  /** Overrides PostHog's default grouping. */
+  fingerprint?: string;
+  /** Frame language tag. Defaults to `javascript`. */
+  lang?: string;
+}
+
+function isInAppFrame(filename: string | undefined): boolean {
+  if (!filename) return true;
+  return (
+    !filename.startsWith("node:") &&
+    !filename.includes("node_modules") &&
+    !filename.includes("/internal/") &&
+    filename !== "native"
+  );
+}
+
+function makeFrame(
+  lang: string,
+  fn: string,
+  filename: string | undefined,
+  lineno: number | undefined,
+  colno: number | undefined,
+): PostHogStackFrame {
+  const name = !fn || fn === "<anonymous>" ? UNKNOWN_FUNCTION : fn;
+  return {
+    platform: "custom",
+    lang,
+    function: name,
+    ...(filename ? { filename } : {}),
+    ...(lineno !== undefined && Number.isFinite(lineno) ? { lineno } : {}),
+    ...(colno !== undefined && Number.isFinite(colno) ? { colno } : {}),
+    in_app: isInAppFrame(filename),
+    // Never `true`: we ship no source maps to PostHog, so a minified browser
+    // frame is exactly as informative as it looks. Claiming it is resolved
+    // would present a mangled name as the real one.
+    resolved: false,
+  };
+}
+
+function parseFrameLine(
+  line: string,
+  lang: string,
+): PostHogStackFrame | undefined {
+  const v8 = V8_FRAME_RE.exec(line);
+  if (v8) {
+    const [, fn, file, lineNo, colNo, bare] = v8;
+    const filename = (file ?? bare)?.replace(/^file:\/\//, "");
+    return makeFrame(
+      lang,
+      fn ?? UNKNOWN_FUNCTION,
+      filename,
+      lineNo ? Number(lineNo) : undefined,
+      colNo ? Number(colNo) : undefined,
+    );
+  }
+
+  const gecko = GECKO_FRAME_RE.exec(line);
+  if (gecko) {
+    const [, fn, file, lineNo, colNo] = gecko;
+    return makeFrame(
+      lang,
+      fn || UNKNOWN_FUNCTION,
+      file,
+      lineNo ? Number(lineNo) : undefined,
+      colNo ? Number(colNo) : undefined,
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Parse a `error.stack` string into PostHog stack frames, oldest call first.
+ *
+ * Returns an empty array when nothing parsed. Callers must treat that as
+ * "no frames" and omit `stacktrace` entirely rather than sending an empty
+ * frame list — PostHog renders the latter as a stack that exists and is empty.
+ */
+export function parseStackFrames(
+  stack: string | undefined,
+  lang = "javascript",
+): PostHogStackFrame[] {
+  if (!stack) return [];
+  const frames: PostHogStackFrame[] = [];
+
+  for (const rawLine of stack.split("\n")) {
+    if (rawLine.length > MAX_STACK_LINE_LENGTH) continue;
+    const line = WEBPACK_ERROR_RE.test(rawLine)
+      ? rawLine.replace(WEBPACK_ERROR_RE, "$1")
+      : rawLine;
+    if (ERROR_HEADER_RE.test(line)) continue;
+
+    const frame = parseFrameLine(line, lang);
+    if (frame) frames.push(frame);
+    if (frames.length >= STACKTRACE_FRAME_LIMIT) break;
+  }
+
+  frames.reverse();
+  return frames;
+}
+
+/**
+ * Build the `$exception_*` properties for a PostHog error-tracking event.
+ *
+ * The caller merges these into the event properties alongside `distinct_id`
+ * and any app dimensions.
+ */
+export function toPostHogExceptionProperties(
+  input: PostHogExceptionInput,
+): PostHogExceptionProperties {
+  const lang = input.lang ?? "javascript";
+  const frames = parseStackFrames(input.stack, lang);
+  const entry: PostHogExceptionEntry = {
+    type: boundedText(input.type || "Error", 200),
+    value: boundedText(
+      input.value || input.type || "Error",
+      MAX_MESSAGE_LENGTH,
+    ),
+    mechanism: {
+      handled: input.handled ?? true,
+      synthetic: input.synthetic ?? false,
+      ...(input.mechanismType
+        ? { type: boundedText(input.mechanismType, 100) }
+        : {}),
+    },
+    ...(frames.length ? { stacktrace: { type: "raw" as const, frames } } : {}),
+  };
+
+  return {
+    $exception_list: [entry],
+    $exception_level: input.level ?? "error",
+    ...(input.fingerprint
+      ? { $exception_fingerprint: boundedText(input.fingerprint, 200) }
+      : {}),
+  };
+}
+
+/** Build `$exception_*` properties directly from a thrown value. */
+export function errorToPostHogExceptionProperties(
+  error: unknown,
+  options: Omit<PostHogExceptionInput, "type" | "value" | "stack"> = {},
+): PostHogExceptionProperties {
+  const parts = exceptionParts(error);
+  return toPostHogExceptionProperties({
+    ...options,
+    type: parts.type,
+    value: parts.message,
+    stack: parts.stack,
+    synthetic: options.synthetic ?? !(error instanceof Error),
+  });
+}
+
+/**
+ * Reshape the camelCase properties emitted by `tracking/error-capture.ts` into
+ * PostHog's `$exception_list` form.
+ *
+ * Returns `undefined` when the event carries no recognizable exception fields,
+ * so the caller can pass it through untouched instead of inventing an empty
+ * issue out of an unrelated event that happens to be named `$exception`.
+ */
+export function reshapeTrackedExceptionProperties(
+  properties: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!properties) return undefined;
+  // Already in PostHog form (e.g. relayed from the browser) — leave it alone.
+  if (Array.isArray(properties.$exception_list)) return properties;
+
+  const type = properties.exceptionType;
+  const message = properties.exceptionMessage;
+  if (typeof type !== "string" && typeof message !== "string") {
+    return undefined;
+  }
+
+  const stack =
+    typeof properties.exceptionStack === "string"
+      ? properties.exceptionStack.slice(0, MAX_STACK_LENGTH)
+      : undefined;
+  const level = properties.level;
+
+  const {
+    exceptionType: _type,
+    exceptionMessage: _message,
+    exceptionStack: _stack,
+    handled: _handled,
+    level: _level,
+    ...rest
+  } = properties;
+
+  return {
+    ...rest,
+    ...toPostHogExceptionProperties({
+      type: typeof type === "string" ? type : "Error",
+      value: typeof message === "string" ? message : "Error",
+      stack,
+      handled:
+        typeof properties.handled === "boolean" ? properties.handled : true,
+      level: isExceptionLevel(level) ? level : "error",
+    }),
+  };
+}
+
+function isExceptionLevel(value: unknown): value is PostHogExceptionLevel {
+  return (
+    value === "fatal" ||
+    value === "error" ||
+    value === "warning" ||
+    value === "info" ||
+    value === "debug"
+  );
+}