@agent-native/core 0.69.0 → 0.70.0

package/corpus/core/src/client/settings/useBuilderStatus.ts

@@ -195,6 +195,8 @@ const BUILDER_STATE_PARAM = "_an_state";
 const BUILDER_SIGNUP_SOURCE_PARAM = "signupSource";
 const BUILDER_AGENT_NATIVE_FLOW_PARAM = "agentNativeFlow";
 const BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM = "agentNativeConnectSource";
+const BUILDER_AGENT_NATIVE_APP_PARAM = "agentNativeApp";
+const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate";
 const BUILDER_SIGNUP_SOURCE = "agent-native";
 const STATUS_CONNECT_URL_TTL_MS = 9 * 60 * 1000;
 
@@ -224,42 +226,102 @@ function inferBuilderConnectTrackingFlow(source: string | undefined): string {
   return "connect_llm";
 }
 
+function normalizeTrackingSlug(
+  value: string | null | undefined,
+): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  const unscoped = trimmed.startsWith("@")
+    ? (trimmed.split("/").pop() ?? trimmed)
+    : trimmed;
+  const slug = unscoped
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || null;
+}
+
+function inferBuilderConnectTrackingIdentity(options: {
+  app?: string;
+  template?: string;
+}): { app: string | null; template: string | null } {
+  const env = (import.meta.env as Record<string, string | undefined>) ?? {};
+  const app =
+    normalizeTrackingSlug(options.app) ??
+    normalizeTrackingSlug(env.VITE_AGENT_NATIVE_APP) ??
+    (typeof window !== "undefined"
+      ? normalizeTrackingSlug(window.location.hostname.split(".")[0])
+      : null);
+  const template =
+    normalizeTrackingSlug(options.template) ??
+    normalizeTrackingSlug(env.VITE_AGENT_NATIVE_TEMPLATE) ??
+    normalizeTrackingSlug(env.VITE_APP_TEMPLATE) ??
+    (app?.startsWith("agent-native-")
+      ? normalizeTrackingSlug(app.slice("agent-native-".length))
+      : app && app !== "localhost"
+        ? app
+        : null);
+
+  return { app, template };
+}
+
+function applyBuilderConnectTrackingParams(
+  params: URLSearchParams,
+  tracking: {
+    source?: string | null;
+    flow: string;
+    app?: string | null;
+    template?: string | null;
+  },
+) {
+  params.set(BUILDER_SIGNUP_SOURCE_PARAM, BUILDER_SIGNUP_SOURCE);
+  params.set(BUILDER_AGENT_NATIVE_FLOW_PARAM, tracking.flow);
+  if (tracking.source) {
+    params.set(BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM, tracking.source);
+  }
+  if (tracking.app) {
+    params.set(BUILDER_AGENT_NATIVE_APP_PARAM, tracking.app);
+  }
+  if (tracking.template) {
+    params.set(BUILDER_AGENT_NATIVE_TEMPLATE_PARAM, tracking.template);
+  }
+}
+
 export function withBuilderConnectTrackingParams(
   url: string,
-  options: { source?: string; flow?: string } = {},
+  options: {
+    source?: string;
+    flow?: string;
+    app?: string;
+    template?: string;
+  } = {},
 ): string {
   const source = cleanTrackingParam(options.source);
   const flow =
     cleanTrackingParam(options.flow) ??
     inferBuilderConnectTrackingFlow(source ?? undefined);
+  const { app, template } = inferBuilderConnectTrackingIdentity(options);
   const origin =
     typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
   try {
     const parsed = new URL(url, origin);
-    parsed.searchParams.set(BUILDER_SIGNUP_SOURCE_PARAM, BUILDER_SIGNUP_SOURCE);
-    parsed.searchParams.set(BUILDER_AGENT_NATIVE_FLOW_PARAM, flow);
-    if (source) {
-      parsed.searchParams.set(
-        BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM,
-        source,
-      );
-    }
+    applyBuilderConnectTrackingParams(parsed.searchParams, {
+      source,
+      flow,
+      app,
+      template,
+    });
 
     const redirectUrl = parsed.searchParams.get("redirect_url");
     if (redirectUrl) {
       const parsedRedirect = new URL(redirectUrl);
-      parsedRedirect.searchParams.set(
-        BUILDER_SIGNUP_SOURCE_PARAM,
-        BUILDER_SIGNUP_SOURCE,
-      );
-      parsedRedirect.searchParams.set(BUILDER_AGENT_NATIVE_FLOW_PARAM, flow);
-      if (source) {
-        parsedRedirect.searchParams.set(
-          BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM,
-          source,
-        );
-      }
+      applyBuilderConnectTrackingParams(parsedRedirect.searchParams, {
+        source,
+        flow,
+        app,
+        template,
+      });
       parsed.searchParams.set("redirect_url", parsedRedirect.toString());
     }
 

package/corpus/core/src/mcp/build-server.ts

@@ -708,7 +708,7 @@ function safeUiSegment(value: string | undefined, fallback: string): string {
 
 // ChatGPT and Claude cache MCP App resource HTML by `ui://` URI. Bump this
 // when the shared shell changes in a way that must invalidate host caches.
-const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v43";
+const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v45";
 
 function legacyDefaultMcpAppUri(config: MCPConfig, actionName: string): string {
   const app = safeUiSegment(config.appId ?? config.name, "agent-native");

package/corpus/core/src/mcp/embed-app.ts

@@ -455,6 +455,49 @@ export function embedApp(
       };
     }
 
+    function externalOpenUrlForAppUrl(appUrl) {
+      if (openUrl) return openUrl;
+      try {
+        const url = new URL(appUrl.href);
+        url.searchParams.delete("embedded");
+        url.searchParams.delete("__an_embed_token");
+        url.searchParams.delete(chatBridgeParam);
+        return url.toString();
+      } catch (_err) {
+        return "";
+      }
+    }
+
+    function installExternalOpenControl(appUrl) {
+      const href = externalOpenUrlForAppUrl(appUrl);
+      if (!href || !document.body || document.getElementById("agent-native-external-open-control")) {
+        return;
+      }
+      const host = document.createElement("div");
+      host.id = "agent-native-external-open-control";
+      host.style.position = "fixed";
+      host.style.top = "10px";
+      host.style.right = "10px";
+      host.style.zIndex = "2147483647";
+      host.style.pointerEvents = "auto";
+      const root = host.attachShadow ? host.attachShadow({ mode: "open" }) : host;
+      root.innerHTML =
+        '<style>' +
+          ':host{all:initial;}' +
+          'button{box-sizing:border-box;min-height:30px;border:1px solid color-mix(in srgb, CanvasText 18%, Canvas);border-radius:7px;background:Canvas;color:CanvasText;box-shadow:0 6px 22px color-mix(in srgb, CanvasText 14%, transparent);cursor:pointer;font:700 12px ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;padding:0 10px;white-space:nowrap;}' +
+          'button:hover{background:color-mix(in srgb, CanvasText 6%, Canvas);}' +
+        '</style>' +
+        '<button type="button">Open in new tab</button>';
+      const button = root.querySelector("button");
+      if (button) {
+        button.addEventListener("click", (event) => {
+          event.preventDefault();
+          void openHostLink({ url: href });
+        });
+      }
+      document.body.appendChild(host);
+    }
+
     function installReactRefreshPreambleFallback() {
       window.__vite_plugin_react_preamble_installed__ = true;
       if (typeof window.$RefreshReg$ !== "function") {
@@ -795,6 +838,7 @@ export function embedApp(
       base.href = config.baseHref;
       document.head.prepend(base);
       importChildren(parsed.body, document.body);
+      installExternalOpenControl(appUrl);
       for (const script of scripts) {
         if (isRunnableClassicScript(script)) runClassicScript(script);
       }
@@ -987,6 +1031,42 @@ export function embedApp(
       }
     }
 
+    function renderAppLaunchError(message) {
+      clearFrameReadyTimer();
+      clearFrameLoadTimer();
+      appFrame = null;
+      const fallbackCopy = openUrl
+        ? "The inline MCP app could not load in this chat host. You can open the same app route in a new tab or retry the inline load."
+        : "The inline MCP app could not load in this chat host.";
+      const copyHtml = message
+        ? '<div>' + esc(message) + '</div><div>' + esc(fallbackCopy) + '</div>'
+        : esc(fallbackCopy);
+      stage.innerHTML =
+        '<div class="fallback">' +
+          '<div class="fallback-title">App did not load</div>' +
+          '<div class="fallback-copy">' + copyHtml + '</div>' +
+          '<div class="fallback-actions">' +
+            '<button type="button" data-fallback-open>Open in new tab</button>' +
+            '<button type="button" data-fallback-retry>Retry</button>' +
+          '</div>' +
+          (openUrl ? '<a class="fallback-url" href="' + esc(openUrl) + '" target="_blank" rel="noreferrer">' + esc(openUrl) + '</a>' : '') +
+        '</div>';
+      const fallbackOpen = stage.querySelector("[data-fallback-open]");
+      const fallbackRetry = stage.querySelector("[data-fallback-retry]");
+      if (fallbackOpen) {
+        fallbackOpen.disabled = !openUrl;
+        fallbackOpen.onclick = () => {
+          if (openUrl) void openHostLink({ url: openUrl });
+        };
+      }
+      if (fallbackRetry) {
+        fallbackRetry.onclick = () => {
+          startedFor = "";
+          void launchEmbed();
+        };
+      }
+    }
+
     async function openFallbackExternal() {
       if (!openUrl) return;
       let url = withChatBridgeParam(openUrl);
@@ -1051,12 +1131,29 @@ export function embedApp(
       return true;
     }
 
+    // We have connected to a standards-track MCP Apps host (Codex, Cursor,
+    // Claude over the SDK, our own renderer, …) through the postMessage
+    // \`ui/*\` bridge rather than ChatGPT's \`window.openai\` global. These hosts
+    // render the resource in a strict sandboxed iframe (typically
+    // \`sandbox="allow-scripts"\`, opaque origin). Self-navigating that iframe to
+    // the real app origin tears down the host bridge and loses the opaque-origin
+    // auth context, which shows up as a permanent / flashing loading state.
+    // Transplanting the app document into the shell keeps the bridge alive and
+    // works under the opaque origin via embed-token auth, exactly like Claude.
+    function isNativeMcpAppsBridgeHost() {
+      return !!app && !openAiBridge;
+    }
+
     function shouldTransplantAppDocument() {
       const render = renderModeSource();
       const mode = render.mode;
+      if (mode === "iframe" || mode === "nested" || render.frame === "iframe" || render.nested) {
+        return false;
+      }
       return (
         isClaudeMcpContentHost() ||
         isChatGptSandboxHost() ||
+        isNativeMcpAppsBridgeHost() ||
         mode === "transplant" ||
         render.frame === "transplant"
       );
@@ -1074,7 +1171,7 @@ export function embedApp(
       try {
         const host = window.location.hostname || "";
         const appParam = new URL(window.location.href).searchParams.get("app");
-        return /^[^.]+\\.web-sandbox\\.oaiusercontent\\.com$/i.test(host) || appParam === "chatgpt";
+        return /^(?:[^.]+\\.)?web-sandbox\\.oaiusercontent\\.com$/i.test(host) || appParam === "chatgpt";
       } catch {
         return false;
       }
@@ -1297,7 +1394,7 @@ export function embedApp(
     async function launchEmbed() {
       const launchUrl = openStartUrl || openUrl;
       if (!launchUrl) {
-        setMessage("Open link was not available.");
+        renderAppLaunchError("Open link was not available.");
         return;
       }
       if (!wantsEmbed()) {
@@ -1328,7 +1425,7 @@ export function embedApp(
         const data = parseToolResult(result);
         if (typeof data.startUrl !== "string" || !data.startUrl) {
           startedFor = "";
-          setMessage(data.error || "This app can be opened, but not embedded from this MCP server.");
+          renderAppLaunchError(data.error || "This app can be opened, but not embedded from this MCP server.");
           return;
         }
         const startUrl = withChatBridgeParam(data.startUrl);
@@ -1345,7 +1442,7 @@ export function embedApp(
         }
       } catch (err) {
         startedFor = "";
-        setMessage(err && err.message ? err.message : "Could not launch embedded app.");
+        renderAppLaunchError(err && err.message ? err.message : "Could not launch embedded app.");
       }
     }
 
@@ -1395,6 +1492,9 @@ export function embedApp(
       try {
         if (new URLSearchParams(window.location.search).get("app") === "chatgpt") return true;
       } catch (_err) {}
+      try {
+        if (/^(?:[^.]+\\.)?web-sandbox\\.oaiusercontent\\.com$/i.test(window.location.hostname || "")) return true;
+      } catch (_err) {}
       try {
         return /chatgpt/i.test(String(navigator.userAgent || ""));
       } catch (_err) {
@@ -1578,8 +1678,13 @@ export function embedApp(
         async openLink(params) {
           const url = typeof (params && params.url) === "string" ? params.url : "";
           if (!url) return { isError: true };
-          window.open(url, "_blank", "noopener,noreferrer");
-          return { ok: true };
+          try {
+            return await rpcRequest("ui/open-link", { url }, wrapperRequestTimeoutMs);
+          } catch (err) {
+            console.warn("[agent-native] MCP host open-link request failed", err);
+          }
+          const opened = window.open(url, "_blank", "noopener,noreferrer");
+          return opened ? { ok: true } : { isError: true };
         },
         async requestDisplayMode(params) {
           return await rpcRequest("ui/request-display-mode", objectValue(params));
@@ -1615,6 +1720,7 @@ export function embedApp(
           return;
         }
         if (
+          message.method === "ui/notifications/host-context-changed" ||
           message.method === "ui/notifications/host-context" ||
           message.method === "ui/notifications/context"
         ) {

package/corpus/core/src/server/attribution.ts

@@ -0,0 +1,211 @@
+/**
+ * First-touch referral attribution — server side.
+ *
+ * The browser captures an anonymous visitor's *first* landing context (referral
+ * source, UTM params, referring host, landing path) and persists it across the
+ * signup boundary in a first-party cookie named `an_ft` (see
+ * `client/analytics.ts`). On signup, the auth hook reads that cookie off the
+ * request and enriches the canonical server-side `signup` event so we can
+ * measure where new users came from and how apps spread (virality).
+ *
+ * This module is intentionally pure and dependency-free so it is trivially
+ * unit-testable and can never throw into the signup path. The single hard rule:
+ * parsing untrusted cookie input must NEVER throw — every accessor is defensive.
+ */
+
+/**
+ * The decoded first-touch attribution object. Mirrors the compact JSON the
+ * client writes into the `an_ft` cookie / `an_attribution` localStorage key.
+ * Every field is optional — the client omits empty fields to keep the cookie
+ * small, and a malformed/absent cookie yields `null`.
+ */
+export interface FirstTouchAttribution {
+  /** Referral source bucket, e.g. "clip_share", "plan_share". */
+  ref?: string;
+  /** Referrer's stable user id (the clip/plan owner who shared the link). */
+  via?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  /** `window.location.pathname` of the first page the visitor landed on. */
+  landing_path?: string;
+  /** Host of `document.referrer` (scrubbed; host only, never a full URL). */
+  landing_referrer?: string;
+  /** ISO timestamp of when the visitor first landed. */
+  landed_at?: string;
+}
+
+/** Cookie name written by the client (non-HttpOnly; non-sensitive). */
+export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+
+const STRING_FIELDS: Array<keyof FirstTouchAttribution> = [
+  "ref",
+  "via",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+  "landing_path",
+  "landing_referrer",
+  "landed_at",
+];
+
+/**
+ * Parse a raw `Cookie:` header into a flat name→value map. Tolerates missing
+ * input, extra whitespace, `=` inside values, and malformed pairs. Never throws.
+ */
+export function parseCookieHeader(
+  cookieHeader: string | null | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!cookieHeader || typeof cookieHeader !== "string") return out;
+  for (const part of cookieHeader.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name) continue;
+    const rawValue = part.slice(eq + 1).trim();
+    // First write wins so a duplicate cookie name can't clobber the first.
+    if (name in out) continue;
+    out[name] = rawValue;
+  }
+  return out;
+}
+
+/**
+ * Decode a single cookie value into a `FirstTouchAttribution`. The value is the
+ * URL-encoded compact JSON written by the client. Returns `null` for empty,
+ * malformed, or non-object input. Only known string fields are copied through,
+ * each clamped to a sane max length as a defense against an oversized cookie.
+ */
+export function decodeFirstTouchValue(
+  value: string | null | undefined,
+): FirstTouchAttribution | null {
+  if (!value || typeof value !== "string") return null;
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    // Not valid percent-encoding — fall back to the raw value and let the JSON
+    // parse below decide whether it's usable.
+    decoded = value;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  const source = parsed as Record<string, unknown>;
+  const result: FirstTouchAttribution = {};
+  let any = false;
+  for (const field of STRING_FIELDS) {
+    const raw = source[field];
+    if (typeof raw === "string" && raw.length > 0) {
+      result[field] = raw.slice(0, 120);
+      any = true;
+    }
+  }
+  return any ? result : null;
+}
+
+/**
+ * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.
+ * Returns `null` when the cookie is absent or unparseable. Never throws.
+ */
+export function readFirstTouchAttribution(
+  cookieHeader: string | null | undefined,
+): FirstTouchAttribution | null {
+  try {
+    const cookies = parseCookieHeader(cookieHeader);
+    return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);
+  } catch {
+    return null;
+  }
+}
+
+function isExternalReferrerHost(host: string | undefined): boolean {
+  const trimmed = host?.trim();
+  return !!trimmed && trimmed.length > 0;
+}
+
+/**
+ * Derive the `referral_source` bucket from first-touch attribution per the
+ * contract:
+ *   1. explicit `ref` wins;
+ *   2. landing path under `/share/` => "clip_share";
+ *   3. landing path that looks like a public plan page
+ *      (contains `/p/`, `/plan/`, or `/share-plan/`) => "plan_share";
+ *   4. a non-empty external referring host => "external";
+ *   5. otherwise => "direct".
+ */
+export function deriveReferralSource(ft: FirstTouchAttribution | null): string {
+  if (ft?.ref && ft.ref.trim()) return ft.ref.trim();
+  const path = ft?.landing_path ?? "";
+  if (path.startsWith("/share/")) return "clip_share";
+  if (
+    path.includes("/p/") ||
+    path.includes("/plan/") ||
+    path.includes("/share-plan/")
+  ) {
+    return "plan_share";
+  }
+  if (isExternalReferrerHost(ft?.landing_referrer)) return "external";
+  return "direct";
+}
+
+/**
+ * Compute the snake_case signup-event properties from first-touch attribution.
+ * Returns a clean object with `undefined` values omitted, ready to merge into
+ * the `signup` track call. Always sets `referral_source` (defaults to "direct").
+ *
+ * Pure and total — given any (or no) input it returns a well-formed object and
+ * never throws.
+ */
+export function deriveSignupAttribution(
+  ft: FirstTouchAttribution | null,
+): Record<string, string> {
+  const out: Record<string, string> = {
+    referral_source: deriveReferralSource(ft),
+  };
+  if (!ft) return out;
+
+  const setIf = (key: string, value: string | undefined) => {
+    const trimmed = value?.trim();
+    if (trimmed) out[key] = trimmed;
+  };
+
+  setIf("referrer_user", ft.via);
+  setIf("referral_medium", ft.utm_medium);
+  setIf("referral_campaign", ft.utm_campaign);
+  setIf("utm_source", ft.utm_source);
+  setIf("utm_medium", ft.utm_medium);
+  setIf("utm_campaign", ft.utm_campaign);
+  setIf("utm_content", ft.utm_content);
+  setIf("utm_term", ft.utm_term);
+  setIf("first_touch_path", ft.landing_path);
+  setIf("landing_referrer", ft.landing_referrer);
+
+  return out;
+}
+
+/**
+ * Convenience: read the cookie header and derive signup attribution in one
+ * call. Never throws; falls back to `{ referral_source: "direct" }` on any
+ * error.
+ */
+export function signupAttributionFromCookieHeader(
+  cookieHeader: string | null | undefined,
+): Record<string, string> {
+  try {
+    return deriveSignupAttribution(readFirstTouchAttribution(cookieHeader));
+  } catch {
+    return { referral_source: "direct" };
+  }
+}

package/corpus/core/src/server/auth.ts

@@ -1796,6 +1796,12 @@ function createAuthGuardFn(): (
     // route tree, no per-user data.
     if (p === "/__manifest") return;
     if (p === "/_agent-native/speculation-rules.json") return;
+    // Liveness probe: always public so uptime monitors and the keep-warm cron
+    // can reach the DB-warmup route without a session. It exposes no per-user
+    // data (just ok/db/ms) and runs a trivial `SELECT 1`. Without this bypass
+    // the gate below 401s anonymous /_agent-native/* requests before any DB
+    // query, so the database would never get warmed.
+    if (p === "/_agent-native/health") return;
     if (isPublicPath(normalizedUrl, publicPaths)) return;
     if (shouldBypassAuthForBuilderConnect(event, p)) return;
     if (isPublicWorkspacePageRequest(event, p, config)) {

package/corpus/core/src/server/better-auth-instance.ts

@@ -23,6 +23,7 @@ import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { autoJoinDomainMatchingOrgs } from "../org/auto-join-domain.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { flushTracking, identify, track } from "../tracking/index.js";
+import { signupAttributionFromCookieHeader } from "./attribution.js";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
@@ -72,23 +73,41 @@ export async function trackSignupEvent({
   authUserId,
   email,
   name,
+  attribution,
 }: {
   authProvider: string;
   authUserId?: string;
   email: string;
   name?: string | null;
+  /**
+   * First-touch referral attribution derived from the visitor's `an_ft`
+   * cookie (see `server/attribution.ts`). Snake_case keys such as
+   * `referral_source`, `referrer_user`, and the UTM passthrough are merged
+   * into the `signup` event so we can measure where new users came from.
+   * `undefined` values are dropped; a missing object is a clean no-op.
+   */
+  attribution?: Record<string, string | undefined>;
 }): Promise<void> {
   identify(email, {
     email,
     name: name ?? undefined,
     authUserId,
   });
+  const cleanAttribution: Record<string, string> = {};
+  if (attribution) {
+    for (const [key, value] of Object.entries(attribution)) {
+      if (typeof value === "string" && value.length > 0) {
+        cleanAttribution[key] = value;
+      }
+    }
+  }
   track(
     "signup",
     {
       ...resolveSignupTrackingProperties(),
       auth_provider: authProvider,
       ...(authUserId ? { auth_user_id: authUserId } : {}),
+      ...cleanAttribution,
     },
     { userId: email },
   );
@@ -929,22 +948,47 @@ async function createBetterAuthInstance(
     databaseHooks: {
       user: {
         create: {
-          after: async (user: {
-            id?: string;
-            email?: string;
-            name?: string | null;
-          }) => {
+          after: async (
+            user: {
+              id?: string;
+              email?: string;
+              name?: string | null;
+            },
+            // Better Auth (1.6.x) passes the endpoint context as the 2nd arg.
+            // It carries the originating request's headers (and on OAuth
+            // signups the callback request's headers), which is where the
+            // browser's `an_ft` first-touch cookie rides in.
+            context?: {
+              headers?: Headers | null;
+              request?: { headers?: Headers | null } | null;
+            } | null,
+          ) => {
             // When a newly-created user's email has pending org invitations
             // (common when someone is invited *before* they've signed up),
             // auto-accept them so the user lands in the org on their very
             // first page load instead of a blank-slate workspace.
             const email = user?.email;
             if (!email) return;
+            // Derive first-touch referral attribution from the request's
+            // cookie header. Never let attribution parsing throw or block
+            // signup — on any error fall back to `direct`.
+            let attribution: Record<string, string> | undefined;
+            try {
+              const cookieHeader =
+                context?.headers?.get("cookie") ??
+                context?.request?.headers?.get("cookie") ??
+                null;
+              attribution = signupAttributionFromCookieHeader(cookieHeader);
+            } catch (err) {
+              console.error("[auth] failed to derive signup attribution", err);
+              attribution = undefined;
+            }
             await trackSignupEvent({
               authProvider: "better-auth",
               authUserId: user.id,
               email,
               name: user.name,
+              attribution,
             });
             try {
               await acceptPendingInvitationsForEmail(email);