@agent-native/core 0.69.0 → 0.70.1

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -832,6 +832,38 @@ function contentAfterContinuationPrefix(
   return [...delta, ...content.slice(contentIndex)];
 }
 
+// Concrete "ship a compact first version, then refine incrementally" guidance
+// keyed by the large-payload action the model was cut off while preparing. A run
+// cut off mid-stream while streaming one big tool input (extension HTML, a full
+// design file set, an entire dashboard config) re-streams the SAME oversized
+// payload on every continuation and never finishes inside the soft-timeout
+// window — the classic thrash loop. Pointing the resumed model at the
+// incremental-edit path for that specific action is what breaks the loop.
+// Returns undefined for tools with no known incremental counterpart so the
+// caller falls back to generic compact-first advice.
+function incrementalActionGuidance(tool: string): string | undefined {
+  switch (tool) {
+    case "create-extension":
+    case "update-extension":
+      return "create a compact working v1 with `create-extension`, then use focused `update-extension` edits for refinements";
+    case "generate-design":
+    case "update-design":
+      return "persist a minimal first version (fewer files) with `generate-design`, then refine individual files with `edit-design` search/replace instead of resending everything";
+    case "create-visual-plan":
+    case "create-ui-plan":
+    case "create-plan-design":
+    case "create-prototype-plan":
+      return "create the plan with its core sections or first screen, then expand it with `update-visual-plan`/`patch-visual-plan-source` follow-up edits";
+    case "update-visual-plan":
+    case "patch-visual-plan-source":
+      return "apply smaller, targeted `patch-visual-plan-source` edits rather than rewriting the whole plan in one call";
+    case "update-dashboard":
+      return "save a small dashboard first, then add panels one at a time with `update-dashboard` incremental `ops` edits instead of authoring the whole config in one call";
+    default:
+      return undefined;
+  }
+}
+
 function autoContinueMessage(signal: AgentAutoContinueSignal): string {
   const tool = lastActivityTool(signal.activityTrail);
   const reason =
@@ -845,15 +877,20 @@ function autoContinueMessage(signal: AgentAutoContinueSignal): string {
             ? "The previous stream ended before the agent sent a final completion signal."
             : "The previous run reached an internal execution budget.";
   // A run_timeout or a mid-stream cutoff while assembling one large action
-  // payload (e.g. inlining a big pasted HTML file into `create-extension`) is
-  // the classic trigger for the repetition/cutoff loop. Nudge the model toward
-  // a compact first version it can actually finish in a single run.
+  // payload (e.g. inlining a big pasted HTML file into `create-extension`, a
+  // full file set into `generate-design`, or a whole `update-dashboard` config)
+  // is the classic trigger for the repetition/cutoff loop. Nudge the model
+  // toward a compact first version it can actually finish in a single run, then
+  // incremental refinements — never re-streaming the same oversized payload.
   const cutoffPreparingAction =
     signal.reason === "run_timeout" || signal.reason === "stream_ended";
-  const actionInputNote =
-    cutoffPreparingAction && tool
-      ? `\n\nThe previous run was cut off while preparing the \`${tool}\` action input before the action could finish. Avoid spending another whole run assembling one large tool payload. If this is \`create-extension\`, create a compact working v1 first, then use focused \`update-extension\` edits for refinements.`
-      : "";
+  let actionInputNote = "";
+  if (cutoffPreparingAction && tool) {
+    const guidance = incrementalActionGuidance(tool);
+    actionInputNote = guidance
+      ? `\n\nThe previous run was cut off while preparing the \`${tool}\` action input before the action could finish. Avoid spending another whole run assembling one large tool payload — ${guidance}.`
+      : `\n\nThe previous run was cut off while preparing the \`${tool}\` action input before the action could finish. Avoid re-assembling one large tool payload: produce a compact first result you can finish in a single run, then refine it with smaller follow-up edits.`;
+  }
   return `${AUTO_CONTINUE_PROMPT}\n\n${AUTO_CONTINUE_COMPLETION_GUARD}\n\nInternal note: ${reason}${actionInputNote}`;
 }
 

package/corpus/core/src/client/analytics.ts

@@ -61,6 +61,44 @@ const LLM_CONNECTION_CACHE_TTL_MS = 5 * 60 * 1000;
 // session over multiple visits.
 const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
+// First-touch referral attribution (viral attribution). Captured once on the
+// visitor's first page load and persisted across the signup boundary so the
+// server-side `signup` event can record where the user came from. First-write
+// wins — an existing value is never overwritten.
+const FIRST_TOUCH_STORAGE_KEY = "an_attribution";
+const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+// 30 days, matching the session cookie lifetime — long enough to bridge a
+// "land today, sign up next week" path without retaining attribution forever.
+const FIRST_TOUCH_COOKIE_MAX_AGE_SECONDS = 2592000;
+const FIRST_TOUCH_MAX_FIELD_LENGTH = 120;
+// Keep the serialized cookie well under the ~4KB browser cap; we bail rather
+// than write a runaway cookie if some field combination blows past this.
+const FIRST_TOUCH_MAX_COOKIE_BYTES = 1500;
+const FIRST_TOUCH_QUERY_FIELDS = [
+  "ref",
+  "via",
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+] as const;
+
+let _firstTouchCaptured = false;
+
+export interface FirstTouchAttribution {
+  ref?: string;
+  via?: string;
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  landing_path?: string;
+  landing_referrer?: string;
+  landed_at?: string;
+}
+
 function generateVisitorId(): string {
   try {
     if (
@@ -214,6 +252,148 @@ function getOrCreateSessionId(): string | undefined {
   return id;
 }
 
+function truncateFirstTouchField(value: string | null | undefined): string {
+  if (!value) return "";
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  return trimmed.slice(0, FIRST_TOUCH_MAX_FIELD_LENGTH);
+}
+
+/**
+ * Extract just the host of a referrer URL — never the full URL or query
+ * string (those can carry tokens). Returns "" when there's no usable host or
+ * the referrer is same-origin (a same-site navigation isn't a referral).
+ */
+function scrubReferrerHost(referrer: string | undefined): string {
+  if (!referrer) return "";
+  try {
+    const url = new URL(referrer);
+    const host = url.host;
+    if (!host) return "";
+    if (
+      typeof window !== "undefined" &&
+      host.toLowerCase() === window.location.host.toLowerCase()
+    ) {
+      return "";
+    }
+    return truncateFirstTouchField(host);
+  } catch {
+    return "";
+  }
+}
+
+function buildFirstTouchAttribution(): FirstTouchAttribution {
+  const attribution: FirstTouchAttribution = {};
+  let params: URLSearchParams | null = null;
+  try {
+    params = new URLSearchParams(window.location.search);
+  } catch {
+    params = null;
+  }
+  if (params) {
+    for (const field of FIRST_TOUCH_QUERY_FIELDS) {
+      const value = truncateFirstTouchField(params.get(field));
+      if (value) attribution[field] = value;
+    }
+  }
+  const landingPath = truncateFirstTouchField(window.location.pathname);
+  if (landingPath) attribution.landing_path = landingPath;
+  const landingReferrer =
+    typeof document !== "undefined" ? scrubReferrerHost(document.referrer) : "";
+  if (landingReferrer) attribution.landing_referrer = landingReferrer;
+  attribution.landed_at = new Date().toISOString();
+  return attribution;
+}
+
+function readFirstTouchCookie(): string | null {
+  if (typeof document === "undefined") return null;
+  try {
+    const cookies = document.cookie ? document.cookie.split(";") : [];
+    for (const part of cookies) {
+      const eq = part.indexOf("=");
+      if (eq === -1) continue;
+      const name = part.slice(0, eq).trim();
+      if (name === FIRST_TOUCH_COOKIE_NAME) {
+        return part.slice(eq + 1).trim();
+      }
+    }
+  } catch {
+    // document.cookie can throw in sandboxed iframes — best-effort.
+  }
+  return null;
+}
+
+function writeFirstTouchCookie(encodedValue: string): void {
+  if (typeof document === "undefined") return;
+  // Non-sensitive, written by client JS, so no HttpOnly. SameSite=Lax keeps it
+  // on top-level navigations (which is how share links arrive) without leaking
+  // it to cross-site subresource requests.
+  const cookie =
+    `${FIRST_TOUCH_COOKIE_NAME}=${encodedValue}; path=/; ` +
+    `max-age=${FIRST_TOUCH_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+  if (cookie.length > FIRST_TOUCH_MAX_COOKIE_BYTES) return;
+  try {
+    document.cookie = cookie;
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Capture the visitor's first-touch referral attribution exactly once. Reads
+ * the current URL query params + landing info and, IF no attribution is
+ * already stored (first-write-wins), persists it to both `localStorage`
+ * (`an_attribution`) and the first-party `an_ft` cookie. Fully defensive and
+ * SSR-safe — any failure is swallowed so it can never break app boot.
+ */
+function captureFirstTouchAttribution(): void {
+  if (_firstTouchCaptured) return;
+  _firstTouchCaptured = true;
+  if (typeof window === "undefined") return;
+  try {
+    const existing = safeStorageGet(FIRST_TOUCH_STORAGE_KEY);
+    if (existing) {
+      // Already captured in a prior visit. Backfill the cookie if it expired
+      // or was cleared so the signup boundary still sees first-touch data, but
+      // never overwrite the stored value itself (first-write-wins).
+      if (!readFirstTouchCookie()) {
+        try {
+          writeFirstTouchCookie(encodeURIComponent(existing));
+        } catch {
+          // ignore
+        }
+      }
+      return;
+    }
+    const attribution = buildFirstTouchAttribution();
+    const json = JSON.stringify(attribution);
+    safeStorageSet(FIRST_TOUCH_STORAGE_KEY, json);
+    writeFirstTouchCookie(encodeURIComponent(json));
+  } catch {
+    // Attribution is best-effort telemetry; never let it break boot.
+  }
+}
+
+/**
+ * Return the parsed first-touch referral attribution captured for this
+ * visitor, or `null` when none is stored. Reads from `localStorage`
+ * (`an_attribution`). SSR-safe and defensive.
+ */
+export function getFirstTouchAttribution(): FirstTouchAttribution | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = safeStorageGet(FIRST_TOUCH_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as FirstTouchAttribution;
+  } catch {
+    return null;
+  }
+}
+
 function isLocalAnalyticsHostname(hostname: string | undefined): boolean {
   const h = (hostname || "").toLowerCase();
   return (
@@ -531,6 +711,7 @@ export function configureTracking(options: {
   if (typeof window !== "undefined") {
     ensureSentry();
     ensureAmplitude();
+    captureFirstTouchAttribution();
     installLlmConnectionRefresh();
     installPageviewTracking();
   }

package/corpus/core/src/client/changelog/Changelog.tsx

@@ -0,0 +1,321 @@
+/**
+ * Changelog UI — renders an app's CHANGELOG.md as an in-app "What's new"
+ * surface. Core owns all of this; a template just passes its own
+ * `CHANGELOG.md?raw` content in (Vite inlines it at build time, so this works
+ * on every host with no runtime file access or server route).
+ *
+ * Surfaces:
+ *   - <ChangelogDialog>      a self-contained modal listing every release.
+ *   - <ChangelogSettingsCard> a settings-page card with the latest updates.
+ *   - useChangelogSeen()     tracks the last release a user has seen (so the
+ *                            command menu can show an "unseen" dot).
+ *
+ * The command menu's built-in `changelog` prop (see CommandMenu.tsx) wires the
+ * dialog automatically — most templates never touch these directly.
+ */
+
+import React, { useEffect, useMemo, useState } from "react";
+import { IconX, IconHistory } from "@tabler/icons-react";
+
+import { parseChangelog, type ChangelogEntry } from "../../changelog/parse.js";
+import {
+  markdownModule,
+  remarkGfmFn,
+  useMarkdownReady,
+  markdownUrlTransform,
+} from "../chat/markdown-renderer.js";
+import { cn } from "../utils.js";
+
+// ─── Date formatting ──────────────────────────────────────────────────────────
+
+function formatEntryHeading(entry: ChangelogEntry): string {
+  if (entry.date) {
+    // Parse as a plain calendar date (avoid TZ shifting YYYY-MM-DD back a day).
+    const [y, m, d] = entry.date.split("-").map(Number);
+    if (y && m && d) {
+      const formatted = new Date(y, m - 1, d).toLocaleDateString(undefined, {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      });
+      return entry.version ? `${entry.version} · ${formatted}` : formatted;
+    }
+  }
+  return entry.title;
+}
+
+// ─── Markdown body ────────────────────────────────────────────────────────────
+// A small, self-contained renderer for a release body. Avoids depending on the
+// typography plugin (`prose`) being generated in the host template by applying
+// explicit utility classes that Tailwind scans from core's compiled output.
+
+const changelogMarkdownComponents = {
+  h3: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+    <h3
+      {...props}
+      className="mb-1.5 mt-3 text-xs font-semibold uppercase tracking-wide text-muted-foreground first:mt-0"
+    />
+  ),
+  ul: (props: React.HTMLAttributes<HTMLUListElement>) => (
+    <ul
+      {...props}
+      className="mb-2 ml-1 list-disc space-y-1 pl-4 text-sm text-foreground marker:text-muted-foreground"
+    />
+  ),
+  ol: (props: React.HTMLAttributes<HTMLOListElement>) => (
+    <ol
+      {...props}
+      className="mb-2 ml-1 list-decimal space-y-1 pl-4 text-sm text-foreground marker:text-muted-foreground"
+    />
+  ),
+  li: (props: React.HTMLAttributes<HTMLLIElement>) => (
+    <li {...props} className="leading-relaxed" />
+  ),
+  p: (props: React.HTMLAttributes<HTMLParagraphElement>) => (
+    <p {...props} className="mb-2 text-sm leading-relaxed text-foreground" />
+  ),
+  a: (props: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a
+      {...props}
+      target="_blank"
+      rel="noreferrer"
+      className="font-medium underline underline-offset-2"
+    />
+  ),
+  code: (props: React.HTMLAttributes<HTMLElement>) => (
+    <code
+      {...props}
+      className="rounded bg-muted px-1 py-0.5 font-mono text-[0.85em]"
+    />
+  ),
+};
+
+function ChangelogBody({ markdown }: { markdown: string }) {
+  const ready = useMarkdownReady();
+  const ReactMarkdown = markdownModule?.default;
+  const gfm = remarkGfmFn;
+
+  if (!ready || !ReactMarkdown || !gfm) {
+    // The react-markdown chunk loads on module eval; this is typically only one
+    // frame. Show readable plain text rather than nothing in the meantime.
+    return (
+      <div className="whitespace-pre-wrap text-sm text-foreground">
+        {markdown}
+      </div>
+    );
+  }
+  return (
+    <ReactMarkdown
+      remarkPlugins={[gfm]}
+      components={changelogMarkdownComponents}
+      urlTransform={markdownUrlTransform}
+    >
+      {markdown}
+    </ReactMarkdown>
+  );
+}
+
+// ─── Unseen tracking ──────────────────────────────────────────────────────────
+
+function seenStorageKey(appKey: string): string {
+  return `an:changelog-seen:${appKey}`;
+}
+
+/**
+ * Tracks the latest release a user has already seen (per browser, via
+ * localStorage). Returns whether there's an unseen release and a `markSeen`
+ * callback to clear the indicator once the changelog is opened.
+ */
+export function useChangelogSeen(
+  appKey: string,
+  latestId: string | undefined,
+): { unseen: boolean; markSeen: () => void } {
+  const [seenId, setSeenId] = useState<string | null>(null);
+  const [hydrated, setHydrated] = useState(false);
+
+  useEffect(() => {
+    try {
+      setSeenId(window.localStorage.getItem(seenStorageKey(appKey)));
+    } catch {
+      // Private mode / disabled storage — treat as "nothing seen yet".
+    }
+    setHydrated(true);
+  }, [appKey]);
+
+  const markSeen = React.useCallback(() => {
+    if (!latestId) return;
+    setSeenId(latestId);
+    try {
+      window.localStorage.setItem(seenStorageKey(appKey), latestId);
+    } catch {
+      // Ignore storage failures; the dot just won't persist.
+    }
+  }, [appKey, latestId]);
+
+  // Don't flag "unseen" until hydrated, and never on a first-ever visit (no
+  // stored value) — only once the user has seen *something* and a newer
+  // release appears. This avoids nagging brand-new users.
+  const unseen =
+    hydrated && !!latestId && seenId !== null && seenId !== latestId;
+
+  return { unseen, markSeen };
+}
+
+// ─── Shared markup ────────────────────────────────────────────────────────────
+
+function ChangelogEntries({
+  entries,
+  emptyText,
+}: {
+  entries: ChangelogEntry[];
+  emptyText: string;
+}) {
+  if (entries.length === 0) {
+    return <p className="text-sm text-muted-foreground">{emptyText}</p>;
+  }
+  return (
+    <div className="space-y-6">
+      {entries.map((entry) => (
+        <section key={entry.id}>
+          <h4 className="mb-2 text-sm font-semibold text-foreground">
+            {formatEntryHeading(entry)}
+          </h4>
+          <ChangelogBody markdown={entry.body} />
+        </section>
+      ))}
+    </div>
+  );
+}
+
+// ─── Dialog ───────────────────────────────────────────────────────────────────
+
+export interface ChangelogDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Raw CHANGELOG.md contents (e.g. `import md from "../CHANGELOG.md?raw"`). */
+  markdown: string;
+  /** Dialog heading. Default: "What's new". */
+  title?: string;
+}
+
+export function ChangelogDialog({
+  open,
+  onOpenChange,
+  markdown,
+  title = "What's new",
+}: ChangelogDialogProps) {
+  const entries = useMemo(() => parseChangelog(markdown), [markdown]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onOpenChange(false);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onOpenChange]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 p-4"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onOpenChange(false);
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        className="mt-[8vh] flex max-h-[80vh] w-full max-w-xl flex-col rounded-lg border border-border bg-popover text-popover-foreground shadow-lg"
+      >
+        <div className="flex items-center justify-between border-b border-border px-5 py-3.5">
+          <div className="flex items-center gap-2">
+            <IconHistory className="h-4 w-4 text-muted-foreground" />
+            <h3 className="text-sm font-semibold">{title}</h3>
+          </div>
+          <button
+            type="button"
+            onClick={() => onOpenChange(false)}
+            aria-label="Close"
+            className="rounded-sm p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
+          >
+            <IconX className="h-4 w-4" />
+          </button>
+        </div>
+        <div className="overflow-y-auto px-5 py-4">
+          <ChangelogEntries
+            entries={entries}
+            emptyText="No updates have been published yet."
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ─── Settings card ────────────────────────────────────────────────────────────
+
+export interface ChangelogSettingsCardProps {
+  /** Raw CHANGELOG.md contents (e.g. `import md from "../CHANGELOG.md?raw"`). */
+  markdown: string;
+  /** How many recent releases to show inline before "View all". Default: 2. */
+  limit?: number;
+  /** Card heading. Default: "What's new". */
+  title?: string;
+  className?: string;
+}
+
+export function ChangelogSettingsCard({
+  markdown,
+  limit = 2,
+  title = "What's new",
+  className,
+}: ChangelogSettingsCardProps) {
+  const entries = useMemo(() => parseChangelog(markdown), [markdown]);
+  const [dialogOpen, setDialogOpen] = useState(false);
+
+  if (entries.length === 0) return null;
+
+  const shown = entries.slice(0, limit);
+  const hasMore = entries.length > shown.length;
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border border-border bg-card text-card-foreground",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 border-b border-border px-5 py-4">
+        <IconHistory className="h-4 w-4 text-muted-foreground" />
+        <h3 className="text-sm font-semibold">{title}</h3>
+      </div>
+      <div className="px-5 py-4">
+        <ChangelogEntries entries={shown} emptyText="No updates yet." />
+        {hasMore && (
+          <button
+            type="button"
+            onClick={() => setDialogOpen(true)}
+            className="mt-4 text-sm font-medium text-foreground underline underline-offset-2"
+          >
+            View all updates
+          </button>
+        )}
+      </div>
+      <ChangelogDialog
+        open={dialogOpen}
+        onOpenChange={setDialogOpen}
+        markdown={markdown}
+        title={title}
+      />
+    </div>
+  );
+}
+
+export { parseChangelog };
+export type { ChangelogEntry };

package/corpus/core/src/client/client-surface.ts

@@ -0,0 +1,41 @@
+/**
+ * The runtime shell the web UI is rendering inside. Used as pass-through
+ * feedback metadata so form owners can tell whether a submission came from the
+ * Agent Native desktop app (Electron), a Tauri desktop shell (e.g. Clips), or a
+ * plain browser — without surfacing it as a visible form field.
+ */
+export type ClientSurface = "web" | "electron" | "tauri";
+
+interface SurfaceGlobals {
+  // Tauri v2 always injects this into the webview; `__TAURI__` only exists when
+  // the app opts into `withGlobalTauri`, so check both.
+  __TAURI_INTERNALS__?: unknown;
+  __TAURI__?: unknown;
+  // Exposed by the Agent Native desktop (Electron) preload bridges.
+  agentNativeDesktop?: unknown;
+  electronAPI?: unknown;
+}
+
+/**
+ * Best-effort, side-effect-free detection of the current client surface.
+ * Returns "web" during SSR and in any plain browser.
+ *
+ * Electron detection keys off the `AgentNativeDesktop` User-Agent token that the
+ * desktop shell appends app-wide (see `app.userAgentFallback`), plus the preload
+ * globals, so it stays specific to our app rather than every Electron webview.
+ */
+export function getClientSurface(): ClientSurface {
+  if (typeof window === "undefined") return "web";
+  const w = window as unknown as SurfaceGlobals;
+  if (w.__TAURI_INTERNALS__ || w.__TAURI__) return "tauri";
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent || "" : "";
+  if (
+    /AgentNativeDesktop/i.test(ua) ||
+    /\bElectron\b/i.test(ua) ||
+    w.agentNativeDesktop ||
+    w.electronAPI
+  ) {
+    return "electron";
+  }
+  return "web";
+}