@promptbook/cli 0.112.0-110 → 0.112.0-112

package/apps/agents-server/src/database/customStylesheet.ts

@@ -7,6 +7,11 @@ import { $provideSupabase } from './$provideSupabase';
  */
 const CUSTOM_STYLESHEET_TABLE_BASENAME = 'CustomStylesheet';
 
+/**
+ * Process-level cache lifetime for custom stylesheet rows.
+ */
+const CUSTOM_STYLESHEET_CACHE_TTL_MS = 30_000;
+
 /**
  * Stored CustomStylesheet row shape.
  *
@@ -82,6 +87,28 @@ type DynamicSupabaseClient = {
     from: (tableName: string) => DynamicCustomStylesheetTableQuery;
 };
 
+/**
+ * Cached custom stylesheet rows keyed by the resolved table name.
+ *
+ * @private
+ */
+const cachedCustomStylesheetsByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly rowsPromise: Promise<CustomStylesheetRow[]>;
+    }
+>();
+
+/**
+ * Clears process-level stylesheet cache after admin writes.
+ *
+ * @public
+ */
+export function invalidateCustomStylesheetCache(): void {
+    cachedCustomStylesheetsByTableName.clear();
+}
+
 /**
  * Resolves the prefixed table name for CustomStylesheet.
  *
@@ -127,8 +154,37 @@ function getCustomStylesheetClient(): DynamicSupabaseClient {
  */
 export async function listCustomStylesheets(): Promise<CustomStylesheetRow[]> {
     const table = await getCustomStylesheetTableName();
-    const supabase = getCustomStylesheetClient();
+    const cachedStylesheets = cachedCustomStylesheetsByTableName.get(table);
+    if (cachedStylesheets && Date.now() - cachedStylesheets.loadedAt < CUSTOM_STYLESHEET_CACHE_TTL_MS) {
+        return cachedStylesheets.rowsPromise;
+    }
+
+    const rowsPromise = loadCustomStylesheetsFromDatabase(table);
+    cachedCustomStylesheetsByTableName.set(table, {
+        loadedAt: Date.now(),
+        rowsPromise,
+    });
+
+    try {
+        return await rowsPromise;
+    } catch (error) {
+        if (cachedCustomStylesheetsByTableName.get(table)?.rowsPromise === rowsPromise) {
+            cachedCustomStylesheetsByTableName.delete(table);
+        }
+        throw error;
+    }
+}
 
+/**
+ * Reads custom stylesheet rows from the database.
+ *
+ * @param table - Resolved CustomStylesheet table name.
+ * @returns Stored stylesheet rows.
+ *
+ * @private
+ */
+async function loadCustomStylesheetsFromDatabase(table: string): Promise<CustomStylesheetRow[]> {
+    const supabase = getCustomStylesheetClient();
     const { data, error } = await supabase.from(table).select('*').order('createdAt', { ascending: true });
 
     if (error) {
@@ -206,6 +262,7 @@ export async function saveCustomStylesheetFile({
         throw new Error(`Failed to save custom stylesheet: ${error.message || String(error)}`);
     }
 
+    invalidateCustomStylesheetCache();
     return data as CustomStylesheetRow;
 }
 
@@ -229,4 +286,6 @@ export async function deleteCustomStylesheetFile(id: number): Promise<void> {
 
         throw new Error(`Failed to delete custom stylesheet: ${error.message || String(error)}`);
     }
+
+    invalidateCustomStylesheetCache();
 }

package/apps/agents-server/src/database/getMetadata.ts

@@ -10,6 +10,45 @@ import { cache } from 'react';
  */
 const metadataDefaultsMap = new Map<string, string>(metadataDefaults.map((metadata) => [metadata.key, metadata.value]));
 
+/**
+ * Process-level cache lifetime for metadata reads.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+const METADATA_CACHE_TTL_MS = 30_000;
+
+/**
+ * Cached metadata table payload keyed by the resolved table name.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+const cachedMetadataValuesByTableName = new Map<
+    string,
+    {
+        readonly loadedAt: number;
+        readonly valuesPromise: Promise<Map<string, string | null>>;
+    }
+>();
+
+/**
+ * Metadata row shape loaded by the lightweight metadata select.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+type MetadataValueRow = {
+    readonly key: string;
+    readonly value: string | null;
+};
+
+/**
+ * Clears process-level metadata cache after admin metadata writes.
+ *
+ * @public exported from `apps/agents-server`
+ */
+export function invalidateMetadataCache(): void {
+    cachedMetadataValuesByTableName.clear();
+}
+
 /**
  * Loads the full metadata table once per request so callers can cheaply project subsets.
  *
@@ -18,17 +57,59 @@ const metadataDefaultsMap = new Map<string, string>(metadataDefaults.map((metada
  * @private Internal helper for batched metadata lookups in `apps/agents-server`.
  */
 const loadAllMetadataValues = cache(async (): Promise<Map<string, string | null>> => {
-    const supabase = $provideSupabase();
     const table = await $getTableName('Metadata');
+    return loadCachedMetadataValues(table);
+});
+
+/**
+ * Loads metadata values using a short process-level cache shared by consecutive requests.
+ *
+ * @param table - Resolved metadata table name.
+ * @returns Metadata values keyed by metadata key.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+async function loadCachedMetadataValues(table: string): Promise<Map<string, string | null>> {
+    const cachedMetadataValues = cachedMetadataValuesByTableName.get(table);
+    if (cachedMetadataValues && Date.now() - cachedMetadataValues.loadedAt < METADATA_CACHE_TTL_MS) {
+        return cachedMetadataValues.valuesPromise;
+    }
+
+    const valuesPromise = loadMetadataValuesFromDatabase(table);
+    cachedMetadataValuesByTableName.set(table, {
+        loadedAt: Date.now(),
+        valuesPromise,
+    });
+
+    try {
+        return await valuesPromise;
+    } catch (error) {
+        if (cachedMetadataValuesByTableName.get(table)?.valuesPromise === valuesPromise) {
+            cachedMetadataValuesByTableName.delete(table);
+        }
+        throw error;
+    }
+}
+
+/**
+ * Reads all persisted metadata values from the database.
+ *
+ * @param table - Resolved metadata table name.
+ * @returns Metadata values keyed by metadata key.
+ *
+ * @private Internal helper for metadata lookups in `apps/agents-server`.
+ */
+async function loadMetadataValuesFromDatabase(table: string): Promise<Map<string, string | null>> {
+    const supabase = $provideSupabase();
     const { data } = await supabase.from(table).select('key, value');
 
     const loadedMap = new Map<string, string | null>();
-    for (const row of data ?? []) {
+    for (const row of (data ?? []) as Array<MetadataValueRow>) {
         loadedMap.set(row.key, row.value);
     }
 
     return loadedMap;
-});
+}
 
 /**
  * Get metadata value by key

package/apps/agents-server/src/instrumentation.ts

@@ -10,6 +10,9 @@ export async function register(): Promise<void> {
     }
 
     try {
+        const { registerServerErrorSentryLogging } = await import('./utils/errorReporting/registerServerErrorSentryLogging');
+        registerServerErrorSentryLogging();
+
         const { registerNodeRuntimeInstrumentation } = await import('./instrumentation-node');
         await registerNodeRuntimeInstrumentation();
     } catch (error) {

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();
+}