@agent-native/core 0.68.3 → 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/extensions/web-search-tool.ts

@@ -7,13 +7,15 @@
  *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)
  *   2. Tavily            (TAVILY_API_KEY)
  *   3. Exa               (EXA_API_KEY)
- *   4. Builder.io        (connected Builder credentials)
+ *   4. Firecrawl         (FIRECRAWL_API_KEY)
+ *   5. Builder.io        (connected Builder credentials)
  *
  * The first configured backend wins. If none is configured, the tool
  * returns a helpful message telling the user which keys to add.
  *
- * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or
- * EXA_API_KEY via app secrets settings or environment variables.
+ * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY,
+ * EXA_API_KEY, or FIRECRAWL_API_KEY via app secrets settings or environment
+ * variables.
  */
 
 import type { ActionEntry } from "../agent/production-agent.js";
@@ -222,6 +224,40 @@ async function searchExa(
   }));
 }
 
+async function searchFirecrawl(
+  query: string,
+  count: number,
+  apiKey: string,
+): Promise<WebSearchResult[]> {
+  const res = await fetch("https://api.firecrawl.dev/v2/search", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      query,
+      limit: count,
+    }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) {
+    throw new Error(`Firecrawl error ${res.status}: ${await res.text()}`);
+  }
+  // v2 groups results by source ({ data: { web: [...] } }); older shapes
+  // return a flat array ({ data: [...] }). Accept both defensively.
+  type FirecrawlResult = { title?: string; url?: string; description?: string };
+  const data = (await res.json()) as {
+    data?: FirecrawlResult[] | { web?: FirecrawlResult[] };
+  };
+  const results = Array.isArray(data.data) ? data.data : (data.data?.web ?? []);
+  return results.map((r) => ({
+    title: r.title ?? "",
+    url: r.url ?? "",
+    snippet: r.description ?? "",
+  }));
+}
+
 async function searchBuilderManaged(
   query: string,
   count: number,
@@ -287,7 +323,7 @@ export function createWebSearchToolEntry(
     "web-search": {
       tool: {
         description:
-          "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or EXA_API_KEY.",
+          "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY.",
         parameters: {
           type: "object" as const,
           properties: {
@@ -318,6 +354,7 @@ export function createWebSearchToolEntry(
         const braveKey = await resolveSearchKey("BRAVE_SEARCH_API_KEY", opts);
         const tavilyKey = await resolveSearchKey("TAVILY_API_KEY", opts);
         const exaKey = await resolveSearchKey("EXA_API_KEY", opts);
+        const firecrawlKey = await resolveSearchKey("FIRECRAWL_API_KEY", opts);
         const builderCredentials = await resolveBuilderSearchCredentials(opts);
 
         let results: WebSearchResult[];
@@ -334,6 +371,9 @@ export function createWebSearchToolEntry(
           } else if (exaKey) {
             results = await searchExa(query, count, exaKey);
             backend = "Exa";
+          } else if (firecrawlKey) {
+            results = await searchFirecrawl(query, count, firecrawlKey);
+            backend = "Firecrawl";
           } else if (builderCredentials) {
             managedText = await searchBuilderManaged(
               query,
@@ -350,6 +390,7 @@ export function createWebSearchToolEntry(
               "  • BRAVE_SEARCH_API_KEY  — https://brave.com/search/api/",
               "  • TAVILY_API_KEY        — https://tavily.com/",
               "  • EXA_API_KEY           — https://exa.ai/",
+              "  • FIRECRAWL_API_KEY     — https://firecrawl.dev/",
             ].join("\n");
           }
         } catch (err: unknown) {

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/secrets/register-framework-secrets.ts

@@ -47,6 +47,13 @@ export function registerFrameworkSecrets(): void {
         "Enables the web-search agent tool via Exa. Used as fallback when Brave and Tavily are not set and before Builder-managed search.",
       docsUrl: "https://exa.ai/",
     },
+    {
+      key: "FIRECRAWL_API_KEY",
+      label: "Firecrawl API Key",
+      description:
+        "Enables the web-search agent tool via Firecrawl. Used as fallback when Brave, Tavily, and Exa are not set and before Builder-managed search.",
+      docsUrl: "https://firecrawl.dev/",
+    },
   ];
 
   for (const entry of webSearchKeys) {

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)) {