@agent-native/core 0.125.0 → 0.126.0

package/corpus/README.md

@@ -30,4 +30,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 - core files: 1737
 - toolkit files: 160
-- template files: 6804
+- template files: 6806

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @agent-native/core
 
+## 0.126.0
+
+### Minor Changes
+
+- b99b899: **Breaking:** rename the `registerShareableResource` resolver `getShareEmailLogoUrl` (added in 0.125.0) to `getLogoUrl`. Update any registration that used the old name.
+
+  Add `getBrandName`, `getSender`, and `getHeroHtml` resolvers to `registerShareableResource`, plus an optional `heroHtml` on `renderEmail` and `fromName` on `sendEmail`. Share-notification emails can now render a template-owned preview block above the CTA (injected verbatim, so a template supplies its own markup — e.g. a video thumbnail with a play badge), override the brand name shown beside the logo, and appear to come from the sharing user ("Alice via Clips") with replies routed to them while keeping the configured domain-verified sending address so SPF/DKIM still pass.
+
 ## 0.125.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.125.0",
+  "version": "0.126.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/server/email-template.ts

@@ -36,6 +36,12 @@ export interface RenderEmailArgs {
   paragraphs: string[];
   /** Primary call-to-action rendered as a real button. */
   cta?: EmailCta;
+  /**
+   * Optional trusted HTML injected above the CTA — e.g. a template-owned video
+   * thumbnail with a play badge. Injected verbatim, so only pass markup built
+   * by app/template code (never raw user input), and escape any dynamic values.
+   */
+  heroHtml?: string;
   /** Small muted text under the CTA (e.g. expiry note). */
   footer?: string;
   /** Optional app name shown beside the framework logo. */
@@ -108,6 +114,12 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
   const ctaFg = brand ? "#ffffff" : "#0a0a0c";
   const linkColor = brand ?? "#a1a1aa";
 
+  // Trusted markup supplied by the caller (template code, not user input),
+  // injected as-is so a template can own app-specific previews (e.g. a video
+  // thumbnail with a play badge). Callers are responsible for escaping any
+  // dynamic values they interpolate.
+  const heroHtml = args.heroHtml ?? "";
+
   const paragraphsHtml = args.paragraphs
     .map(
       (p) =>
@@ -174,6 +186,7 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
                   ${escapeHtml(args.heading)}
                 </h1>
                 ${paragraphsHtml}
+                ${heroHtml}
                 ${ctaHtml}
                 ${footerHtml}
               </td>

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

@@ -30,6 +30,13 @@ export interface SendEmailArgs {
   html: string;
   text?: string;
   from?: string;
+  /**
+   * Display-name-only override. Keeps the configured (domain-verified) sending
+   * address and just changes the name shown to the recipient, e.g.
+   * "Alice via Clips". Ignored when `from` is set. Prefer this over `from` for
+   * per-user senders: putting a user's own address in `From` breaks SPF/DKIM.
+   */
+  fromName?: string;
   cc?: string | string[];
   replyTo?: string;
   inReplyTo?: string;
@@ -110,9 +117,14 @@ export async function getEmailProvider(): Promise<EmailProvider> {
 function getFromAddress(
   config: EmailTransportConfig,
   override?: string,
+  fromName?: string,
 ): string {
-  const explicit = override || config.from;
-  if (explicit) return explicit;
+  if (override) return override;
+  const base = config.from ?? defaultFromAddress(config);
+  return fromName ? withDisplayName(base, fromName) : base;
+}
+
+function defaultFromAddress(config: EmailTransportConfig): string {
   // Resend lets unverified accounts send from its sandbox domain; SendGrid
   // does not, so falling back there would cause silent 403s at runtime.
   if (config.provider === "sendgrid") {
@@ -123,6 +135,21 @@ function getFromAddress(
   return "Agent Native <onboarding@resend.dev>";
 }
 
+/**
+ * Swap the display name while keeping the verified address. The name is
+ * sanitized and quoted because it lands in a header: CR/LF would allow header
+ * injection, and quotes/angle brackets would break address parsing.
+ */
+function withDisplayName(from: string, name: string): string {
+  const safe = name
+    .replace(/[\r\n"<>\\]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!safe) return from;
+  const address = from.match(/<([^>]+)>/)?.[1]?.trim() ?? from.trim();
+  return `"${safe}" <${address}>`;
+}
+
 async function sendEmailWithSignal(
   args: SendEmailArgs,
   signal?: AbortSignal,
@@ -130,7 +157,7 @@ async function sendEmailWithSignal(
   const config = await resolveEmailTransport();
   signal?.throwIfAborted();
   const provider = config.provider;
-  const from = getFromAddress(config, args.from);
+  const from = getFromAddress(config, args.from, args.fromName);
   const attachments = resolveAttachments(args);
 
   if (provider === "resend") {
@@ -270,10 +297,19 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
 
 function parseSendGridFrom(from: string): { email: string; name?: string } {
   const m = from.match(/^\s*(.*?)\s*<(.+)>\s*$/);
-  if (m && m[2]) return { name: m[1] || undefined, email: m[2] };
+  if (m && m[2]) return { name: unquoteDisplayName(m[1]), email: m[2] };
   return { email: from.trim() };
 }
 
+function unquoteDisplayName(name: string): string | undefined {
+  const trimmed = name.trim();
+  const unquoted =
+    trimmed.startsWith('"') && trimmed.endsWith('"')
+      ? trimmed.slice(1, -1).replace(/\\(.)/g, "$1")
+      : trimmed;
+  return unquoted || undefined;
+}
+
 function stripHtml(html: string): string {
   return html
     .replace(/<br\s*\/?>/gi, "\n")

package/corpus/core/src/sharing/actions/share-resource.ts

@@ -8,6 +8,7 @@ import { renderEmail, emailStrong } from "../../server/email-template.js";
 import { sendEmail, isEmailConfigured } from "../../server/email.js";
 import { invalidateCollabAccessCache } from "../../server/poll.js";
 import { getRequestUserEmail } from "../../server/request-context.js";
+import { getUserProfile } from "../../user-profile/store.js";
 import { assertAccess, ForbiddenError } from "../access.js";
 import { requireShareableResource } from "../registry.js";
 import {
@@ -298,10 +299,9 @@ export default defineAction({
         const appName =
           process.env.APP_NAME || process.env.VITE_APP_NAME || "Agent Native";
         let brandLogoUrl: string | undefined;
-        if (reg.getShareEmailLogoUrl) {
+        if (reg.getLogoUrl) {
           try {
-            brandLogoUrl =
-              (await reg.getShareEmailLogoUrl(resource)) ?? undefined;
+            brandLogoUrl = (await reg.getLogoUrl(resource)) ?? undefined;
           } catch (err) {
             console.error(
               "[share-resource] brand logo resolver failed; using default logo:",
@@ -309,9 +309,51 @@ export default defineAction({
             );
           }
         }
+        let brandName = appName;
+        if (reg.getBrandName) {
+          try {
+            brandName = (await reg.getBrandName(resource))?.trim() || appName;
+          } catch (err) {
+            console.error(
+              "[share-resource] brand name resolver failed; using app name:",
+              err,
+            );
+          }
+        }
+        let fromName: string | undefined;
+        let replyTo: string | undefined;
+        if (reg.getSender) {
+          try {
+            const sender = await reg.getSender(resource, {
+              sender: await getUserProfile(actor),
+            });
+            fromName = sender?.fromName?.trim() || undefined;
+            replyTo = sender?.replyTo?.trim() || undefined;
+          } catch (err) {
+            console.error(
+              "[share-resource] sender resolver failed; using default sender:",
+              err,
+            );
+          }
+        }
+        let heroHtml: string | undefined;
+        if (reg.getHeroHtml) {
+          try {
+            heroHtml =
+              (await reg.getHeroHtml(resource, {
+                href: notificationUrl,
+                alt: resourceTitle,
+              })) ?? undefined;
+          } catch (err) {
+            console.error(
+              "[share-resource] hero html resolver failed; omitting preview:",
+              err,
+            );
+          }
+        }
         const subject = `${actor} shared "${resourceTitle}" with you on ${appName}`;
         const { html, text } = renderEmail({
-          brandName: appName,
+          brandName,
           brandLogoUrl,
           preheader: subject,
           heading: "You've been given access",
@@ -319,10 +361,18 @@ export default defineAction({
             `${emailStrong(actor)} has shared the ${reg.displayName} ${emailStrong(resourceTitle)} with you as a ${emailStrong(args.role)}.`,
             `Use the button below to open it. If prompted, sign in with ${emailStrong(principalId)}.`,
           ],
+          heroHtml,
           cta: { label: `Open ${reg.displayName}`, url: notificationUrl },
           footer: `You received this because ${actor} granted you ${args.role} access.`,
         });
-        await sendEmail({ to: principalId, subject, html, text });
+        await sendEmail({
+          to: principalId,
+          subject,
+          html,
+          text,
+          fromName,
+          replyTo,
+        });
       } catch (err) {
         console.error(
           "[share-resource] failed to send share notification:",

package/corpus/core/src/sharing/registry.ts

@@ -17,6 +17,8 @@
  *   });
  */
 
+import type { UserProfile } from "../user-profile/shared.js";
+
 export interface ShareableResourceRegistration {
   /** Stable identifier used across actions, UI, and analytics. e.g. "document". */
   type: string;
@@ -42,8 +44,46 @@ export interface ShareableResourceRegistration {
    * (e.g. the sharing org's own logo), or undefined to fall back. Receives the
    * resource row being shared so the template can scope the logo to its org.
    */
-  getShareEmailLogoUrl?: (
+  getLogoUrl?: (
+    resource: any,
+  ) => string | undefined | Promise<string | undefined>;
+  /**
+   * Optional resolver for the brand name shown beside the logo in the
+   * share-notification email header. Return a display name (e.g. the sharing
+   * org's name) to override the app name, or undefined to keep the default.
+   * Receives the resource row being shared.
+   */
+  getBrandName?: (
+    resource: any,
+  ) => string | undefined | Promise<string | undefined>;
+  /**
+   * Optional resolver for who the share-notification email appears to come
+   * from. `fromName` changes only the display name and keeps the configured,
+   * domain-verified sending address (e.g. "Alice via Clips"); `replyTo` routes
+   * replies to the sharer. `ctx.sender` is the account doing the sharing, so the
+   * template decides how to present them (name, email, avatar).
+   *
+   * Do not put a user's address in the sending address itself — SPF/DKIM sign
+   * the app's domain, so recipients would bounce or spam-filter it.
+   */
+  getSender?: (
+    resource: any,
+    ctx: { sender: UserProfile },
+  ) =>
+    | { fromName?: string; replyTo?: string }
+    | undefined
+    | Promise<{ fromName?: string; replyTo?: string } | undefined>;
+  /**
+   * Optional resolver for a preview block shown above the CTA in the
+   * share-notification email — e.g. a recording thumbnail with a play badge.
+   * Return trusted HTML (built by template code, dynamic values escaped) that
+   * is injected verbatim, or undefined to omit it. `ctx.href` is the resolved
+   * link to the resource; `ctx.alt` is its title. The template owns the entire
+   * preview markup so the generic share action stays app-agnostic.
+   */
+  getHeroHtml?: (
     resource: any,
+    ctx: { href: string; alt?: string },
   ) => string | undefined | Promise<string | undefined>;
   /**
    * Drizzle DB accessor from the template's server/db/index.ts. Required —

package/corpus/templates/assets/actions/edit-image.ts

@@ -1,9 +1,11 @@
 import { defineAction } from "@agent-native/core";
+import type { ActionRunContext } from "@agent-native/core/action";
 import { z } from "zod";
 
 import { IMAGE_MODELS, IMAGE_QUALITY_TIERS } from "../shared/api.js";
 import { getAssetOrThrow } from "./_helpers.js";
 import generateImage from "./generate-image.js";
+import { resolveLiveBatchContinuation } from "./variant-slots.js";
 
 export default defineAction({
   description:
@@ -24,26 +26,37 @@ export default defineAction({
     contextModeOverride: z.literal("off").optional(),
   }),
   parallelSafe: true,
-  run: async (args) => {
+  run: async (args, context?: ActionRunContext) => {
     const asset = await getAssetOrThrow(args.assetId);
-    return generateImage.run({
+    const continuation = await resolveLiveBatchContinuation({
+      threadId: context?.threadId,
       libraryId: asset.libraryId,
-      collectionId: asset.collectionId ?? undefined,
-      prompt: args.instruction,
-      aspectRatio: (asset.aspectRatio ?? "16:9") as any,
-      imageSize: (asset.imageSize ?? "2K") as any,
-      model: args.model,
-      tier: args.tier,
-      intent: "edit",
-      styleStrength: "balanced",
-      referenceAssetIds: [],
-      includeLogo: false,
-      groundingMode: "off",
-      subjectAssetId: asset.id,
-      slotId: args.slotId,
-      source: args.source,
-      callerAppId: args.callerAppId,
-      contextModeOverride: args.contextModeOverride,
     });
+    return generateImage.run(
+      {
+        libraryId: asset.libraryId,
+        collectionId:
+          asset.collectionId ?? continuation?.collectionId ?? undefined,
+        presetId: continuation?.presetId ?? undefined,
+        sessionId: continuation?.sessionId ?? undefined,
+        prompt: args.instruction,
+        aspectRatio: (asset.aspectRatio ?? "16:9") as any,
+        imageSize: (asset.imageSize ?? "2K") as any,
+        model: args.model,
+        tier: args.tier,
+        intent: "edit",
+        styleStrength: "balanced",
+        referenceAssetIds: [],
+        includeLogo: false,
+        groundingMode: "off",
+        subjectAssetId: asset.id,
+        slotId: args.slotId,
+        variantBatchId: continuation?.variantBatchId,
+        source: args.source,
+        callerAppId: args.callerAppId,
+        contextModeOverride: args.contextModeOverride,
+      },
+      context,
+    );
   },
 });

package/corpus/templates/assets/actions/refine-image.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import type { ActionRunContext } from "@agent-native/core/action";
 import { z } from "zod";
 
 import { parseJson } from "../server/lib/json.js";
@@ -8,6 +9,7 @@ import {
   requireGenerationSessionInLibrary,
 } from "./_helpers.js";
 import generateImage from "./generate-image.js";
+import { resolveLiveBatchContinuation } from "./variant-slots.js";
 
 export default defineAction({
   description:
@@ -31,19 +33,22 @@ export default defineAction({
     contextModeOverride: z.literal("off").optional(),
   }),
   parallelSafe: true,
-  run: async ({
-    assetId,
-    feedback,
-    presetId,
-    sessionId,
-    model,
-    aspectRatio,
-    imageSize,
-    slotId,
-    source,
-    callerAppId,
-    contextModeOverride,
-  }) => {
+  run: async (
+    {
+      assetId,
+      feedback,
+      presetId,
+      sessionId,
+      model,
+      aspectRatio,
+      imageSize,
+      slotId,
+      source,
+      callerAppId,
+      contextModeOverride,
+    },
+    context?: ActionRunContext,
+  ) => {
     const asset = await getAssetOrThrow(assetId);
     if (sessionId) {
       await requireGenerationSessionInLibrary(sessionId, asset.libraryId);
@@ -57,23 +62,32 @@ export default defineAction({
       "",
       "Preserve the strongest successful parts of the prior candidate unless the feedback contradicts them.",
     ].join("\n");
-    return generateImage.run({
+    const continuation = await resolveLiveBatchContinuation({
+      threadId: context?.threadId,
       libraryId: asset.libraryId,
-      collectionId: asset.collectionId ?? undefined,
-      presetId,
-      sessionId,
-      prompt,
-      aspectRatio: (aspectRatio ?? asset.aspectRatio ?? "16:9") as any,
-      imageSize: (imageSize ?? asset.imageSize ?? "2K") as any,
-      model: (model ?? asset.model ?? "gemini-3.1-flash-image") as any,
-      categories: metadata.category ? [metadata.category] : undefined,
-      includeLogo: false,
-      groundingMode: "auto",
-      sourceAssetId: asset.id,
-      slotId,
-      source,
-      callerAppId,
-      contextModeOverride,
     });
+    return generateImage.run(
+      {
+        libraryId: asset.libraryId,
+        collectionId:
+          asset.collectionId ?? continuation?.collectionId ?? undefined,
+        presetId: presetId ?? continuation?.presetId ?? undefined,
+        sessionId: sessionId ?? continuation?.sessionId ?? undefined,
+        prompt,
+        aspectRatio: (aspectRatio ?? asset.aspectRatio ?? "16:9") as any,
+        imageSize: (imageSize ?? asset.imageSize ?? "2K") as any,
+        model: (model ?? asset.model ?? "gemini-3.1-flash-image") as any,
+        categories: metadata.category ? [metadata.category] : undefined,
+        includeLogo: false,
+        groundingMode: "auto",
+        sourceAssetId: asset.id,
+        slotId,
+        variantBatchId: continuation?.variantBatchId,
+        source,
+        callerAppId,
+        contextModeOverride,
+      },
+      context,
+    );
   },
 });

package/corpus/templates/assets/actions/restyle-image.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import type { ActionRunContext } from "@agent-native/core/action";
 import { z } from "zod";
 
 import {
@@ -10,6 +11,7 @@ import {
 } from "../shared/api.js";
 import { getAssetOrThrow } from "./_helpers.js";
 import generateImage from "./generate-image.js";
+import { resolveLiveBatchContinuation } from "./variant-slots.js";
 
 export default defineAction({
   description:
@@ -38,30 +40,39 @@ export default defineAction({
     contextModeOverride: z.literal("off").optional(),
   }),
   parallelSafe: true,
-  run: async (args) => {
+  run: async (args, context?: ActionRunContext) => {
     const subject = await getAssetOrThrow(args.subjectAssetId);
     const prompt =
       args.prompt?.trim() ||
       "Apply this library's brand style to the subject image while preserving the subject, pose, composition, and framing.";
-    return generateImage.run({
+    const continuation = await resolveLiveBatchContinuation({
+      threadId: context?.threadId,
       libraryId: subject.libraryId,
-      collectionId: subject.collectionId ?? undefined,
-      presetId: args.presetId,
-      sessionId: args.sessionId,
-      prompt,
-      aspectRatio: (args.aspectRatio ?? subject.aspectRatio ?? "16:9") as any,
-      imageSize: (args.imageSize ?? subject.imageSize ?? "2K") as any,
-      model: args.model,
-      tier: args.tier,
-      intent: "restyle",
-      styleStrength: args.styleStrength,
-      includeLogo: false,
-      groundingMode: "auto",
-      subjectAssetId: subject.id,
-      slotId: args.slotId,
-      source: args.source,
-      callerAppId: args.callerAppId,
-      contextModeOverride: args.contextModeOverride,
     });
+    return generateImage.run(
+      {
+        libraryId: subject.libraryId,
+        collectionId:
+          subject.collectionId ?? continuation?.collectionId ?? undefined,
+        presetId: args.presetId ?? continuation?.presetId ?? undefined,
+        sessionId: args.sessionId ?? continuation?.sessionId ?? undefined,
+        prompt,
+        aspectRatio: (args.aspectRatio ?? subject.aspectRatio ?? "16:9") as any,
+        imageSize: (args.imageSize ?? subject.imageSize ?? "2K") as any,
+        model: args.model,
+        tier: args.tier,
+        intent: "restyle",
+        styleStrength: args.styleStrength,
+        includeLogo: false,
+        groundingMode: "auto",
+        subjectAssetId: subject.id,
+        slotId: args.slotId,
+        variantBatchId: continuation?.variantBatchId,
+        source: args.source,
+        callerAppId: args.callerAppId,
+        contextModeOverride: args.contextModeOverride,
+      },
+      context,
+    );
   },
 });

package/corpus/templates/assets/actions/variant-slots.ts

@@ -177,6 +177,32 @@ export async function readVariantState(
   return withVariantStateLock(() => readVariantStateUnlocked(scopeId));
 }
 
+// Iterations (refine/edit/restyle) are a continuation of what is already on
+// screen for this thread, not a new generation topic: they should append into
+// the live tray instead of tripping the "new batch/run" reset in
+// isSameVariantScope. Passing the current tray's batch/run id plus its
+// collection/preset/session back through keeps every isSameVariantScope check
+// satisfied.
+export async function resolveLiveBatchContinuation(input: {
+  threadId?: string | null;
+  libraryId: string;
+}): Promise<{
+  variantBatchId: string;
+  collectionId: string | null;
+  presetId: string | null;
+  sessionId: string | null;
+} | null> {
+  if (!input.threadId) return null;
+  const state = await readVariantState(input.threadId);
+  if (!state || state.libraryId !== input.libraryId) return null;
+  return {
+    variantBatchId: state.batchId ?? state.runId,
+    collectionId: state.collectionId ?? null,
+    presetId: state.presetId ?? null,
+    sessionId: state.sessionId ?? null,
+  };
+}
+
 export async function writeVariantState(
   state: AssetVariantState,
   scopeId?: string | null,