@promptbook/cli 0.112.0-110 → 0.112.0-111

package/apps/agents-server/src/app/agents/[agentName]/_utils.ts

@@ -5,7 +5,7 @@ import { $provideAgentReferenceResolver } from '@/src/utils/agentReferenceResolv
 import {
     parseBookScopedAgentIdentifier,
 } from '@/src/utils/agentReferenceResolver/bookScopedAgentReferences';
-import { resolveServerAgentContext } from '@/src/utils/resolveServerAgentContext';
+import { resolveCachedServerAgentContext } from '@/src/utils/cachedServerAgentRuntime';
 import { cache } from 'react';
 import type { AgentsServerDatabase } from '../../../database/schema';
 import { $provideSupabaseForServer } from '../../../database/$provideSupabaseForServer';
@@ -91,10 +91,12 @@ export async function enforceCanonicalLocalAgentId(
  * @returns Resolved agent profile with visibility.
  */
 const getCachedAgentProfile = cache(async (agentName: string) => {
-    const collection = await $provideAgentCollectionForServer();
-    const { publicUrl } = await $provideServer();
-    const baseAgentReferenceResolver = await $provideAgentReferenceResolver();
-    const resolvedAgentContext = await resolveServerAgentContext({
+    const [collection, { publicUrl }, baseAgentReferenceResolver] = await Promise.all([
+        $provideAgentCollectionForServer(),
+        $provideServer(),
+        $provideAgentReferenceResolver(),
+    ]);
+    const resolvedAgentContext = await resolveCachedServerAgentContext({
         collection,
         agentIdentifier: agentName,
         localServerUrl: publicUrl.href,

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/[chatId]/stream/route.ts

@@ -1,11 +1,6 @@
 import { CHAT_STREAM_KEEP_ALIVE_INTERVAL_MS } from '@/src/constants/streaming';
 import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
-import {
-    createUserChatDetailPayload,
-    getUserChat,
-    getUserChatRevision,
-    isFrozenUserChatSource,
-} from '@/src/utils/userChat';
+import { createUserChatDetailPayload, getUserChat, isFrozenUserChatSource } from '@/src/utils/userChat';
 import type { ChatMessage } from '@promptbook-local/types';
 import { NextResponse } from 'next/server';
 import { resolveUserChatScope } from '../../resolveUserChatScope';
@@ -37,11 +32,6 @@ type UserChatStreamFrame =
           type: 'keepalive';
       };
 
-/**
- * Lightweight revision shape returned by `getUserChatRevision`.
- */
-type UserChatRevision = Awaited<ReturnType<typeof getUserChatRevision>>;
-
 /**
  * Streams canonical chat snapshots for one scoped user chat so multiple viewers can observe the same background turn.
  */
@@ -83,7 +73,6 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         async start(controller) {
             let isStreamClosed = false;
             let lastSnapshotSignature: string | null = null;
-            let lastRevisionSignature: string | null = null;
             let keepAliveInterval: ReturnType<typeof setInterval> | null = null;
 
             /**
@@ -149,24 +138,6 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
 
                 const payload = await createUserChatDetailPayload(currentChat);
                 const nextSignature = createUserChatDetailSignature(payload);
-                lastRevisionSignature = createUserChatRevisionSignature({
-                    id: payload.chat.id,
-                    updatedAt: payload.chat.updatedAt,
-                    draftMessage: payload.draftMessage,
-                    source: payload.chat.source,
-                    activeJobs: payload.activeJobs.map((job) => ({
-                        id: job.id,
-                        status: job.status,
-                        cancelRequestedAt: job.cancelRequestedAt,
-                    })),
-                    activeTimeouts: payload.activeTimeouts.map((timeout) => ({
-                        id: timeout.id,
-                        status: timeout.status,
-                        message: timeout.message,
-                        dueAt: timeout.dueAt,
-                        cancelRequestedAt: timeout.cancelRequestedAt,
-                    })),
-                });
 
                 if (nextSignature !== lastSnapshotSignature) {
                     lastSnapshotSignature = nextSignature;
@@ -178,32 +149,6 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                 return !isFrozenUserChatSource(payload.chat.source) && payload.activeJobs.length > 0;
             };
 
-            /**
-             * Emits a full snapshot only when an idle chat revision changed.
-             *
-             * @private route helper
-             */
-            const emitLatestSnapshotWhenRevisionChanged = async (): Promise<boolean> => {
-                const currentRevision = await getUserChatRevision({
-                    userId: scopeResult.scope.userId,
-                    viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
-                    agentPermanentId: scopeResult.scope.agentPermanentId,
-                    chatId,
-                });
-
-                if (!currentRevision) {
-                    closeStream();
-                    return false;
-                }
-
-                const nextRevisionSignature = createUserChatRevisionSignature(currentRevision);
-                if (nextRevisionSignature === lastRevisionSignature) {
-                    return false;
-                }
-
-                return emitLatestSnapshot();
-            };
-
             /**
              * Tracks client disconnects so the polling loop can exit promptly.
              *
@@ -220,11 +165,11 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             keepAliveInterval.unref?.();
 
             try {
-                let shouldUseFullPolling = await emitLatestSnapshot();
+                let hasActiveJobs = await emitLatestSnapshot();
 
                 while (!isStreamClosed && !request.signal.aborted) {
                     await waitForNextUserChatStreamPoll(
-                        shouldUseFullPolling
+                        hasActiveJobs
                             ? ACTIVE_USER_CHAT_STREAM_POLL_INTERVAL_MS
                             : IDLE_USER_CHAT_STREAM_POLL_INTERVAL_MS,
                         request.signal,
@@ -234,9 +179,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                         break;
                     }
 
-                    shouldUseFullPolling = shouldUseFullPolling
-                        ? await emitLatestSnapshot()
-                        : await emitLatestSnapshotWhenRevisionChanged();
+                    hasActiveJobs = await emitLatestSnapshot();
                 }
             } catch (error) {
                 if (!isStreamClosed && !request.signal.aborted) {
@@ -267,30 +210,6 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
     });
 }
 
-/**
- * Builds a compact signature for idle stream revision checks.
- */
-function createUserChatRevisionSignature(revision: NonNullable<UserChatRevision>): string {
-    return JSON.stringify({
-        id: revision.id,
-        updatedAt: revision.updatedAt,
-        draftMessage: revision.draftMessage || '',
-        source: revision.source,
-        activeJobs: revision.activeJobs.map((job) => ({
-            id: job.id,
-            status: job.status,
-            cancelRequestedAt: job.cancelRequestedAt,
-        })),
-        activeTimeouts: revision.activeTimeouts.map((timeout) => ({
-            id: timeout.id,
-            status: timeout.status,
-            message: timeout.message || '',
-            dueAt: timeout.dueAt,
-            cancelRequestedAt: timeout.cancelRequestedAt,
-        })),
-    });
-}
-
 /**
  * Builds a stable signature for the user-visible parts of a canonical chat snapshot.
  */
@@ -308,7 +227,6 @@ function createUserChatDetailSignature(payload: Awaited<ReturnType<typeof create
         activeTimeouts: payload.activeTimeouts.map((timeout) => ({
             id: timeout.id,
             status: timeout.status,
-            message: timeout.message || '',
             dueAt: timeout.dueAt,
             cancelRequestedAt: timeout.cancelRequestedAt,
         })),

package/apps/agents-server/src/components/ApplicationErrorPage/ApplicationErrorPage.tsx

@@ -14,8 +14,10 @@ import {
     createApplicationErrorHeadline,
     createApplicationErrorReportPayload,
     describeApplicationError,
+    isApplicationErrorRecoverableByHardRefresh,
     resolveApplicationErrorVariant,
 } from '../../utils/errorReporting/applicationErrorHandling';
+import { refreshApplicationDocument } from '../../utils/errorReporting/refreshApplicationDocument';
 import { ErrorPageButtonAction, ErrorPageLinkAction } from '../ErrorPage/ErrorPage';
 import { InternalServerErrorPage } from '../InternalServerErrorPage/InternalServerErrorPage';
 
@@ -27,7 +29,7 @@ import { InternalServerErrorPage } from '../InternalServerErrorPage/InternalServ
 const troubleshootingSteps = [
     {
         title: 'Refresh the route',
-        detail: 'Try "Try again" so the last navigation runs with fresh cookies, network state, and session data.',
+        detail: 'Use the primary action so the page can retry with fresh cookies, network state, and build assets.',
     },
     {
         title: 'Share the digest',
@@ -46,6 +48,20 @@ const troubleshootingSteps = [
  */
 const REPORT_ACTION_FEEDBACK_DURATION_MS = 2500;
 
+/**
+ * Delay before one recoverable stale-asset error triggers an automatic full-document refresh.
+ *
+ * @private
+ */
+const APPLICATION_ERROR_AUTO_REFRESH_DELAY_MS = 1500;
+
+/**
+ * Prefix used for session-scoped stale-asset refresh guards.
+ *
+ * @private
+ */
+const APPLICATION_ERROR_AUTO_REFRESH_STORAGE_KEY_PREFIX = 'promptbook.application-error-hard-refresh';
+
 /**
  * Writes plain text to the user clipboard.
  *
@@ -82,17 +98,25 @@ function downloadMarkdownReport(reportMarkdown: string, filename: string): void
     URL.revokeObjectURL(reportUrl);
 }
 
+/**
+ * Builds the session-storage key used to ensure one stale-asset error only auto-refreshes once per URL and digest.
+ *
+ * @param pageUrl - Browser URL where the error happened.
+ * @param digest - Deterministic digest rendered for the error.
+ * @returns Stable session-storage key for the current recoverable error.
+ *
+ * @private
+ */
+function createApplicationErrorAutoRefreshStorageKey(pageUrl: string, digest: string): string {
+    return `${APPLICATION_ERROR_AUTO_REFRESH_STORAGE_KEY_PREFIX}:${pageUrl}:${digest}`;
+}
+
 /**
  * Props accepted by shared action controls used across error variants.
  *
  * @private
  */
 type ApplicationErrorActionsProps = {
-    /**
-     * Callback that retries the failed route transition.
-     */
-    reset: () => void;
-
     /**
      * Digest value displayed for operator correlation.
      */
@@ -107,6 +131,16 @@ type ApplicationErrorActionsProps = {
      * Default filename used by the markdown save action.
      */
     reportFilename: string;
+
+    /**
+     * Primary action label rendered on the left-most action button.
+     */
+    primaryActionLabel: string;
+
+    /**
+     * Callback used by the left-most primary action button.
+     */
+    onPrimaryAction: () => void;
 };
 
 /**
@@ -117,10 +151,11 @@ type ApplicationErrorActionsProps = {
  * @private
  */
 function ApplicationErrorActions({
-    reset,
     digest,
     reportMarkdown,
     reportFilename,
+    primaryActionLabel,
+    onPrimaryAction,
 }: ApplicationErrorActionsProps) {
     const [reportFeedback, setReportFeedback] = useState<string | null>(null);
     const reportFeedbackTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -179,9 +214,7 @@ function ApplicationErrorActions({
     return (
         <div className="flex flex-col items-center gap-3">
             <div className="flex flex-wrap justify-center gap-3">
-                <ErrorPageButtonAction onClick={() => reset()}>
-                    Try again
-                </ErrorPageButtonAction>
+                <ErrorPageButtonAction onClick={onPrimaryAction}>{primaryActionLabel}</ErrorPageButtonAction>
                 <ErrorPageLinkAction href="/" tone="secondary">
                     Go to homepage
                 </ErrorPageLinkAction>
@@ -245,10 +278,25 @@ type ApplicationErrorViewProps = {
      */
     size?: 'default' | 'wide';
 
+    /**
+     * Primary action label rendered on the left-most action button.
+     */
+    primaryActionLabel: string;
+
+    /**
+     * Callback used by the left-most primary action button.
+     */
+    onPrimaryAction: () => void;
+
     /**
      * Optional supplementary content rendered beneath shared actions.
      */
     supplementaryContent?: ReactNode;
+
+    /**
+     * Optional recovery note rendered between the actions and supplementary content.
+     */
+    recoveryNotice?: ReactNode;
 };
 
 /**
@@ -264,18 +312,22 @@ function ApplicationErrorView({
     digest,
     reportMarkdown,
     reportFilename,
-    reset,
     size = 'default',
+    primaryActionLabel,
+    onPrimaryAction,
+    recoveryNotice,
     supplementaryContent,
 }: ApplicationErrorViewProps) {
     return (
         <InternalServerErrorPage headline={headline} description={description} size={size}>
             <ApplicationErrorActions
-                reset={reset}
                 digest={digest}
                 reportMarkdown={reportMarkdown}
                 reportFilename={reportFilename}
+                primaryActionLabel={primaryActionLabel}
+                onPrimaryAction={onPrimaryAction}
             />
+            {recoveryNotice}
             {supplementaryContent}
         </InternalServerErrorPage>
     );
@@ -374,9 +426,11 @@ export function ApplicationErrorPage({ error, reset }: ApplicationErrorPageProps
     );
     const digest = createApplicationErrorDigest(error);
     const serverName = process.env.NEXT_PUBLIC_SERVER_NAME ?? DEFAULT_APPLICATION_ERROR_SERVER_NAME;
+    const isRecoverableByHardRefresh = isApplicationErrorRecoverableByHardRefresh(error);
     const headline = createApplicationErrorHeadline(serverName);
     const description = describeApplicationError(error, serverName);
     const [pageUrl, setPageUrl] = useState<string | undefined>(undefined);
+    const [hasAutomaticRefreshAlreadyBeenAttempted, setHasAutomaticRefreshAlreadyBeenAttempted] = useState(false);
     const reportPayload = useMemo(
         () => createApplicationErrorReportPayload(error, digest, serverName, variant, pageUrl),
         [digest, error, pageUrl, serverName, variant],
@@ -392,6 +446,35 @@ export function ApplicationErrorPage({ error, reset }: ApplicationErrorPageProps
         setPageUrl(window.location.href);
     }, []);
 
+    useEffect(() => {
+        if (!pageUrl || !isRecoverableByHardRefresh) {
+            setHasAutomaticRefreshAlreadyBeenAttempted(false);
+            return undefined;
+        }
+
+        const storageKey = createApplicationErrorAutoRefreshStorageKey(pageUrl, digest);
+
+        try {
+            const hasStoredRefreshAttempt = window.sessionStorage.getItem(storageKey) === 'done';
+            if (hasStoredRefreshAttempt) {
+                setHasAutomaticRefreshAlreadyBeenAttempted(true);
+                return undefined;
+            }
+
+            window.sessionStorage.setItem(storageKey, 'done');
+        } catch {
+            // Some browser privacy modes may block session storage; the one-shot reload remains best-effort.
+        }
+
+        const timeout = window.setTimeout(() => {
+            refreshApplicationDocument();
+        }, APPLICATION_ERROR_AUTO_REFRESH_DELAY_MS);
+
+        return () => {
+            window.clearTimeout(timeout);
+        };
+    }, [digest, isRecoverableByHardRefresh, pageUrl]);
+
     useEffect(() => {
         if (!pageUrl) {
             return;
@@ -408,6 +491,23 @@ export function ApplicationErrorPage({ error, reset }: ApplicationErrorPageProps
         });
     }, [error, pageUrl, reportPayload]);
 
+    const primaryActionLabel = isRecoverableByHardRefresh ? 'Refresh now' : 'Try again';
+    const handlePrimaryAction = () => {
+        if (isRecoverableByHardRefresh) {
+            refreshApplicationDocument();
+            return;
+        }
+
+        reset();
+    };
+    const recoveryNotice = isRecoverableByHardRefresh ? (
+        <p className="mt-6 text-center text-sm text-gray-600">
+            {hasAutomaticRefreshAlreadyBeenAttempted
+                ? 'Automatic refresh already ran once. If the newest assets still do not load, use "Refresh now" or share the digest with your administrator.'
+                : 'Refreshing this page automatically once so the latest application files can be loaded.'}
+        </p>
+    ) : undefined;
+
     if (variant === 'simple') {
         return (
             <SimpleApplicationErrorView
@@ -417,6 +517,9 @@ export function ApplicationErrorPage({ error, reset }: ApplicationErrorPageProps
                 reportMarkdown={reportMarkdown}
                 reportFilename={reportFilename}
                 reset={reset}
+                recoveryNotice={recoveryNotice}
+                primaryActionLabel={primaryActionLabel}
+                onPrimaryAction={handlePrimaryAction}
             />
         );
     }
@@ -429,6 +532,9 @@ export function ApplicationErrorPage({ error, reset }: ApplicationErrorPageProps
             reportMarkdown={reportMarkdown}
             reportFilename={reportFilename}
             reset={reset}
+            recoveryNotice={recoveryNotice}
+            primaryActionLabel={primaryActionLabel}
+            onPrimaryAction={handlePrimaryAction}
         />
     );
 }

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -1,15 +1,11 @@
 import { $provideServer } from '../../tools/$provideServer';
 import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
-import { $getTableName } from '../../database/$getTableName';
-import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
 import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provideAgentReferenceResolver';
 import { consumeAgentReferenceResolutionIssues } from '../agentReferenceResolver/AgentReferenceResolutionIssue';
 import { parseBookScopedAgentIdentifier } from '../agentReferenceResolver/bookScopedAgentReferences';
-import { buildAgentNameOrIdFilter } from '../agentIdentifier';
 import { resolvePseudoAgentDescriptor } from '../pseudoAgents';
 import { normalizeAgentName } from '../../../../../src/_packages/core.index';
 import type { PseudoAgentKind } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
-import type { AgentsServerDatabase } from '../../database/schema';
 import { cache } from 'react';
 
 /**
@@ -54,14 +50,6 @@ type PseudoAgentRouteTarget = {
     canonicalUrl: string;
 };
 
-/**
- * Minimal database row needed to resolve one local route target.
- */
-type LocalAgentRouteRow = Pick<
-    AgentsServerDatabase['public']['Tables']['Agent']['Row'],
-    'agentName' | 'permanentId'
->;
-
 /**
  * Target returned for an incoming `/agents/:agentId` route value.
  */
@@ -114,11 +102,6 @@ async function resolveAgentRouteTargetUncached(
         };
     }
 
-    const directLocalRouteTarget = await resolveLocalAgentRouteTargetFromDatabase(normalizedReference, localServerUrl);
-    if (directLocalRouteTarget) {
-        return directLocalRouteTarget;
-    }
-
     const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
@@ -288,21 +271,7 @@ async function resolveLocalAgentRouteTarget(
     localServerUrl: string,
 ): Promise<AgentRouteTarget | null> {
     const collection = await $provideAgentCollectionForServer();
-    const agents = await collection.listAgents();
-    const normalizedReference = normalizeAgentName(reference);
-
-    const agentMatch = agents.find((agent: { agentName: string; permanentId?: string }) => {
-        if (agent.agentName === reference || agent.permanentId === reference) {
-            return true;
-        }
-
-        const normalizedAgentName = normalizeAgentName(agent.agentName);
-        if (normalizedAgentName === normalizedReference) {
-            return true;
-        }
-
-        return false;
-    });
+    const agentMatch = await findLocalAgentRouteMatch(collection, reference);
 
     if (!agentMatch) {
         return null;
@@ -318,40 +287,36 @@ async function resolveLocalAgentRouteTarget(
 }
 
 /**
- * Resolves the common local route case with a targeted indexed database lookup.
+ * Finds a local agent route match without loading the whole collection when possible.
  *
- * The reference resolver has to initialize the full local/federated lookup map.
- * Most page requests already carry a permanent id or exact local name, so checking
- * the Agent table first keeps normal navigation from loading every agent profile.
- *
- * @param reference - Normalized route reference.
- * @param localServerUrl - Normalized URL of the current Agents Server instance.
- * @returns Local route target or `null` when the reference is not a local agent.
+ * @param collection - Agents collection backing local routes.
+ * @param reference - Normalized route/reference text.
+ * @returns Matching local agent profile or `null`.
  */
-async function resolveLocalAgentRouteTargetFromDatabase(
+async function findLocalAgentRouteMatch(
+    collection: Awaited<ReturnType<typeof $provideAgentCollectionForServer>>,
     reference: string,
-    localServerUrl: string,
-): Promise<AgentRouteTarget | null> {
-    const supabase = $provideSupabaseForServer();
-    const agentTable = await $getTableName('Agent');
-    const result = await supabase
-        .from(agentTable)
-        .select('agentName, permanentId')
-        .or(buildAgentNameOrIdFilter(reference))
-        .is('deletedAt', null)
-        .order('createdAt', { ascending: true })
-        .limit(1);
-
-    if (result.error || !result.data || result.data.length === 0) {
-        return null;
+): Promise<{ agentName: string; permanentId?: string | null } | null> {
+    const directMatch = await collection.findAgentBasicInformation(reference);
+    if (directMatch) {
+        return directMatch;
     }
 
-    const agent = result.data[0] as LocalAgentRouteRow;
-    const canonicalAgentId = agent.permanentId || agent.agentName;
+    const agents = await collection.listAgents();
+    const normalizedReference = normalizeAgentName(reference);
 
-    return {
-        kind: 'local',
-        canonicalAgentId,
-        canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
-    };
+    return (
+        agents.find((agent: { agentName: string; permanentId?: string | null }) => {
+            if (agent.agentName === reference || agent.permanentId === reference) {
+                return true;
+            }
+
+            const normalizedAgentName = normalizeAgentName(agent.agentName);
+            if (normalizedAgentName === normalizedReference) {
+                return true;
+            }
+
+            return false;
+        }) || null
+    );
 }

package/apps/agents-server/src/utils/errorReporting/applicationErrorHandling.ts

@@ -80,6 +80,21 @@ const EDGE_DASH_PATTERN = /^-+|-+$/g;
  */
 const CODE_FENCE_PATTERN = /```/g;
 
+/**
+ * Regex matching webpack/Next.js chunk-load failures caused by stale or missing build assets.
+ */
+const CHUNK_LOAD_ERROR_MESSAGE_PATTERN = /loading (css )?chunk .* failed/i;
+
+/**
+ * Regex matching browsers that fail while fetching one dynamically imported module.
+ */
+const DYNAMIC_IMPORT_FETCH_ERROR_MESSAGE_PATTERN = /failed to fetch dynamically imported module/i;
+
+/**
+ * Regex matching Next.js-managed build asset URLs.
+ */
+const NEXT_BUILD_ASSET_PATH_PATTERN = /\/_next\/static\/(?:chunks|css)\//i;
+
 /**
  * Shape sent from the app error boundary to server-side Sentry forwarding.
  */
@@ -162,6 +177,32 @@ export function createApplicationErrorDigest(error: ApplicationBoundaryError | n
     return (hash >>> 0).toString(DECIMAL_BASE).padStart(DIGEST_LENGTH, '0');
 }
 
+/**
+ * Detects client-side build-asset errors that are commonly fixed by reloading the document once.
+ *
+ * @param error - Captured boundary exception.
+ * @returns True when the current document should be hard-refreshed instead of only retrying React navigation.
+ */
+export function isApplicationErrorRecoverableByHardRefresh(error: ApplicationBoundaryError | null): boolean {
+    const errorName = error?.name?.trim() || '';
+    const errorMessage = error?.message?.trim() || '';
+    const errorStack = error?.stack?.trim() || '';
+    const errorDetails = `${errorName}\n${errorMessage}\n${errorStack}`;
+
+    if (errorName === 'ChunkLoadError') {
+        return true;
+    }
+
+    if (CHUNK_LOAD_ERROR_MESSAGE_PATTERN.test(errorDetails)) {
+        return true;
+    }
+
+    return (
+        DYNAMIC_IMPORT_FETCH_ERROR_MESSAGE_PATTERN.test(errorDetails) &&
+        NEXT_BUILD_ASSET_PATH_PATTERN.test(errorDetails)
+    );
+}
+
 /**
  * Formats descriptive text shown beneath the application error headline.
  *
@@ -170,6 +211,10 @@ export function createApplicationErrorDigest(error: ApplicationBoundaryError | n
  * @returns Friendly summary of what happened.
  */
 export function describeApplicationError(error: ApplicationBoundaryError | null, serverName: string): string {
+    if (isApplicationErrorRecoverableByHardRefresh(error)) {
+        return `The browser could not load the latest application files for ${serverName}. Refreshing the page usually resolves this after a deployment or stale cached shell.`;
+    }
+
     if (error?.message) {
         return `${error.message.trim()} - the server for ${serverName} logged this failure.`;
     }

package/apps/agents-server/src/utils/errorReporting/refreshApplicationDocument.ts

@@ -0,0 +1,10 @@
+/**
+ * Reloads the current browser document so stale build assets can be fetched again.
+ */
+export function refreshApplicationDocument(): void {
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    window.location.reload();
+}