@agent-native/core 0.97.0 → 0.98.1

package/corpus/templates/analytics/server/lib/session-replay.ts

@@ -16,7 +16,19 @@ import {
   roleSatisfies,
   type ShareRole,
 } from "@agent-native/core/sharing";
-import { and, asc, desc, eq, gte, isNull, lt, lte, or, sql } from "drizzle-orm";
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  gte,
+  inArray,
+  isNull,
+  lt,
+  lte,
+  or,
+  sql,
+} from "drizzle-orm";
 
 import {
   isFailedSessionReplayNetworkStatus,
@@ -229,6 +241,10 @@ const DEFAULT_REPLAY_EVENTS_READ = 10_000;
 const MAX_REPLAY_EVENTS_READ = 100_000;
 const MAX_REPLAY_EVENTS_RESPONSE_BYTES =
   MAX_BLOB_REPLAY_CHUNK_BYTES + 512 * 1024;
+export const MAX_REPLAY_CHUNK_READ_BATCH_SIZE = 20;
+export const MAX_REPLAY_CHUNK_READ_BATCH_BYTES =
+  MAX_REPLAY_EVENTS_RESPONSE_BYTES;
+const REPLAY_CHUNK_READ_CONCURRENCY = 10;
 const DEFAULT_SESSION_RECORDINGS_LIMIT = 50;
 const MAX_SESSION_RECORDINGS_LIMIT = 100;
 const DEFAULT_REPLAY_RETENTION_DAYS = 30;
@@ -1954,7 +1970,16 @@ async function readSessionReplayChunkBytesForRecording(
     const ref = decodeReplayBlobRef(row.storageRef);
     if (!ref)
       throw replayError("Session replay blob reference is invalid", 500);
-    const blob = await readPrivateBlob(ref.handle);
+    const blob = await readPrivateBlob(ref.handle).catch((error) => {
+      console.error(
+        `[session-replay] Failed to decrypt blob chunk ${recording.id}/${row.seq}:`,
+        error,
+      );
+      throw replayError(
+        "Session replay storage could not be decrypted with this environment's encryption key. When using a production Analytics database locally, set ANALYTICS_SECRETS_ENCRYPTION_KEY to the matching production key.",
+        503,
+      );
+    });
     return {
       recording,
       seq: row.seq,
@@ -1972,6 +1997,187 @@ async function readSessionReplayChunkBytesForRecording(
   };
 }
 
+export interface SessionReplayChunkBatchItem {
+  seq: number;
+  checksum: string;
+  byteLength: number;
+  eventCount: number;
+  events: unknown[];
+  unavailable?: true;
+}
+
+export interface SessionReplayChunkBatchResult {
+  chunks: SessionReplayChunkBatchItem[];
+  unavailableChunks: number;
+}
+
+function validateReplayChunkReadSeqs(seqs: number[]): number[] {
+  if (!seqs.length) {
+    throw replayError("At least one replay chunk seq is required", 400);
+  }
+  if (seqs.length > MAX_REPLAY_CHUNK_READ_BATCH_SIZE) {
+    throw replayError(
+      `At most ${MAX_REPLAY_CHUNK_READ_BATCH_SIZE} replay chunks may be read per request`,
+      400,
+    );
+  }
+  const unique = new Set<number>();
+  for (const seq of seqs) {
+    if (!Number.isSafeInteger(seq) || seq < 0) {
+      throw replayError("Replay chunk seqs must be non-negative integers", 400);
+    }
+    if (unique.has(seq)) {
+      throw replayError("Replay chunk seqs must be unique", 400);
+    }
+    unique.add(seq);
+  }
+  return [...seqs];
+}
+
+function unavailableReplayChunkBatchItem(
+  seq: number,
+  row?: any,
+): SessionReplayChunkBatchItem {
+  return {
+    seq,
+    checksum: row?.checksum ?? "",
+    byteLength: Number(row?.byteLength ?? 0),
+    eventCount: Number(row?.eventCount ?? 0),
+    events: [],
+    unavailable: true,
+  };
+}
+
+async function readReplayChunkBatchRow(
+  recording: SessionRecordingSummary,
+  row: any,
+): Promise<SessionReplayChunkBatchItem> {
+  let json: string;
+  if (row.storageKind === "blob" && row.storageRef) {
+    const ref = decodeReplayBlobRef(row.storageRef);
+    if (!ref) return unavailableReplayChunkBatchItem(row.seq, row);
+    let blob: Awaited<ReturnType<typeof readPrivateBlob>>;
+    try {
+      blob = await readPrivateBlob(ref.handle);
+    } catch (error) {
+      console.error(
+        `[session-replay] Failed to read blob chunk ${recording.id}/${row.seq}:`,
+        error,
+      );
+      throw replayError(
+        "Session replay storage could not be read with this environment's storage configuration or encryption key.",
+        503,
+      );
+    }
+    try {
+      json = gunzipSync(Buffer.from(blob.data)).toString("utf8");
+    } catch {
+      return unavailableReplayChunkBatchItem(row.seq, row);
+    }
+  } else if (row.inlineData) {
+    json = row.inlineData;
+  } else {
+    return unavailableReplayChunkBatchItem(row.seq, row);
+  }
+
+  return {
+    seq: row.seq,
+    checksum: row.checksum,
+    byteLength: row.byteLength,
+    eventCount: row.eventCount,
+    events: parseInlineReplayEvents(json),
+  };
+}
+
+async function readSessionReplayChunkBatchForRecording(
+  recording: SessionRecordingSummary,
+  requestedSeqs: number[],
+): Promise<SessionReplayChunkBatchResult> {
+  const seqs = validateReplayChunkReadSeqs(requestedSeqs);
+  const db = getDb() as any;
+  // guard:allow-unscoped -- rows are loaded only after one recording-scoped resolveAccess check or a signed recording-scoped agent token verifies access.
+  const rows = await db
+    .select()
+    .from(schema.sessionReplayChunks)
+    .where(
+      and(
+        eq(schema.sessionReplayChunks.recordingId, recording.id),
+        inArray(schema.sessionReplayChunks.seq, seqs),
+      ),
+    )
+    .orderBy(asc(schema.sessionReplayChunks.seq));
+
+  const declaredBytes = rows.reduce(
+    (total: number, row: any) => total + Math.max(0, Number(row.byteLength)),
+    0,
+  );
+  if (declaredBytes > MAX_REPLAY_CHUNK_READ_BATCH_BYTES) {
+    throw replayError(
+      `Replay chunk batches must be ${MAX_REPLAY_CHUNK_READ_BATCH_BYTES} bytes or smaller`,
+      413,
+    );
+  }
+
+  const rowBySeq = new Map<number, any>(
+    rows.map((row: any) => [Number(row.seq), row]),
+  );
+  const chunks = new Array<SessionReplayChunkBatchItem>(seqs.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    while (nextIndex < seqs.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const seq = seqs[index];
+      const row = rowBySeq.get(seq);
+      chunks[index] = row
+        ? await readReplayChunkBatchRow(recording, row)
+        : unavailableReplayChunkBatchItem(seq);
+    }
+  }
+
+  await Promise.all(
+    Array.from(
+      {
+        length: Math.min(REPLAY_CHUNK_READ_CONCURRENCY, seqs.length),
+      },
+      worker,
+    ),
+  );
+
+  const result = {
+    chunks,
+    unavailableChunks: chunks.filter((chunk) => chunk.unavailable).length,
+  };
+  if (
+    Buffer.byteLength(JSON.stringify(result), "utf8") >
+    MAX_REPLAY_CHUNK_READ_BATCH_BYTES
+  ) {
+    throw replayError(
+      `Replay chunk batch responses must be ${MAX_REPLAY_CHUNK_READ_BATCH_BYTES} bytes or smaller`,
+      413,
+    );
+  }
+  return result;
+}
+
+export async function readSessionReplayChunkBatch(
+  recordingId: string,
+  seqs: number[],
+  scope: SessionReplayScope,
+): Promise<SessionReplayChunkBatchResult> {
+  const recording = await getSessionReplaySummary(recordingId, scope);
+  return readSessionReplayChunkBatchForRecording(recording, seqs);
+}
+
+export async function readSessionReplayTokenizedChunkBatch(
+  recordingId: string,
+  seqs: number[],
+): Promise<SessionReplayChunkBatchResult> {
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  return readSessionReplayChunkBatchForRecording(recording, seqs);
+}
+
 export async function getSessionReplayEvents(
   recordingId: string,
   scope: SessionReplayScope,

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -1,7 +1,6 @@
 import { getOrgContext } from "@agent-native/core/org";
 import {
   createAgentChatPlugin,
-  getRequestRunContext,
   loadActionsFromStaticRegistry,
   type AgentLoopFinalResponseGuardContext,
 } from "@agent-native/core/server";
@@ -11,7 +10,6 @@ import {
   applyAnalyticsPlanModePolicy,
   INITIAL_TOOL_NAMES,
 } from "../lib/agent-chat-plan-mode";
-import { renderDataDictionary } from "../lib/data-dictionary-context";
 import {
   failedDataQueryAttemptMessage,
   hasExplicitPartialDisclosure,
@@ -26,12 +24,6 @@ import {
   needsCorpusWorkflowForCoverageSensitiveRequest,
   needsSourceRecordBodyWorkflowForCoverageSensitiveRequest,
 } from "../lib/real-data-actions";
-import {
-  listScopedSettingRecords,
-  resolveSettingsScope,
-} from "../lib/scoped-settings";
-
-const DATA_DICT_PREFIX = "data-dict-";
 const ANALYTICS_BACKGROUND_RUN_SOFT_TIMEOUT_MS = 13 * 60_000;
 
 export const SIMPLE_TIME_BOUNDED_METRIC_FAST_PATH_GUIDANCE =
@@ -46,6 +38,12 @@ export function analyticsSourceGuidanceOpening(): string {
   );
 }
 
+export function analyticsDataDictionaryRoutingContext(): string {
+  return `<data-dictionary-routing>
+Data-dictionary definitions are available on demand instead of being embedded in every chat request. Before writing SQL or making a metric-definition claim, call \`list-data-dictionary\` with a focused \`search\` or \`department\` filter. If the user asks what definitions exist and no useful filter is available, call it without filters. Treat approved entries as canonical, verify unreviewed human entries when stakes are high, and treat AI-generated unapproved entries as suggestions only. If no matching definition exists, inspect the configured source schema or ask the user instead of guessing.
+</data-dictionary-routing>`;
+}
+
 export {
   applyAnalyticsPlanModePolicy,
   INITIAL_TOOL_NAMES,
@@ -231,10 +229,10 @@ export default createAgentChatPlugin({
     const ctx = await getOrgContext(event);
     return ctx.orgId;
   },
-  extraContext: async (event) => {
-    // Always inject source guidance, even if the data-dictionary lookup throws.
-    // The generic template can ship provider actions without every deployment
-    // having credentials or workspace-specific schemas configured.
+  extraContext: async () => {
+    // Always inject compact source-routing guidance. Dictionary definitions
+    // stay behind list-data-dictionary so prompt assembly does not read and
+    // render every organization metric before the model request starts.
     const sourceGuidance =
       analyticsSourceGuidanceOpening() +
       "DASHBOARD CREATION RULE — You may create dashboards, analyses, SQL panels, or other resources only when the user explicitly asks you to (e.g. 'build me a dashboard for...', 'create a new analysis', 'add a chart for...'). Never create any resource proactively during research, trend analysis, or answering questions. If you think a dashboard would be useful, suggest it and wait for explicit confirmation before creating anything. Never add new items to the sidebar or modify existing dashboards without an explicit user directive. " +
@@ -268,33 +266,7 @@ export default createAgentChatPlugin({
       "Do not also create a same-named dashboard or saved analysis unless the user explicitly asked for multiple artifacts; saved analyses appear in the sidebar and should not be used for throwaway notes or scratch summaries.\n" +
       "</analytics-artifact-guidance>";
 
-    // In the durable background-function worker, skip the data-dictionary read
-    // + render. That settings read + synchronous render is the heaviest, most
-    // hang-prone part of worker setup on a cold bg-fn instance, and it runs
-    // EAGERLY while the system prompt is built (before any pre-send timeout can
-    // arm), so a stall here is what kept the analytics worker from ever claiming
-    // its run. The agent can still pull dictionary entries on demand via
-    // `list-data-dictionary` / `search-bigquery-schema`; the static guidance is
-    // what it needs to know they exist. Foreground requests keep the full dict.
-    if (getRequestRunContext()?.isBackgroundWorker) {
-      return `${sourceGuidance}\n\n${artifactGuidance}`;
-    }
-
-    try {
-      const scope = await resolveSettingsScope(event);
-      const all = await listScopedSettingRecords(scope, DATA_DICT_PREFIX);
-      const entries = Object.values(all) as Array<Record<string, unknown>>;
-      const dict = renderDataDictionary(entries);
-      return dict
-        ? `${sourceGuidance}\n\n${artifactGuidance}\n\n${dict}`
-        : `${sourceGuidance}\n\n${artifactGuidance}`;
-    } catch (err) {
-      console.warn(
-        "[analytics] data dictionary context failed:",
-        err instanceof Error ? err.message : err,
-      );
-      return `${sourceGuidance}\n\n${artifactGuidance}`;
-    }
+    return `${sourceGuidance}\n\n${artifactGuidance}\n\n${analyticsDataDictionaryRoutingContext()}`;
   },
   mentionProviders: {
     dashboards: {

package/corpus/templates/analytics/server/plugins/onboarding.ts

@@ -1,24 +1,17 @@
 /**
  * Custom onboarding plugin for Analytics.
  *
- * Overrides the framework's default onboarding plugin to add an optional
- * "Session replay storage" step and register the S3 file upload provider. Must
- * live in server/plugins/ so the framework skips its default onboarding plugin,
- * and all registrations share the same module context as the onboarding route
- * handlers (which read from the same in-memory Map).
- *
- * The step is `required: false` because session replay is opt-in: capturing
- * replays only matters once a site embeds the tracking SDK with replay enabled,
- * so we surface storage setup without forcing it into the onboarding checklist.
+ * Overrides the framework's default onboarding plugin to register the S3 file
+ * upload provider. Must live in server/plugins/ so the framework skips its
+ * default onboarding plugin, and all registrations share the same module
+ * context as the onboarding route handlers (which read from the same in-memory
+ * Map). Analytics only needs storage when someone enables session replay, so
+ * replay setup lives with that workflow instead of onboarding.
  */
 
 import { registerFileUploadProvider } from "@agent-native/core/file-upload";
-import {
-  createOnboardingPlugin,
-  registerOnboardingStep,
-} from "@agent-native/core/onboarding";
+import { createOnboardingPlugin } from "@agent-native/core/onboarding";
 
-import { hasRequestReplayStorage } from "../lib/replay-storage.js";
 import { s3FileUploadProvider } from "../lib/s3-upload-provider.js";
 
 const basePlugin = createOnboardingPlugin();
@@ -29,69 +22,4 @@ export default async (nitroApp: any): Promise<void> => {
 
   // Register S3-compatible file upload provider for session-replay chunks.
   registerFileUploadProvider(s3FileUploadProvider);
-
-  // Add the optional "Session replay storage" onboarding step.
-  registerOnboardingStep({
-    id: "replay-storage",
-    order: 15,
-    required: false,
-    title: "Session replay storage",
-    description:
-      "Store session replay recordings with Builder.io or S3-compatible storage.",
-    methods: [
-      {
-        id: "builder",
-        kind: "builder-cli-auth",
-        label: "Connect Builder.io",
-        description:
-          "Builder.io's free tier includes object storage for replay chunks.",
-        primary: true,
-        badge: "free",
-        payload: { scope: "browser" },
-      },
-      {
-        id: "s3",
-        kind: "form",
-        label: "Use S3-compatible storage",
-        description:
-          "AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, or any S3-compatible service.",
-        payload: {
-          writeScope: "workspace",
-          fields: [
-            {
-              key: "S3_ENDPOINT",
-              label: "Endpoint URL",
-              placeholder: "https://s3.us-east-1.amazonaws.com",
-            },
-            {
-              key: "S3_BUCKET",
-              label: "Bucket name",
-              placeholder: "my-replays-bucket",
-            },
-            {
-              key: "S3_ACCESS_KEY_ID",
-              label: "Access key ID",
-              placeholder: "AKIA...",
-            },
-            {
-              key: "S3_SECRET_ACCESS_KEY",
-              label: "Secret access key",
-              secret: true,
-            },
-            {
-              key: "S3_REGION",
-              label: "Region (optional)",
-              placeholder: "us-east-1",
-            },
-            {
-              key: "S3_PUBLIC_BASE_URL",
-              label: "Public base URL (optional)",
-              placeholder: "https://cdn.example.com",
-            },
-          ],
-        },
-      },
-    ],
-    isComplete: hasRequestReplayStorage,
-  });
 };

package/corpus/templates/analytics/server/routes/api/session-replay/recordings/[recordingId]/chunks.get.ts

@@ -0,0 +1 @@
+export { handleSessionReplayChunkBatch as default } from "../../../../../handlers/session-replay";

package/corpus/templates/assets/.agents/skills/frontend-design/SKILL.md

@@ -48,7 +48,7 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 
 - **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
 - **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
-- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library.
+- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.

package/corpus/templates/assets/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/assets/app/components/create/RecentDraftsSection.tsx

@@ -1,5 +1,9 @@
 import { useActionQuery, useT } from "@agent-native/core/client";
-import { IconArrowUpRight, IconPhoto } from "@tabler/icons-react";
+import {
+  IconAlertTriangle,
+  IconArrowUpRight,
+  IconPhoto,
+} from "@tabler/icons-react";
 import { Link } from "react-router";
 
 import { Button } from "@/components/ui/button";
@@ -20,11 +24,33 @@ const RECENT_DRAFTS_LIMIT = 5;
 
 export function RecentDraftsSection() {
   const t = useT();
-  const { data, isLoading } = useActionQuery("list-draft-assets", {
-    limit: RECENT_DRAFTS_LIMIT,
-  });
+  const { data, isLoading, isError, isFetching, refetch } = useActionQuery(
+    "list-draft-assets",
+    {
+      limit: RECENT_DRAFTS_LIMIT,
+    },
+  );
   const drafts = ((data as any)?.assets ?? []) as DraftAsset[];
 
+  if (isError) {
+    return (
+      <section className="flex items-center justify-between gap-3 rounded-lg border border-destructive/30 px-4 py-3">
+        <div className="flex min-w-0 items-center gap-2 text-sm text-muted-foreground">
+          <IconAlertTriangle className="size-4 shrink-0 text-destructive" />
+          <span className="truncate">{t("audit.unknownError")}</span>
+        </div>
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => void refetch()}
+          disabled={isFetching}
+        >
+          {t("brandKitDetail.refresh")}
+        </Button>
+      </section>
+    );
+  }
+
   if (!isLoading && drafts.length === 0) return null;
 
   return (

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

@@ -257,14 +257,14 @@
   [data-agent-empty-state="centered"]
   .agent-composer-area {
   width: 100%;
-  max-width: min(760px, 90%);
+  max-width: min(570px, 90%);
   padding: 0;
 }
 
 .assets-create-chat-panel
   [data-agent-empty-state="centered"]
   .agent-composer-root {
-  min-height: 10.5rem;
+  min-height: 7.875rem;
   border-color: hsl(var(--border));
   border-radius: 1rem;
   background: hsl(var(--card));
@@ -274,7 +274,7 @@
 .assets-create-chat-panel
   [data-agent-empty-state="centered"]
   .agent-composer-prosemirror {
-  min-height: 6.75rem;
+  min-height: 5.0625rem;
   font-size: 1rem;
   line-height: 1.625rem;
 }
@@ -305,6 +305,6 @@
   .assets-create-chat-panel
     [data-agent-empty-state="centered"]
     .agent-composer-root {
-    min-height: 9rem;
+    min-height: 6.75rem;
   }
 }

package/corpus/templates/assets/app/routes/brand-kits.$id.tsx

@@ -429,7 +429,6 @@ export function BrandKitDetailRoute({
         signal,
       });
     },
-    refetchInterval: 1000,
   });
 
   useEffect(() => {

package/corpus/templates/assets/app/routes/library.tsx

@@ -24,6 +24,7 @@ import {
   EMBED_TOKEN_QUERY_PARAM,
 } from "@agent-native/core/shared";
 import {
+  IconAlertTriangle,
   IconArrowUpRight,
   IconCheck,
   IconChevronDown,
@@ -1104,11 +1105,20 @@ function AllAssetsBrowser() {
   > | null>(null);
   const [standaloneCopyOk, setStandaloneCopyOk] = useState(false);
 
-  const { data: assetData, isLoading } = useActionQuery("list-assets", {
+  const {
+    data: assetData,
+    isLoading,
+    isError,
+    isFetching,
+    refetch,
+  } = useActionQuery("list-assets", {
     query: query.trim() || undefined,
   } as any) as {
     data?: { assets?: Asset[] };
     isLoading: boolean;
+    isError: boolean;
+    isFetching: boolean;
+    refetch: () => Promise<unknown>;
   };
 
   const allAssets = assetData?.assets ?? [];
@@ -1274,6 +1284,21 @@ function AllAssetsBrowser() {
               <Skeleton key={index} className="aspect-[4/3] rounded-lg" />
             ))}
           </div>
+        ) : isError ? (
+          <div className="flex min-h-64 flex-col items-center justify-center gap-3 px-6 text-center">
+            <IconAlertTriangle className="size-9 text-destructive" />
+            <p className="max-w-sm text-sm text-muted-foreground">
+              {t("audit.unknownError")}
+            </p>
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => void refetch()}
+              disabled={isFetching}
+            >
+              {t("brandKitDetail.refresh")}
+            </Button>
+          </div>
         ) : assets.length === 0 ? (
           <div className="flex min-h-64 items-center justify-center text-center">
             <div className="max-w-sm text-sm text-muted-foreground">
@@ -1592,7 +1617,6 @@ function LibraryCandidateStage({
         { signal },
       );
     },
-    refetchInterval: 1000,
   });
   const isAllAssetsStage = !activeLibraryId;
   const liveLibraryId = activeLibraryId ?? variants?.libraryId ?? null;
@@ -1886,12 +1910,16 @@ export function LibraryWorkspace({
 }: {
   selectedLibraryId?: string | null;
 }) {
+  const t = useT();
   const navigate = useNavigate();
   const routeSelectedLibraryId = useLibraryRouteSelectedId(selectedLibraryId);
   const [createOpen, setCreateOpen] = useState(false);
-  const { data, isLoading } = useActionQuery("list-libraries", {
-    includeFolders: true,
-  } as any);
+  const { data, isLoading, isError, isFetching, refetch } = useActionQuery(
+    "list-libraries",
+    {
+      includeFolders: true,
+    } as any,
+  );
   const libraries = ((data as any)?.libraries ?? []) as ImageLibrarySummary[];
   const foldersByLibraryId = useMemo(() => {
     const result: Record<string, any[]> = {};
@@ -1939,7 +1967,22 @@ export function LibraryWorkspace({
             isLoading={isLoading}
             onCreateKit={() => setCreateOpen(true)}
           />
-          {routeSelectedLibraryId || hasLibraries ? (
+          {isError ? (
+            <div className="flex min-h-80 flex-col items-center justify-center gap-3 px-6 text-center">
+              <IconAlertTriangle className="size-9 text-destructive" />
+              <p className="max-w-sm text-sm text-muted-foreground">
+                {t("audit.unknownError")}
+              </p>
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={() => void refetch()}
+                disabled={isFetching}
+              >
+                {t("brandKitDetail.refresh")}
+              </Button>
+            </div>
+          ) : routeSelectedLibraryId || hasLibraries ? (
             <>
               <LibraryCandidateStage
                 activeLibraryId={routeSelectedLibraryId}

package/corpus/templates/assets/changelog/2026-07-11-library-load-failures-now-show-a-retry-action.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-11
+---
+
+Library and recent-draft loading failures now show a clear retry action instead of looking empty.