@agent-native/core 0.113.0 → 0.114.0

package/src/server/app-url.ts

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve the canonical URL of this app — used in transactional emails,
+ * invite links, and anywhere we need an absolute URL that remains valid
+ * outside the current request context.
+ *
+ * Resolution order:
+ *   1. Explicit public URL env vars (`APP_URL`, workspace OAuth origin,
+ *      `BETTER_AUTH_URL`) — operator overrides
+ *   2. Incoming request's origin (when an H3Event is available)
+ *   3. First-party template `prodUrl` from the registry (matched by
+ *      package.json name) — lets deployed first-party apps (mail,
+ *      calendar, analytics, …) use e.g. `analytics.agent-native.com`
+ *      instead of their Netlify preview hostname.
+ *   4. Platform-injected URL (Netlify `URL`, Vercel `VERCEL_URL`) —
+ *      automatically set by the hosting platform, so user-deployed apps
+ *      get a real hostname in emails without needing to set `APP_URL`.
+ *   5. Public `WORKSPACE_GATEWAY_URL` — multi-app workspace gateway
+ *   6. Local `WORKSPACE_GATEWAY_URL` — local multi-app workspace gateway
+ *   7. `http://localhost:3000`
+ *
+ * Older versions preferred `WORKSPACE_GATEWAY_URL` before platform URLs.
+ * That is fine for local development, but in hosted Builder Desktop sessions
+ * the gateway can be `127.0.0.1`, which must not become Better Auth's
+ * production base URL.
+ */
+import { getRequestURL, type H3Event } from "h3";
+
+import { TEMPLATES } from "../cli/templates-meta.js";
+import { isLocalDatabase } from "../db/client.js";
+
+let cachedPkgName: string | undefined | null = null;
+
+/**
+ * Read the app's package name, validated against the first-party template
+ * registry. On serverless runtimes (Netlify Functions, Cloudflare Workers),
+ * `process.cwd()` may point at a bundler-generated package.json with a
+ * bogus name (e.g. Nitro's "traced-node-modules"). Only trust the name if
+ * it matches a known template.
+ */
+function readPackageName(): string | undefined {
+  if (cachedPkgName !== null) return cachedPkgName ?? undefined;
+  try {
+    const pkgPath = path.join(process.cwd(), "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const name = typeof pkg?.name === "string" ? pkg.name : undefined;
+    const isKnown = name && TEMPLATES.some((t) => t.name === name);
+    cachedPkgName = isKnown ? name : undefined;
+  } catch {
+    cachedPkgName = undefined;
+  }
+  return cachedPkgName ?? undefined;
+}
+
+/** Strip trailing slashes for consistent URL concatenation. */
+function stripTrailingSlash(u: string): string {
+  return u.replace(/\/+$/, "");
+}
+
+function firstConfiguredUrl(keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value) return stripTrailingSlash(value);
+  }
+  return undefined;
+}
+
+function firstConfiguredPublicUrl(keys: readonly string[]): string | undefined {
+  const allowLoopback = !isHostedRuntime();
+  for (const key of keys) {
+    const value = process.env[key];
+    if (!value) continue;
+    const url = stripTrailingSlash(value);
+    if (!allowLoopback && isLoopbackUrl(url)) continue;
+    return url;
+  }
+  return undefined;
+}
+
+function isLoopbackUrl(value: string | undefined): boolean {
+  if (!value) return false;
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return (
+      hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isHostedRuntime(): boolean {
+  return Boolean(
+    process.env.NODE_ENV === "production" ||
+    process.env.NETLIFY ||
+    process.env.URL ||
+    process.env.DEPLOY_URL ||
+    process.env.VERCEL ||
+    process.env.VERCEL_URL ||
+    process.env.VERCEL_PROJECT_PRODUCTION_URL,
+  );
+}
+
+function workspaceGatewayUrl(options: {
+  allowLoopback: boolean;
+}): string | undefined {
+  const url = firstConfiguredUrl([
+    "WORKSPACE_GATEWAY_URL",
+    "VITE_WORKSPACE_GATEWAY_URL",
+  ]);
+  if (!url) return undefined;
+  if (!options.allowLoopback && isLoopbackUrl(url)) return undefined;
+  return url;
+}
+
+/**
+ * Look up the first-party template `prodUrl` for the current app based on
+ * its `package.json` name. Returns undefined if the app isn't a known
+ * first-party template or the template has no `prodUrl`.
+ */
+export function getFirstPartyProdUrl(): string | undefined {
+  const name = readPackageName();
+  if (!name) return undefined;
+  const t = TEMPLATES.find((t) => t.name === name);
+  return t?.prodUrl;
+}
+
+export function getAppProductionUrl(event?: H3Event): string {
+  const envUrl = firstConfiguredPublicUrl([
+    "APP_URL",
+    "WORKSPACE_OAUTH_ORIGIN",
+    "VITE_WORKSPACE_OAUTH_ORIGIN",
+    "BETTER_AUTH_URL",
+    "VITE_BETTER_AUTH_URL",
+  ]);
+  if (envUrl) return envUrl;
+
+  // Prefer the incoming request's origin when we have one — for local dev
+  // this is `http://localhost:3000`, which keeps Better Auth from setting
+  // `Secure` cookies on plain-HTTP dev servers.
+  if (event) {
+    try {
+      const url = getRequestURL(event);
+      return `${url.protocol}//${url.host}`;
+    } catch {
+      // fall through
+    }
+  }
+
+  // Fall back to a first-party template's hard-coded prod URL when we're
+  // running in production OR on a remote database (Neon/Postgres/Turso).
+  // A remote DB means we're deployed even if NODE_ENV isn't explicitly
+  // "production" (e.g. Netlify Functions). In local dev with SQLite, skip
+  // this — the hard-coded URL breaks auth via Secure cookies on HTTP.
+  if (process.env.NODE_ENV === "production" || !isLocalDatabase()) {
+    const firstParty = getFirstPartyProdUrl();
+    if (firstParty) return stripTrailingSlash(firstParty);
+
+    // Netlify injects `URL` (main site URL, always https) and `DEPLOY_URL`
+    // (deploy-specific URL). Prefer `URL` so emails always link to the
+    // primary domain rather than a preview branch URL.
+    const netlifyUrl = process.env.URL || process.env.DEPLOY_URL;
+    if (netlifyUrl) return stripTrailingSlash(netlifyUrl);
+
+    // Vercel injects `VERCEL_PROJECT_PRODUCTION_URL` (custom/primary domain,
+    // no protocol) and `VERCEL_URL` (ephemeral deployment hostname). Prefer
+    // the production URL so emails use the real domain, not *.vercel.app.
+    const vercelUrl =
+      process.env.VERCEL_PROJECT_PRODUCTION_URL || process.env.VERCEL_URL;
+    if (vercelUrl) return `https://${stripTrailingSlash(vercelUrl)}`;
+
+    const publicWorkspaceGateway = workspaceGatewayUrl({
+      allowLoopback: false,
+    });
+    if (publicWorkspaceGateway) return publicWorkspaceGateway;
+  }
+
+  const localWorkspaceGateway = workspaceGatewayUrl({ allowLoopback: true });
+  if (localWorkspaceGateway) return localWorkspaceGateway;
+
+  return "http://localhost:3000";
+}

package/src/server/attachment-actions.ts

@@ -0,0 +1,276 @@
+/**
+ * Core `read-attachment` agent tool.
+ *
+ * Large text pastes, CSVs, JSON files, and code files are truncated to
+ * 60 K chars when injected into the model context. This action lets the agent
+ * read the full content in offset/limit slices from the durable resource
+ * stored at attach-time.
+ *
+ * Storage: text-y attachments are persisted as `agent_scratch` resources
+ * keyed  `attachments/<threadId>/<sanitised-name>` under the owner's scope.
+ * The maximum stored size per attachment is 20 MB.
+ */
+
+import type { ActionEntry } from "../agent/production-agent.js";
+import { resourceGet, resourcePut, resourceList } from "../resources/store.js";
+import { getRequestUserEmail } from "./request-context.js";
+
+const MAX_ATTACHMENT_RESOURCE_BYTES = 20 * 1024 * 1024; // 20 MB
+const DEFAULT_SLICE_LIMIT = 8_000; // chars returned by default per call
+
+/**
+ * Derive a deterministic resource path for a text attachment stored inside a
+ * thread scope.
+ */
+function attachmentResourcePath(
+  threadId: string,
+  name: string,
+  index: number,
+): string {
+  // Sanitise the name: keep alphanum, dot, dash, underscore; replace anything
+  // else with '_'. Append the index to avoid collisions between same-named
+  // files in the same thread.
+  const safe = name.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
+  return `attachments/${threadId}/${index}-${safe}`;
+}
+
+/**
+ * Determine whether a MIME type or filename represents a text-like attachment
+ * that should be stored as a durable resource for paginated reads.
+ */
+export function isTextLikeMimeType(contentType: string | undefined): boolean {
+  if (!contentType) return false;
+  const ct = contentType.toLowerCase().split(";")[0].trim();
+  if (ct.startsWith("text/")) return true;
+  if (ct === "application/json") return true;
+  if (ct === "application/javascript") return true;
+  if (ct === "application/typescript") return true;
+  return false;
+}
+
+export function isTextLikeFilename(name: string | undefined): boolean {
+  if (!name) return false;
+  return /\.(txt|md|markdown|csv|json|jsonl|yaml|yml|ts|tsx|js|jsx|py|rb|go|rs|java|c|cpp|h|cs|swift|kt|sh|bash|zsh|fish|toml|ini|cfg|conf|xml|html|htm|css|scss|sass|less|sql|graphql|gql)$/i.test(
+    name,
+  );
+}
+
+/**
+ * Persist text-ish attachments from a chat turn as thread-scoped resources
+ * so the agent can later read them in slices via `read-attachment`.
+ *
+ * Silently skips attachments that aren't text-like or have no text content.
+ * Returns a map from attachment index → stored resource id for use in the
+ * truncation-notice injected into the model context.
+ */
+export async function persistTextAttachmentsAsResources(opts: {
+  attachments: Array<{
+    type?: string;
+    name?: string;
+    contentType?: string;
+    text?: string;
+  }>;
+  threadId: string;
+  ownerEmail: string | null | undefined;
+}): Promise<
+  Map<number, { resourceId: string; path: string; totalChars: number }>
+> {
+  const result = new Map<
+    number,
+    { resourceId: string; path: string; totalChars: number }
+  >();
+  const owner = opts.ownerEmail || "anonymous";
+
+  for (let i = 0; i < opts.attachments.length; i++) {
+    const att = opts.attachments[i];
+    if (!att.text || att.text.length === 0) continue;
+    if (!isTextLikeMimeType(att.contentType) && !isTextLikeFilename(att.name)) {
+      continue;
+    }
+
+    const text =
+      att.text.length > MAX_ATTACHMENT_RESOURCE_BYTES
+        ? att.text.slice(0, MAX_ATTACHMENT_RESOURCE_BYTES)
+        : att.text;
+
+    const path = attachmentResourcePath(
+      opts.threadId,
+      att.name || "attachment",
+      i,
+    );
+
+    try {
+      const resource = await resourcePut(
+        owner,
+        path,
+        text,
+        att.contentType || "text/plain",
+        {
+          createdBy: "user",
+          visibility: "agent_scratch",
+          threadId: opts.threadId,
+          // 7-day TTL — long enough for multi-session threads.
+          expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
+        },
+      );
+      result.set(i, {
+        resourceId: resource.id,
+        path,
+        totalChars: text.length,
+      });
+    } catch (err) {
+      // Best-effort: if storage fails the agent still gets the truncated
+      // context and the read-attachment call will return a not-found error.
+      console.warn(
+        "[agent-native] persistTextAttachmentsAsResources failed:",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  return result;
+}
+
+export function createCoreAttachmentActionEntries(): Record<
+  string,
+  ActionEntry
+> {
+  return {
+    "read-attachment": {
+      tool: {
+        description: [
+          "Read a slice of a large text attachment (CSV, code, JSON, markdown, plain text) that was",
+          "truncated in the conversation context. Use this when the initial context showed a truncated",
+          "attachment and you need to read more of it.",
+          "",
+          "Identify the attachment by name (e.g. name='data.csv') exactly as shown in the",
+          "<attachment name='...'> tag in the conversation. Use offset and limit to page through it.",
+          "",
+          "Returns { content, offset, limit, totalChars, hasMore }.",
+          "If totalChars is unknown (attachment not stored as a resource), returns a not-found message.",
+        ].join("\n"),
+        parameters: {
+          type: "object" as const,
+          properties: {
+            name: {
+              type: "string",
+              description:
+                "The exact attachment name as it appeared in the <attachment name='...'> tag.",
+            },
+            threadId: {
+              type: "string",
+              description:
+                "The chat thread ID. If omitted, the current thread is used.",
+            },
+            offset: {
+              type: "string",
+              description:
+                "Character offset to start reading from. Default: 0.",
+            },
+            limit: {
+              type: "string",
+              description: `Maximum characters to return. Default: ${DEFAULT_SLICE_LIMIT}.`,
+            },
+          },
+          required: ["name"],
+        },
+      },
+      run: async (input: Record<string, string>, ctx) => {
+        const ownerEmail =
+          ctx?.userEmail || getRequestUserEmail() || "anonymous";
+        const name = String(input.name || "").trim();
+        const offset = Math.max(0, parseInt(input.offset || "0", 10) || 0);
+        const limit = Math.min(
+          50_000,
+          Math.max(
+            1,
+            parseInt(input.limit || String(DEFAULT_SLICE_LIMIT), 10) ||
+              DEFAULT_SLICE_LIMIT,
+          ),
+        );
+
+        if (!name) {
+          return { error: "name is required" };
+        }
+
+        // Determine threadId — from input or from turn-scoped run context.
+        let threadId = String(input.threadId || "").trim();
+        if (!threadId) {
+          try {
+            const { getRequestRunContext } =
+              await import("./request-context.js");
+            const runCtx = getRequestRunContext();
+            threadId = (runCtx as any)?.threadId || "";
+          } catch {
+            // ignore
+          }
+        }
+
+        if (!threadId) {
+          return {
+            error:
+              "threadId is required (could not be resolved from context). Re-call with the thread id.",
+          };
+        }
+
+        // Search the owner's resources for an attachment matching the name.
+        try {
+          const prefix = `attachments/${threadId}/`;
+          const metas = await resourceList(ownerEmail, prefix, {
+            includeAgentScratch: true,
+          });
+
+          // Find by name suffix match (the path ends with <index>-<safe-name>).
+          const safeName = name.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
+          const matching = metas.filter((m) => m.path.endsWith(`-${safeName}`));
+
+          // If no exact match, try a partial search on the raw name.
+          const candidates =
+            matching.length > 0
+              ? matching
+              : metas.filter((m) => {
+                  const basename = m.path.split("/").pop() || "";
+                  // Strip the leading index prefix (<digits>-)
+                  const withoutIndex = basename.replace(/^\d+-/, "");
+                  return withoutIndex
+                    .toLowerCase()
+                    .includes(name.toLowerCase());
+                });
+
+          if (candidates.length === 0) {
+            return {
+              error: `No stored attachment found with name "${name}" in thread ${threadId}. The attachment may not have been persisted as a resource (only text-like files are stored).`,
+            };
+          }
+
+          // Use the first match (most recent upsert wins when there are
+          // multiple same-name attachments in the same thread).
+          const meta = candidates[0];
+          const resource = await resourceGet(meta.id);
+          if (!resource) {
+            return { error: `Attachment resource "${name}" not found.` };
+          }
+
+          const totalChars = resource.content.length;
+          const slice = resource.content.slice(offset, offset + limit);
+          return {
+            name,
+            content: slice,
+            offset,
+            limit,
+            totalChars,
+            hasMore: offset + limit < totalChars,
+            note:
+              offset + limit < totalChars
+                ? `${totalChars - offset - limit} chars remain. Call again with offset=${offset + limit}.`
+                : "End of attachment.",
+          };
+        } catch (err) {
+          return {
+            error: `Failed to read attachment: ${err instanceof Error ? err.message : String(err)}`,
+          };
+        }
+      },
+    },
+  };
+}

package/src/server/attribution.ts

@@ -0,0 +1,214 @@
+/**
+ * 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
+ *      (`/p/`, `/plan/`, `/plans/`, `/recaps/`, 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("/plans/") ||
+    path.includes("/recaps/") ||
+    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" };
+  }
+}