@agent-native/core 0.69.0 → 0.70.0

package/corpus/templates/clips/server/routes/api/video/[recordingId].get.ts

@@ -49,6 +49,7 @@ import {
 import { getOrgContext } from "@agent-native/core/org";
 import { resolveAccess } from "@agent-native/core/sharing";
 import {
+  captureRouteError,
   getSession,
   runWithRequestContext,
   signShortLivedToken,
@@ -404,7 +405,56 @@ export default defineEventHandler(async (event: H3Event) => {
           setResponseStatus(event, upstream.status);
           return { error: upstream.error };
         }
-        return providerResponse(upstream);
+        // The provider answered, but with a server error (e.g. the CDN asset is
+        // broken and returns 5xx). Don't proxy an opaque upstream error — and
+        // don't risk reconstructing a Response from it, which previously threw
+        // and surfaced as an unhandled 500 on every request. Capture it so the
+        // broken asset is diagnosable, and return a clean 502.
+        if (upstream.status >= 500) {
+          captureRouteError(
+            new Error(
+              `Storage provider returned ${upstream.status} for recording media`,
+            ),
+            {
+              route: "api/video",
+              tags: {
+                mediaPath: "provider-proxy",
+                upstreamStatus: String(upstream.status),
+              },
+              extra: { recordingId },
+            },
+          );
+          setResponseStatus(event, 502);
+          setResponseHeader(
+            event,
+            "Cache-Control",
+            "private, max-age=0, no-store",
+          );
+          return {
+            error: "The recording's media could not be loaded from storage.",
+            upstreamStatus: upstream.status,
+          };
+        }
+        try {
+          return providerResponse(upstream);
+        } catch (err) {
+          // Reconstructing the proxied Response should not happen, but if it
+          // does, fail cleanly instead of as an unhandled 500.
+          captureRouteError(err, {
+            route: "api/video",
+            tags: { mediaPath: "provider-proxy-response" },
+            extra: { recordingId, upstreamStatus: String(upstream.status) },
+          });
+          setResponseStatus(event, 502);
+          setResponseHeader(
+            event,
+            "Cache-Control",
+            "private, max-age=0, no-store",
+          );
+          return {
+            error: "The recording's media could not be loaded from storage.",
+          };
+        }
       }
       const mimeType =
         typeof blob?.mimeType === "string" ? blob.mimeType : "video/webm";

package/corpus/templates/clips/shared/share-attribution.ts

@@ -0,0 +1,79 @@
+/**
+ * Viral attribution contract for shared Clips links.
+ *
+ * Shared clip URLs self-attribute so the signup funnel can be measured even
+ * when `document.referrer` is empty (desktop app, Slack, native clients, etc.).
+ * The framework captures first-touch from these params into a cookie and
+ * enriches the `signup` event; Clips' job is to (a) tag share/embed URLs and
+ * (b) emit funnel events from the public share page.
+ *
+ * Contract strings are centralized here so the minting side (share dialog) and
+ * the measuring side (public share page) cannot drift apart.
+ *
+ * Privacy: `via` must be a non-PII stable id (e.g. the owner's user id), never
+ * an email. Omit `via` rather than leak PII into a public URL or event.
+ */
+
+/** Fixed referral source for clip shares. */
+export const CLIP_SHARE_REF = "clip_share";
+
+/** Query param names that carry attribution. */
+export const REF_PARAM = "ref";
+export const VIA_PARAM = "via";
+
+/**
+ * Append `ref=clip_share` (and `via=<ownerId>` when a non-PII owner id is
+ * known) to an absolute share/embed URL, preserving any existing query params.
+ * Returns the input unchanged when it isn't a parseable absolute URL.
+ */
+export function withShareAttribution(
+  url: string,
+  ownerId?: string | null,
+): string {
+  if (!url) return url;
+  try {
+    const parsed = new URL(url);
+    parsed.searchParams.set(REF_PARAM, CLIP_SHARE_REF);
+    const owner = (ownerId ?? "").trim();
+    if (owner) parsed.searchParams.set(VIA_PARAM, owner);
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+export type ShareAttribution = {
+  ref: string | undefined;
+  via: string | undefined;
+};
+
+/**
+ * Read `ref`/`via` from a query string (e.g. `window.location.search`). Falls
+ * back to `ref=clip_share` so downstream attribution stays meaningful even when
+ * the visitor arrived via a link that lost the param.
+ */
+export function readShareAttribution(search: string): ShareAttribution {
+  let ref: string | undefined;
+  let via: string | undefined;
+  try {
+    const params = new URLSearchParams(search ?? "");
+    ref = params.get(REF_PARAM) ?? undefined;
+    via = params.get(VIA_PARAM) ?? undefined;
+  } catch {
+    // Ignore malformed query strings — fall through to the default below.
+  }
+  return { ref: ref || CLIP_SHARE_REF, via: via || undefined };
+}
+
+/**
+ * Build the attribution-forwarding signup path so attribution survives even if
+ * cookies are blocked. The framework also captures these params on the
+ * `/signup` page load.
+ */
+export function buildSignupAttributionQuery(via?: string | null): string {
+  const params = new URLSearchParams();
+  params.set(REF_PARAM, CLIP_SHARE_REF);
+  const owner = (via ?? "").trim();
+  if (owner) params.set(VIA_PARAM, owner);
+  return params.toString();
+}

package/corpus/templates/content/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Content are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Content — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/content/app/root.tsx

@@ -26,6 +26,7 @@ import {
 } from "@agent-native/core/client";
 import { useDbSync } from "./hooks/use-db-sync";
 import { useNavigationState } from "./hooks/use-navigation-state";
+import changelog from "../CHANGELOG.md?raw";
 import type { LinksFunction } from "react-router";
 import stylesheet from "./global.css?url";
 import { configureTracking } from "@agent-native/core/client";
@@ -247,7 +248,12 @@ export default function Root() {
     >
       <AppSetup />
       <Toaster />
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="content"
+      >
         <CommandMenu.Group heading="Content">
           <CommandMenu.Item onSelect={() => {}}>
             Search documents

package/corpus/templates/design/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Design are documented here. Open it any time
+from the command menu (Cmd+K → "What's new") or from Settings.
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Design — a changelog now lives in the command menu (Cmd+K) and in Settings.

package/corpus/templates/design/actions/generate-design.ts

@@ -29,6 +29,10 @@ export default defineAction({
     "The agent calls this after generating HTML/CSS/JSX content to persist it " +
     "as files in the design project. Creates or updates files as needed. " +
     "Returns the saved files and design URL path for iframe rendering. " +
+    "Keep the first save compact and working; for large designs, persist a minimal " +
+    "version then refine individual files with `edit-design` (search/replace) rather " +
+    "than resending a big multi-file payload — a single oversized payload can get cut " +
+    "off mid-stream and stall the turn. " +
     "Do not report a design as ready until this action succeeds.",
   schema: z.object({
     designId: z.string().describe("Design project ID to save content to"),

package/corpus/templates/design/app/root.tsx

@@ -14,6 +14,7 @@ import {
   configureTracking,
 } from "@agent-native/core/client";
 import { IconSun, IconMoon } from "@tabler/icons-react";
+import changelog from "../CHANGELOG.md?raw";
 import { Toaster } from "@/components/ui/sonner";
 import { Layout as AppLayout } from "@/components/layout/Layout";
 import type { LinksFunction } from "react-router";
@@ -99,7 +100,12 @@ export default function Root() {
     <AppProviders queryClient={queryClient}>
       <DbSyncSetup />
       <Toaster richColors position="bottom-left" />
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="design"
+      >
         <CommandMenu.Group heading="Actions">
           <CommandMenu.Item onSelect={() => {}}>Search</CommandMenu.Item>
         </CommandMenu.Group>

package/corpus/templates/design/app/routes/settings.tsx

@@ -1,4 +1,9 @@
-import { SettingsPanel, useDevMode } from "@agent-native/core/client";
+import {
+  SettingsPanel,
+  useDevMode,
+  ChangelogSettingsCard,
+} from "@agent-native/core/client";
+import changelog from "../../CHANGELOG.md?raw";
 
 export function meta() {
   return [{ title: "Settings — Design" }];
@@ -8,12 +13,15 @@ export default function SettingsRoute() {
   const { isDevMode, canToggle, setDevMode } = useDevMode();
 
   return (
-    <div className="flex h-full min-h-0 flex-col bg-background">
+    <div className="flex h-full min-h-0 flex-col overflow-y-auto bg-background">
       <SettingsPanel
         isDevMode={isDevMode}
         onToggleDevMode={() => setDevMode(!isDevMode)}
         showDevToggle={canToggle}
       />
+      <div className="mx-auto w-full max-w-2xl px-4 pb-8">
+        <ChangelogSettingsCard markdown={changelog} />
+      </div>
     </div>
   );
 }

package/corpus/templates/dispatch/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Dispatch are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Dispatch — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/dispatch/app/root.tsx

@@ -25,6 +25,7 @@ import { useTheme } from "next-themes";
 import { Layout as AppLayout } from "@agent-native/dispatch/components";
 import type { LinksFunction } from "react-router";
 import { dispatchExtensions } from "./dispatch-extensions";
+import changelog from "../CHANGELOG.md?raw";
 import stylesheet from "./global.css?url";
 
 configureTracking({
@@ -166,7 +167,12 @@ function AppContent() {
   return (
     <>
       <DbSyncSetup />
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="dispatch"
+      >
         <CommandMenu.Group heading="Actions">
           <CommandMenu.Item onSelect={() => {}}>Search</CommandMenu.Item>
         </CommandMenu.Group>

package/corpus/templates/forms/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Forms are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Forms — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/forms/app/root.tsx

@@ -27,6 +27,7 @@ import {
   setClientAppState,
 } from "@agent-native/core/client";
 import type { LinksFunction } from "react-router";
+import changelog from "../CHANGELOG.md?raw";
 import stylesheet from "./global.css?url";
 import { TAB_ID } from "@/lib/tab-id";
 
@@ -198,7 +199,12 @@ export default function Root() {
       <NavigationStateSync />
       <UrlStateSync />
       <OpenLinkInterceptor />
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="forms"
+      >
         <CommandMenu.Group heading="Forms">
           <CommandMenu.Item onSelect={() => {}}>Search forms</CommandMenu.Item>
         </CommandMenu.Group>

package/corpus/templates/macros/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Macros are documented here. Open it any
+time from the command menu (Cmd+K → "What's new").
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Macros — a changelog now lives in the command menu (Cmd+K).

package/corpus/templates/macros/app/root.tsx

@@ -17,6 +17,7 @@ import { IconSun, IconMoon } from "@tabler/icons-react";
 import { TAB_ID } from "@/lib/tab-id";
 import { AppLayout } from "@/components/layout/AppLayout";
 import type { LinksFunction } from "react-router";
+import changelog from "../CHANGELOG.md?raw";
 import stylesheet from "./global.css?url";
 
 configureTracking({
@@ -124,7 +125,12 @@ export default function Root() {
       toaster={<Toaster richColors position="bottom-left" />}
     >
       <DbSyncSetup />
-      <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen}>
+      <CommandMenu
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        changelog={changelog}
+        changelogKey="macros"
+      >
         <CommandMenu.Group heading="Actions">
           <CommandMenu.Item onSelect={() => {}}>Search</CommandMenu.Item>
         </CommandMenu.Group>

package/corpus/templates/mail/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Mail are documented here. Open it any
+time from the command menu (Cmd+K → "What's new") or from Settings.
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Mail — a changelog now lives in the command menu (Cmd+K) and in Settings.

package/corpus/templates/mail/app/components/layout/CommandPalette.tsx

@@ -25,6 +25,7 @@ import { CommandMenu } from "@agent-native/core/client";
 import { useTheme } from "next-themes";
 import { useSettings, useUpdateSettings } from "@/hooks/use-emails";
 import { getResolvedTheme } from "@/lib/theme";
+import changelog from "../../../CHANGELOG.md?raw";
 
 interface CommandPaletteProps {
   open: boolean;
@@ -91,6 +92,8 @@ export function CommandPalette({
       open={open}
       onOpenChange={onOpenChange}
       placeholder="Type a command or ask AI..."
+      changelog={changelog}
+      changelogKey="mail"
     >
       <CommandMenu.Group heading="Actions">
         <CommandMenu.Item

package/corpus/templates/mail/app/pages/SettingsPage.tsx

@@ -6,8 +6,10 @@ import {
   useActionMutation,
   useChatModels,
   useChangeVersions,
+  ChangelogSettingsCard,
 } from "@agent-native/core/client";
 import { appApiPath } from "@agent-native/core/client";
+import changelog from "../../CHANGELOG.md?raw";
 import {
   IconUsers,
   IconPlus,
@@ -24,6 +26,7 @@ import {
   IconSignature,
   IconFilter,
   IconInfoCircle,
+  IconHistory,
 } from "@tabler/icons-react";
 import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
@@ -1379,9 +1382,31 @@ function SlackIntakeSection() {
   );
 }
 
+// ─── What's New Section ──────────────────────────────────────────────────────
+
+function WhatsNewSection() {
+  return (
+    <div className="flex-1 overflow-y-auto p-4 sm:p-8">
+      <div className="mb-6">
+        <h2 className="text-[16px] font-semibold text-foreground">
+          What's new
+        </h2>
+        <p className="mt-0.5 text-[13px] text-muted-foreground">
+          Recent user-facing changes to Agent-Native Mail.
+        </p>
+      </div>
+
+      <div className="max-w-2xl">
+        <ChangelogSettingsCard markdown={changelog} />
+      </div>
+    </div>
+  );
+}
+
 // ─── Settings Page ────────────────────────────────────────────────────────────
 
 type SettingsSection =
+  | "whats-new"
   | "drafting"
   | "automations"
   | "gmail-filters"
@@ -1395,6 +1420,7 @@ const navItems: {
   label: string;
   icon: React.ComponentType<{ className?: string }>;
 }[] = [
+  { id: "whats-new", label: "What's new", icon: IconHistory },
   { id: "drafting", label: "Drafting", icon: IconSignature },
   { id: "automations", label: "Automations", icon: IconBolt },
   { id: "gmail-filters", label: "Gmail Filters", icon: IconFilter },
@@ -1464,6 +1490,7 @@ export function SettingsPage() {
 
       {/* Right content panel */}
       <div className="flex flex-1 overflow-hidden bg-background">
+        {activeSection === "whats-new" && <WhatsNewSection />}
         {activeSection === "drafting" && <DraftingSection />}
         {activeSection === "automations" && <AutomationsSection />}
         {activeSection === "gmail-filters" && <GmailFiltersSection />}

package/corpus/templates/plan/.agents/skills/visual-plan/SKILL.md

@@ -88,13 +88,14 @@ surface.
   approach and options in the plan. Ask a clarifying question only when an
   ambiguity would change the design and you cannot resolve it from the code; use
   the host agent's normal ask-user-question flow and batch 2-4 high-leverage
-  questions before finalizing. Do not call `create-visual-questions` from
-  `/visual-plan`. Otherwise state the assumption explicitly and proceed, and
-  keep anything unresolved in the plan's single bottom `question-form` Open
-  Questions block. For complex plans, do a final open-question pass before
-  handoff: if a decision would affect architecture, scope, UX, data shape, or
-  rollout, either decide it in the plan with rationale or put it in that bottom
-  form with a recommended default.
+  questions before finalizing. Do not call `create-visual-questions` for
+  ordinary clarification or preflight; reserve it for the visual-intake mode when
+  the user explicitly asks for a visual intake questionnaire. Otherwise state the
+  assumption explicitly and proceed, and keep anything unresolved in the plan's
+  single bottom `question-form` Open Questions block. For complex plans, do a
+  final open-question pass before handoff: if a decision would affect
+  architecture, scope, UX, data shape, or rollout, either decide it in the plan
+  with rationale or put it in that bottom form with a recommended default.
 - **The plan is the approval gate.** After surfacing it, ask the user to review
   and approve before you write code, and name which files/areas the work touches.
   Presenting the plan and requesting sign-off is the approval step — do not ask a
@@ -139,6 +140,11 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
 
 ## Core Workflow
 
+This section describes the default hosted Plan MCP workflow. If
+`AGENT_NATIVE_PLANS_MODE=local-files` is set, or the user asks for fully local
+files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
+forward only the code-research and plan-composition guidance here.
+
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
    wide exploration when useful, gather the info needed, and ask native
    clarifying questions as needed before generating the plan. If a source plan
@@ -185,11 +191,13 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
    backend, data, multi-file, or risky), also kick off the self-review pass in
    **Self-Review Before Handoff** while the user reads, instead of blocking the
    handoff on it.
-5. Call `get-plan-feedback` before editing, after review, after any long pause,
+5. For hosted plans, call `get-plan-feedback` before editing, after review,
+   after any long pause,
    and before the final response. Treat `anchorDetails`, resolver intent, recent
    review events, and any focused screenshots from browser handoff as the source
    of truth for exactly what changed and exactly what each comment points at.
-6. Apply changes with `update-visual-plan`, preferring targeted `contentPatches`.
+6. For hosted plans, apply changes with `update-visual-plan`, preferring
+   targeted `contentPatches`.
    Treat the top-level `content` payload as a full replacement, not a merge; do
    not send a partial `content` object to add a canvas or one block. If a full
    replacement is unavoidable, first read the complete plan source/content, carry
@@ -197,8 +205,8 @@ is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
    afterward so the document body was not truncated. When the user wants
    source-control friendly edits, use `patch-visual-plan-source` against the MDX
    files instead of regenerating the plan.
-7. Export with `export-visual-plan` only when the user wants a shareable receipt
-   or repo-check-in artifacts.
+7. For hosted plans, export with `export-visual-plan` only when the user wants a
+   shareable receipt or repo-check-in artifacts.
 
 ## Self-Review Before Handoff
 
@@ -394,11 +402,12 @@ The local-files contract is:
   wants the artifact checked into the repo, or use a repo-ignored/temporary
   folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/`
   when it should not be checked in. The folder contains `plan.mdx`, optional
-  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`.
-- Run `npx @agent-native/core@latest plan local check --dir plans/<slug>`
-  before serving, then run
-  `npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open`.
-  Report the returned local bridge URL from stdout or `plans/<slug>/.plan-url`.
+  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Use
+  that exact chosen folder as `<plan-dir>` in every local CLI command below.
+- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
+  serving, then run
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind plan --open`.
+  Report the returned local bridge URL from stdout or `<plan-dir>/.plan-url`.
   Treat `.plan-url` as a local token file and do not commit it. The URL opens
   the hosted Plan UI but reads from the localhost bridge on this machine, so it
   is not shareable across machines. On macOS, `--open` prefers Chromium browsers;
@@ -407,7 +416,7 @@ The local-files contract is:
   running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route
   is also valid.
 - For headless verification, run
-  `npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan`.
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind plan`.
   It starts the bridge, checks the private-network preflight and JSON payload,
   prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
   the `bridgeUrl` from the verify/serve JSON to read the concrete validation
@@ -429,6 +438,11 @@ otherwise approved by the user.
 
 ## Interpreting comment anchors
 
+This section applies to hosted plans with `get-plan-feedback` /
+`update-visual-plan`. In local-files mode, do not call hosted feedback or update
+tools; interpret file/chat feedback directly, edit the MDX files, rerun the
+local bridge check/serve/verify command, and report the new local URL.
+
 `get-plan-feedback` returns rich anchors — read them before acting on any comment.
 
 - **Coordinate frames.** `targetX`/`targetY` are percentages *within* the

package/corpus/templates/plan/.agents/skills/visual-plan/references/wireframe.md

@@ -135,12 +135,15 @@ no labels or copy. The renderer drops borders, sketch, and color into the
 skeleton register automatically. Never escape to a `custom-html` document block
 to fake a loader.
 
-**Editing an existing mockup.** To change one element, text, or color in an
-existing html mockup, call `update-visual-plan`
-with `contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
 replace }] }]`. Each `find` is a unique snippet of the current html (read it
 first with `get-visual-plan`); set `all: true` on an edit to replace every
-occurrence. The result is re-sanitized.
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
 
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing