@agent-native/core 0.128.4 → 0.129.1

package/corpus/templates/analytics/app/components/dashboard/DashboardPanelSkeleton.tsx

@@ -1,19 +1,10 @@
 import type { ComponentProps } from "react";
 
 import { Skeleton } from "@/components/ui/skeleton";
-import { cn } from "@/lib/utils";
 
 export function DashboardPanelSkeleton({
   className,
   ...props
 }: ComponentProps<typeof Skeleton>) {
-  return (
-    <Skeleton
-      {...props}
-      className={cn(
-        "dashboard-panel-skeleton bg-muted-foreground/14",
-        className,
-      )}
-    />
-  );
+  return <Skeleton {...props} className={className} />;
 }

package/corpus/templates/analytics/app/global.css

@@ -138,37 +138,6 @@
   }
 }
 
-.dashboard-panel-skeleton {
-  background-color: hsl(var(--muted-foreground) / 0.14);
-  background-image: linear-gradient(
-    105deg,
-    transparent 28%,
-    hsl(var(--foreground) / 0.025) 44%,
-    hsl(var(--foreground) / 0.06) 50%,
-    hsl(var(--foreground) / 0.025) 56%,
-    transparent 72%
-  );
-  background-size: 28rem 100%;
-  background-repeat: repeat;
-  animation: dashboard-panel-skeleton-shimmer 2.6s linear infinite;
-}
-
-@keyframes dashboard-panel-skeleton-shimmer {
-  0% {
-    background-position: 0 0;
-  }
-
-  100% {
-    background-position: 28rem 0;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .dashboard-panel-skeleton {
-    animation: none;
-  }
-}
-
 .analytics-mobile-nav {
   height: 2.75rem;
   min-height: 2.75rem;

package/corpus/templates/analytics/app/lib/sql-query.ts

@@ -1,6 +1,9 @@
 import { callAction } from "@agent-native/core/client/hooks";
 import { DASHBOARD_REPORT_ACTION_TIMEOUT_MS } from "@shared/dashboard-report-timeouts";
-import { MAX_CONCURRENT_SQL_QUERIES } from "@shared/sql-query-limits";
+import {
+  MAX_CONCURRENT_FIRST_PARTY_SQL_QUERIES,
+  MAX_CONCURRENT_SQL_QUERIES,
+} from "@shared/sql-query-limits";
 import { useQuery } from "@tanstack/react-query";
 
 import type { DataSourceType } from "@/pages/adhoc/sql-dashboard/types";
@@ -22,8 +25,30 @@ type PendingSqlQuerySlot = {
   onAbort: () => void;
 };
 
-let activeSqlQueries = 0;
-const pendingSqlQuerySlots: PendingSqlQuerySlot[] = [];
+type SqlQueryLane = "first-party" | "external";
+
+type SqlQuerySlotPool = {
+  active: number;
+  limit: number;
+  pending: PendingSqlQuerySlot[];
+};
+
+const sqlQuerySlotPools: Record<SqlQueryLane, SqlQuerySlotPool> = {
+  "first-party": {
+    active: 0,
+    limit: MAX_CONCURRENT_FIRST_PARTY_SQL_QUERIES,
+    pending: [],
+  },
+  external: {
+    active: 0,
+    limit: MAX_CONCURRENT_SQL_QUERIES,
+    pending: [],
+  },
+};
+
+function sqlQueryLane(source: DataSourceType): SqlQueryLane {
+  return source === "first-party" ? "first-party" : "external";
+}
 
 function createAbortError(): Error {
   if (typeof DOMException !== "undefined") {
@@ -34,49 +59,50 @@ function createAbortError(): Error {
   return error;
 }
 
-function createSqlQueryRelease(): () => void {
+function createSqlQueryRelease(pool: SqlQuerySlotPool): () => void {
   let released = false;
   return () => {
     if (released) return;
     released = true;
-    activeSqlQueries = Math.max(0, activeSqlQueries - 1);
-    drainSqlQuerySlots();
+    pool.active = Math.max(0, pool.active - 1);
+    drainSqlQuerySlots(pool);
   };
 }
 
-function drainSqlQuerySlots(): void {
-  while (
-    activeSqlQueries < MAX_CONCURRENT_SQL_QUERIES &&
-    pendingSqlQuerySlots.length > 0
-  ) {
-    const pending = pendingSqlQuerySlots.shift();
+function drainSqlQuerySlots(pool: SqlQuerySlotPool): void {
+  while (pool.active < pool.limit && pool.pending.length > 0) {
+    const pending = pool.pending.shift();
     if (!pending) return;
     pending.signal?.removeEventListener("abort", pending.onAbort);
     if (pending.signal?.aborted) {
       pending.reject(createAbortError());
       continue;
     }
-    activeSqlQueries += 1;
-    pending.resolve(createSqlQueryRelease());
+    pool.active += 1;
+    pending.resolve(createSqlQueryRelease(pool));
   }
 }
 
-async function acquireSqlQuerySlot(signal?: AbortSignal): Promise<() => void> {
+async function acquireSqlQuerySlot(
+  source: DataSourceType,
+  signal?: AbortSignal,
+): Promise<() => void> {
   if (signal?.aborted) throw createAbortError();
+  const pool = sqlQuerySlotPools[sqlQueryLane(source)];
   return new Promise((resolve, reject) => {
     const pending: PendingSqlQuerySlot = {
       resolve,
       reject,
       signal,
       onAbort: () => {
-        const index = pendingSqlQuerySlots.indexOf(pending);
-        if (index >= 0) pendingSqlQuerySlots.splice(index, 1);
+        const index = pool.pending.indexOf(pending);
+        if (index >= 0) pool.pending.splice(index, 1);
         reject(createAbortError());
       },
     };
     signal?.addEventListener("abort", pending.onAbort, { once: true });
-    pendingSqlQuerySlots.push(pending);
-    drainSqlQuerySlots();
+    pool.pending.push(pending);
+    drainSqlQuerySlots(pool);
   });
 }
 
@@ -91,7 +117,7 @@ export async function executeSqlQuery(
   signal?: AbortSignal,
   options?: { reportScreenshot?: boolean },
 ): Promise<SqlQueryResult> {
-  const release = await acquireSqlQuerySlot(signal);
+  const release = await acquireSqlQuerySlot(source, signal);
   let data: DashboardPanelQueryResponse;
   try {
     data = await callAction<DashboardPanelQueryResponse>(

package/corpus/templates/analytics/changelog/2026-07-28-analytics-dashboard-loading-states-now-use-a-simpler-standar.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-28
+---
+
+Analytics dashboard loading states now use a simpler standard placeholder.

package/corpus/templates/analytics/changelog/2026-07-28-analytics-dashboards-now-load-first-party-charts-reliably-in.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Analytics dashboards now load first-party charts reliably instead of timing out under concurrent load.

package/corpus/templates/analytics/server/lib/first-party-analytics-cache.ts

@@ -26,6 +26,7 @@ interface L1Entry {
 
 const CACHE_TTL_MS = 5 * 60 * 1000;
 const MAX_L1_ENTRIES = 500;
+const CACHE_IO_TIMEOUT_MS = 1_000;
 
 const l1Cache = new Map<string, L1Entry>();
 // De-dupes identical concurrent cache misses (e.g. the same panel query fired
@@ -70,7 +71,7 @@ function setL1(key: string, result: AnalyticsQueryResult): void {
 
 async function getL2(
   key: string,
-  timeoutMs?: number,
+  deadlineAt: number,
 ): Promise<AnalyticsQueryResult | null> {
   try {
     const db = getDbExec();
@@ -78,7 +79,8 @@ async function getL2(
     const { rows } = await db.execute({
       sql: "SELECT result FROM first_party_analytics_cache WHERE key = ? AND expires_at > ?",
       args: [key, nowIso],
-      timeoutMs,
+      timeoutMs: cacheIoTimeoutMs(deadlineAt),
+      maxAttempts: 1,
     });
     if (!rows.length) return null;
     const raw = (rows[0] as { result: string }).result;
@@ -93,23 +95,24 @@ async function setL2(
   key: string,
   sql: string,
   result: AnalyticsQueryResult,
-  timeoutMs?: number,
+  deadlineAt: number,
 ): Promise<void> {
   try {
     const db = getDbExec();
     const now = new Date();
     const expiresAt = new Date(now.getTime() + CACHE_TTL_MS);
     const serialized = JSON.stringify(result);
-    // Upsert via delete+insert to stay dialect-agnostic (SQLite/Postgres).
     await db.execute({
-      sql: "DELETE FROM first_party_analytics_cache WHERE key = ?",
-      args: [key],
-      timeoutMs,
-    });
-    await db.execute({
-      sql: "INSERT INTO first_party_analytics_cache (key, sql, result, created_at, expires_at) VALUES (?, ?, ?, ?, ?)",
+      sql: `INSERT INTO first_party_analytics_cache (key, sql, result, created_at, expires_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+          sql = excluded.sql,
+          result = excluded.result,
+          created_at = excluded.created_at,
+          expires_at = excluded.expires_at`,
       args: [key, sql, serialized, now.toISOString(), expiresAt.toISOString()],
-      timeoutMs,
+      timeoutMs: cacheIoTimeoutMs(deadlineAt),
+      maxAttempts: 1,
     });
     // Opportunistically prune expired rows so the table doesn't grow
     // unbounded — the keyspace is effectively every distinct panel/filter
@@ -118,7 +121,8 @@ async function setL2(
       await db.execute({
         sql: "DELETE FROM first_party_analytics_cache WHERE expires_at <= ?",
         args: [now.toISOString()],
-        timeoutMs,
+        timeoutMs: cacheIoTimeoutMs(deadlineAt),
+        maxAttempts: 1,
       });
     }
   } catch (err) {
@@ -126,6 +130,17 @@ async function setL2(
   }
 }
 
+function remainingTimeoutMs(deadlineAt: number): number {
+  return Math.max(0, deadlineAt - Date.now());
+}
+
+function cacheIoTimeoutMs(deadlineAt: number): number {
+  return Math.max(
+    1,
+    Math.min(CACHE_IO_TIMEOUT_MS, remainingTimeoutMs(deadlineAt)),
+  );
+}
+
 /**
  * Returns a cached result for (key, sql) if fresh, otherwise runs `compute`
  * exactly once — even under concurrent callers with the same key — and
@@ -134,12 +149,15 @@ async function setL2(
 export async function withFirstPartyCache(
   key: string,
   sql: string,
-  compute: () => Promise<AnalyticsQueryResult>,
+  compute: (timeoutMs: number) => Promise<AnalyticsQueryResult>,
   options: FirstPartyCacheOptions = {},
 ): Promise<AnalyticsQueryResult> {
   const l1Hit = getL1(key);
   if (l1Hit) return l1Hit;
 
+  const timeoutMs = Math.max(1, options.timeoutMs ?? CACHE_IO_TIMEOUT_MS);
+  const deadlineAt = Date.now() + timeoutMs;
+
   // A report prewarm may have a shorter deadline than a normal panel request;
   // never let those callers inherit one another's database timeout.
   const requestKey = inFlightKey(key, options.timeoutMs);
@@ -150,14 +168,22 @@ export async function withFirstPartyCache(
   // callers racing on the same key can't both slip past the check above and
   // both hit L2/compute.
   const promise = (async () => {
-    const l2Hit = await getL2(key, options.timeoutMs);
+    const l2Hit = await getL2(key, deadlineAt);
     if (l2Hit) {
       setL1(key, l2Hit);
       return l2Hit;
     }
-    const result = await compute();
+    const queryTimeoutMs = remainingTimeoutMs(deadlineAt);
+    if (queryTimeoutMs <= 0) {
+      throw new Error(
+        `First-party analytics query timed out after ${timeoutMs}ms`,
+      );
+    }
+    const result = await compute(queryTimeoutMs);
     setL1(key, result);
-    await setL2(key, sql, result, options.timeoutMs);
+    // Cache persistence is best-effort. A successful panel query must not miss
+    // its delivery deadline because the cache table is slow or unavailable.
+    void setL2(key, sql, result, deadlineAt);
     return result;
   })().finally(() => {
     inFlight.delete(requestKey);

package/corpus/templates/analytics/server/lib/first-party-analytics.ts

@@ -660,12 +660,14 @@ export async function queryFirstPartyAnalytics(
   // org_id/owner_email (see scopeClause) — a cache hit can only ever return
   // rows the same tenant was already entitled to query.
   const cacheKey = firstPartyCacheKey(wrappedSql, scoped.args);
-  const compute = async (): Promise<AnalyticsQueryResult> => {
+  const compute = async (
+    queryTimeoutMs = timeoutMs,
+  ): Promise<AnalyticsQueryResult> => {
     const exec = getDbExec();
     const result = await exec.execute({
       sql: wrappedSql,
       args: scoped.args,
-      timeoutMs,
+      timeoutMs: queryTimeoutMs,
       maxAttempts: 1,
     });
     const rows = result.rows as Record<string, unknown>[];

package/corpus/templates/analytics/shared/sql-query-limits.ts

@@ -1 +1,2 @@
 export const MAX_CONCURRENT_SQL_QUERIES = 4;
+export const MAX_CONCURRENT_FIRST_PARTY_SQL_QUERIES = 1;

package/corpus/templates/assets/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/brain/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/calendar/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/chat/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/chat/README.md

@@ -30,5 +30,3 @@ pnpm dev
 ```
 
 Full docs: [agent-native.com/docs/template-chat](https://agent-native.com/docs/template-chat).
-
-<!-- vendor-branch mirror end-to-end test — safe to remove -->

package/corpus/templates/clips/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/clips/app/components/player/player-controls.tsx

@@ -323,11 +323,8 @@ function IconBtn({
 
 function SkipIcon({ direction }: { direction: "back" | "forward" }) {
   return (
-    <span className="relative flex h-5 w-5 items-center justify-center">
-      <IconPlayerSkipForward
-        className={cn("h-5 w-5", direction === "back" && "rotate-180")}
-      />
-      <span className="absolute text-[7px] font-bold leading-none">5</span>
-    </span>
+    <IconPlayerSkipForward
+      className={cn("h-5 w-5", direction === "back" && "rotate-180")}
+    />
   );
 }

package/corpus/templates/clips/app/components/player/recording-views-badge.tsx

@@ -1,9 +1,9 @@
-import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useActionQuery, useAvatarUrl } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
 import { IconTerminal2, IconUser } from "@tabler/icons-react";
 import { useState } from "react";
 
-import { Avatar, AvatarFallback } from "@/components/ui/avatar";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import { Button } from "@/components/ui/button";
 import {
   Popover,
@@ -284,8 +284,12 @@ export function ViewerAvatar({
   className?: string;
 }) {
   const anonymous = !viewer.viewerName && !viewer.viewerEmail;
+  const avatarUrl = useAvatarUrl(viewer.viewerEmail);
+  const label = viewer.viewerName || viewer.viewerEmail || "";
+
   return (
     <Avatar className={cn("h-6 w-6 shrink-0", className)}>
+      {avatarUrl ? <AvatarImage src={avatarUrl} alt={label} /> : null}
       <AvatarFallback className="bg-primary text-[10px] text-primary-foreground">
         {anonymous ? (
           <IconUser className="h-3 w-3" />

package/corpus/templates/clips/app/components/sharing/share-ui.tsx

@@ -16,6 +16,11 @@ import {
 import { useQueryClient } from "@tanstack/react-query";
 import { useMemo, useState } from "react";
 
+import {
+  Avatar as UserAvatar,
+  AvatarFallback as UserAvatarFallback,
+  AvatarImage as UserAvatarImage,
+} from "@/components/ui/avatar";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { Input } from "@/components/ui/input";
@@ -26,6 +31,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { useVisibleAvatarUrl } from "@/lib/use-visible-avatar-url";
 import { cn } from "@/lib/utils";
 
 // ---------------------------------------------------------------------------
@@ -304,17 +310,26 @@ export function CopyField({
 // ---------------------------------------------------------------------------
 
 export function Avatar({ label, org }: { label: string; org?: boolean }) {
-  return (
-    <span
-      aria-hidden
-      className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-muted text-[11px] font-semibold text-muted-foreground"
-    >
-      {org ? (
+  const { avatarRef, avatarUrl } = useVisibleAvatarUrl(org ? null : label);
+
+  if (org) {
+    return (
+      <span
+        aria-hidden
+        className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-muted text-[11px] font-semibold text-muted-foreground"
+      >
         <IconUsersGroup size={14} strokeWidth={1.75} />
-      ) : (
-        (label.split("@")[0]?.[0] ?? label[0] ?? "?").toUpperCase()
-      )}
-    </span>
+      </span>
+    );
+  }
+
+  return (
+    <UserAvatar ref={avatarRef} className="h-7 w-7 shrink-0">
+      {avatarUrl ? <UserAvatarImage src={avatarUrl} alt={label} /> : null}
+      <UserAvatarFallback className="bg-muted text-[11px] font-semibold text-muted-foreground">
+        {(label.split("@")[0]?.[0] ?? label[0] ?? "?").toUpperCase()}
+      </UserAvatarFallback>
+    </UserAvatar>
   );
 }
 

package/corpus/templates/clips/app/components/sharing/viewed-by-popover.tsx

@@ -2,12 +2,13 @@ import { useActionQuery } from "@agent-native/core/client/hooks";
 import { useFormatters, useT } from "@agent-native/core/client/i18n";
 import { useState } from "react";
 
-import { Avatar, AvatarFallback } from "@/components/ui/avatar";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import {
   Popover,
   PopoverContent,
   PopoverTrigger,
 } from "@/components/ui/popover";
+import { useVisibleAvatarUrl } from "@/lib/use-visible-avatar-url";
 import { cn } from "@/lib/utils";
 
 interface ClipViewRecord {
@@ -100,11 +101,11 @@ export function ViewedByPopover({
                     key={v.id}
                     className="flex items-center gap-2 rounded-md px-2 py-1.5"
                   >
-                    <Avatar className="h-6 w-6 shrink-0">
-                      <AvatarFallback className="text-[10px] bg-primary text-primary-foreground">
-                        {initials(v.viewerName || v.viewerEmail || "?")}
-                      </AvatarFallback>
-                    </Avatar>
+                    <ViewerAvatar
+                      email={v.viewerEmail}
+                      name={v.viewerName}
+                      label={label}
+                    />
                     <div className="min-w-0 flex-1">
                       <div className="truncate text-sm text-foreground">
                         {label}
@@ -124,6 +125,27 @@ export function ViewedByPopover({
   );
 }
 
+export function ViewerAvatar({
+  email,
+  name,
+  label,
+}: {
+  email: string | null;
+  name: string | null;
+  label: string;
+}) {
+  const { avatarRef, avatarUrl } = useVisibleAvatarUrl(email);
+
+  return (
+    <Avatar ref={avatarRef} className="h-6 w-6 shrink-0">
+      {avatarUrl ? <AvatarImage src={avatarUrl} alt={label} /> : null}
+      <AvatarFallback className="text-[10px] bg-primary text-primary-foreground">
+        {initials(name || email || "?")}
+      </AvatarFallback>
+    </Avatar>
+  );
+}
+
 function initials(s: string): string {
   return s
     .split(/\s+|@/)