@promptbook/cli 0.112.0-110 → 0.112.0-112

package/apps/agents-server/src/app/admin/servers/CreateServerDialog.tsx

@@ -203,6 +203,22 @@ function CreateServerForm(props: {
                 ) : null}
             </div>
 
+            <div className="rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm text-gray-600">
+                <label htmlFor="create-server-default-agents" className="flex items-start gap-3">
+                    <input
+                        id="create-server-default-agents"
+                        type="checkbox"
+                        checked={wizardState.isDefaultAgentsInstalled}
+                        onChange={(event) => updateWizardField('isDefaultAgentsInstalled', event.target.checked)}
+                        className="mt-0.5 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                    />
+                    <span>
+                        <span className="block font-semibold text-gray-900">Install default agents</span>
+                        <span className="mt-1 block">Create bundled starter agents from agents/default.</span>
+                    </span>
+                </label>
+            </div>
+
             <div className="rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm text-gray-600">
                 <p className="font-semibold text-gray-900">Admin user exists</p>
                 <p className="mt-1">

package/apps/agents-server/src/app/admin/servers/useCreateServerWizard.ts

@@ -121,6 +121,11 @@ export type CreateServerWizardState = {
      */
     additionalUsers: WizardUser[];
 
+    /**
+     * Whether bundled default agents should be installed during server creation.
+     */
+    isDefaultAgentsInstalled: boolean;
+
     /**
      * Initial metadata values.
      */
@@ -155,7 +160,10 @@ export type CreateServerWizardError = {
  * @private function of <ServersClient/>
  */
 export type UpdateCreateServerWizardField = <
-    TFieldName extends keyof Pick<CreateServerWizardState, 'name' | 'domain' | 'iconUrl'>,
+    TFieldName extends keyof Pick<
+        CreateServerWizardState,
+        'name' | 'domain' | 'iconUrl' | 'isDefaultAgentsInstalled'
+    >,
 >(
     fieldName: TFieldName,
     value: CreateServerWizardState[TFieldName],
@@ -262,6 +270,7 @@ function createInitialWizardState(): CreateServerWizardState {
             password: '',
         },
         additionalUsers: [],
+        isDefaultAgentsInstalled: true,
         initialSettings: {
             language: 'en',
             homepageMessage: '',
@@ -345,7 +354,8 @@ function hasCreateServerWizardChanges(wizardState: CreateServerWizardState): boo
         wizardState.name !== initialWizardState.name ||
         wizardState.identifier !== initialWizardState.identifier ||
         wizardState.domain !== initialWizardState.domain ||
-        wizardState.iconUrl !== initialWizardState.iconUrl
+        wizardState.iconUrl !== initialWizardState.iconUrl ||
+        wizardState.isDefaultAgentsInstalled !== initialWizardState.isDefaultAgentsInstalled
     );
 }
 
@@ -402,16 +412,32 @@ export function useCreateServerWizard(options: UseCreateServerWizardOptions): Us
     const updateWizardField = useCallback<UpdateCreateServerWizardField>((fieldName, value) => {
         setWizardState((previous) => {
             if (fieldName === 'name') {
+                const name = value as CreateServerWizardState['name'];
+
+                return {
+                    ...previous,
+                    name,
+                    identifier: createServerIdentifierFromName(name),
+                };
+            }
+
+            if (fieldName === 'domain') {
+                return {
+                    ...previous,
+                    domain: value as CreateServerWizardState['domain'],
+                };
+            }
+
+            if (fieldName === 'iconUrl') {
                 return {
                     ...previous,
-                    name: value,
-                    identifier: createServerIdentifierFromName(value),
+                    iconUrl: value as CreateServerWizardState['iconUrl'],
                 };
             }
 
             return {
                 ...previous,
-                [fieldName]: value,
+                isDefaultAgentsInstalled: value as CreateServerWizardState['isDefaultAgentsInstalled'],
             };
         });
     }, []);

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/app/api/admin/servers/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { spaceTrim } from 'spacetrim';
 import { DatabaseError } from '../../../../../../../src/errors/DatabaseError';
 import { isAgentsServerSqliteMode } from '../../../../database/agentsServerDatabaseMode';
+import { seedDefaultAgents } from '../../../../database/seedDefaultAgents';
 import { resolveCurrentServerRegistryContext } from '../../../../utils/currentServerRegistryContext';
 import { isUserAdmin } from '../../../../utils/isUserAdmin';
 import { isUserGlobalAdmin } from '../../../../utils/isUserGlobalAdmin';
@@ -97,6 +98,7 @@ export async function POST(request: Request) {
 
         const body = withEnvironmentAdminUser((await request.json()) as CreateServerInput);
         if (isAgentsServerSqliteMode()) {
+            const isDefaultAgentsInstalled = body.isDefaultAgentsInstalled !== false;
             const normalizedDomain = normalizeServerDomain(body.domain);
             if (!normalizedDomain) {
                 return NextResponse.json({ error: 'A valid domain is required.' }, { status: 400 });
@@ -114,6 +116,9 @@ export async function POST(request: Request) {
                     iconUrl: body.iconUrl,
                 });
             }
+            if (isDefaultAgentsInstalled) {
+                await seedDefaultAgents({ tablePrefix });
+            }
 
             return NextResponse.json(
                 {

package/apps/agents-server/src/app/api/metadata/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { keepUnused } from '../../../../../../src/utils/organization/keepUnused';
 import { $getTableName } from '../../../database/$getTableName';
 import { $provideSupabase } from '../../../database/$provideSupabase';
+import { invalidateMetadataCache } from '../../../database/getMetadata';
 import { validateMetadataValue } from '../../../database/metadataDefaults';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
 
@@ -121,6 +122,7 @@ export async function POST(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json(data);
 }
 
@@ -152,6 +154,7 @@ export async function PUT(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json(data);
 }
 
@@ -179,5 +182,6 @@ export async function DELETE(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json({ success: true });
 }

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/database/customJavascript.ts

@@ -14,6 +14,13 @@ export const MAX_CUSTOM_JAVASCRIPT_LENGTH = 100_000;
  */
 const CUSTOM_JAVASCRIPT_TABLE_BASENAME = 'CustomJavascript';
 
+/**
+ * Process-level cache lifetime for custom JavaScript rows.
+ *
+ * @private
+ */
+const CUSTOM_JAVASCRIPT_CACHE_TTL_MS = 30_000;
+
 /**
  * Stored `CustomJavascript` row shape.
  *
@@ -90,6 +97,28 @@ type DynamicSupabaseClient = {
     from: (tableName: string) => DynamicCustomJavascriptTableQuery;
 };
 
+/**
+ * Cached custom JavaScript rows keyed by the resolved table name.
+ *
+ * @private
+ */
+const cachedCustomJavascriptByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly rowsPromise: Promise<CustomJavascriptRow[]>;
+    }
+>();
+
+/**
+ * Clears process-level custom JavaScript cache after admin writes.
+ *
+ * @private
+ */
+export function invalidateCustomJavascriptCache(): void {
+    cachedCustomJavascriptByTableName.clear();
+}
+
 /**
  * Resolves the prefixed table name for `CustomJavascript`.
  *
@@ -137,8 +166,37 @@ function getCustomJavascriptClient() {
  */
 export async function getCustomJavascriptFiles(): Promise<CustomJavascriptRow[]> {
     const table = await getCustomJavascriptTableName();
-    const supabase = getCustomJavascriptClient();
+    const cachedJavascript = cachedCustomJavascriptByTableName.get(table);
+    if (cachedJavascript && Date.now() - cachedJavascript.loadedAt < CUSTOM_JAVASCRIPT_CACHE_TTL_MS) {
+        return cachedJavascript.rowsPromise;
+    }
+
+    const rowsPromise = loadCustomJavascriptFilesFromDatabase(table);
+    cachedCustomJavascriptByTableName.set(table, {
+        loadedAt: Date.now(),
+        rowsPromise,
+    });
+
+    try {
+        return await rowsPromise;
+    } catch (error) {
+        if (cachedCustomJavascriptByTableName.get(table)?.rowsPromise === rowsPromise) {
+            cachedCustomJavascriptByTableName.delete(table);
+        }
+        throw error;
+    }
+}
 
+/**
+ * Reads custom JavaScript rows from the database.
+ *
+ * @param table - Resolved CustomJavascript table name.
+ * @returns Stored JavaScript rows.
+ *
+ * @private
+ */
+async function loadCustomJavascriptFilesFromDatabase(table: string): Promise<CustomJavascriptRow[]> {
+    const supabase = getCustomJavascriptClient();
     const { data, error } = await supabase.from(table).select('*').order('scope', { ascending: true });
 
     if (error) {
@@ -234,6 +292,7 @@ export async function saveCustomJavascriptFile({
         throw new Error(`Failed to save custom JavaScript: ${error.message || String(error)}`);
     }
 
+    invalidateCustomJavascriptCache();
     return data as CustomJavascriptRow;
 }
 
@@ -255,4 +314,6 @@ export async function deleteCustomJavascriptFile(id: number): Promise<void> {
 
         throw new Error(`Failed to delete custom JavaScript: ${error.message || String(error)}`);
     }
+
+    invalidateCustomJavascriptCache();
 }