@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/app/admin/chat-history/useChatHistoryState.ts

@@ -1,16 +1,26 @@
 import type { ChatMessage, string_date_iso8601 } from '@promptbook-local/types';
 import { useCallback, useEffect, useMemo, useState, type ChangeEvent, type FormEvent } from 'react';
 import { showConfirm } from '../../../components/AsyncDialogs/asyncDialogs';
+import { notifyError, notifySuccess } from '../../../components/Notifications/notifications';
+import { resolveNextAdminTableSortState } from '../_components/adminTableSorting';
 import {
     $clearAgentChatHistory,
     $deleteChatHistoryRow,
     $fetchChatHistory,
+    $fetchChatHistoryThreads,
     type ChatHistoryListParams,
     type ChatHistoryListResponse,
     type ChatHistoryRow,
     type ChatHistorySortField,
     type ChatHistorySortOrder,
+    type ChatHistoryThread,
 } from '../../../utils/chatHistoryAdmin';
+import { resolveChatHistoryMessageSender, resolveChatHistoryMessageText } from '../../../utils/chatHistoryMessage';
+import {
+    $saveMockedChatPresetFromMessages,
+    MOCKED_CHATS_EDITOR_ROUTE,
+} from '../../../utils/mockedChats/$saveMockedChatPresetFromMessages';
+import type { MockedChatSourceMessage } from '../../../utils/mockedChats/createMockedChatPresetFromChatMessages';
 
 /**
  * Default page size used in the table view.
@@ -62,6 +72,18 @@ type UseChatHistoryStateProps = {
      * Optional initial agent filter, taken from the URL query.
      */
     initialAgentName?: string;
+    /**
+     * Optional initial chat thread filter, taken from the URL query.
+     */
+    initialChatId?: string;
+    /**
+     * Optional initial user filter, taken from the URL query.
+     */
+    initialUserId?: number;
+    /**
+     * Optional initial view mode, taken from the URL query.
+     */
+    initialViewMode?: ChatHistoryViewMode;
     /**
      * Active text formatter for agent naming.
      */
@@ -81,7 +103,13 @@ export type UseChatHistoryState = {
     pageSize: number;
     totalPages: number;
     agentName: string;
+    chatId: string;
+    userId: number | undefined;
+    threads: ChatHistoryThread[];
+    threadsLoading: boolean;
+    selectedThread: ChatHistoryThread | null;
     searchInput: string;
+    sortBy: ChatHistorySortField;
     sortOrder: ChatHistorySortOrder;
     viewMode: ChatHistoryViewMode;
     loading: boolean;
@@ -92,12 +120,15 @@ export type UseChatHistoryState = {
     handleSearchInputChange: (event: ChangeEvent<HTMLInputElement>) => void;
     handleSearchSubmit: (event: FormEvent<HTMLFormElement>) => void;
     handleAgentChange: (event: ChangeEvent<HTMLSelectElement>) => void;
+    handleChatThreadChange: (chatId: string) => void;
     handlePageSizeChange: (event: ChangeEvent<HTMLSelectElement>) => void;
     handleSortChange: (field: ChatHistorySortField) => void;
     handleViewModeChange: (mode: ChatHistoryViewMode) => void;
     handleDeleteRow: (row: ChatHistoryRow) => Promise<void>;
     handleClearAgentHistory: () => Promise<void>;
-    isSortedBy: (field: ChatHistorySortField) => boolean;
+    handleCreateMockFromRow: (row: ChatHistoryRow) => Promise<void>;
+    handleCreateMockFromChatView: () => Promise<void>;
+    isCreatingMock: boolean;
     goToPreviousPage: () => void;
     goToNextPage: () => void;
 };
@@ -125,17 +156,24 @@ function mapAdminAgents(data: AgentsApiResponse): AdminAgentInfo[] {
  * Builds fetch params for the current chat history view state.
  */
 function createChatHistoryListParams(
-    state: Pick<UseChatHistoryState, 'page' | 'pageSize' | 'agentName'> & {
+    state: Pick<UseChatHistoryState, 'page' | 'pageSize' | 'agentName' | 'chatId' | 'userId'> & {
         search: string;
         sortBy: ChatHistorySortField;
         sortOrder: ChatHistorySortOrder;
     },
     overrides: Partial<ChatHistoryListParams> = {},
 ): ChatHistoryListParams {
+    const chatId = state.chatId || undefined;
+
     return {
         page: state.page,
         pageSize: state.pageSize,
-        agentName: state.agentName || undefined,
+        // Note: A chat thread belongs to exactly one agent, so a selected `chatId` fully
+        // determines the rows and the redundant `agentName` filter is dropped. This keeps
+        // deep-links robust even when the agent was addressed by permanent id.
+        agentName: chatId ? undefined : state.agentName || undefined,
+        chatId,
+        userId: state.userId,
         search: state.search || undefined,
         sortBy: state.sortBy,
         sortOrder: state.sortOrder,
@@ -170,31 +208,23 @@ function getChatHistoryViewSettings(mode: ChatHistoryViewMode): ChatHistoryViewS
 }
 
 /**
- * Builds the CSV export URL for the active agent filter.
+ * Builds the CSV export URL for the active agent and chat thread filters.
  */
-function getChatHistoryExportUrl(agentName: string): string {
+function getChatHistoryExportUrl(agentName: string, chatId: string, userId?: number): string {
     const params = new URLSearchParams();
 
-    if (agentName) {
+    if (chatId) {
+        // Note: A selected chat thread fully determines the exported rows (see `createChatHistoryListParams`)
+        params.set('chatId', chatId);
+    } else if (agentName) {
         params.set('agentName', agentName);
     }
 
-    return `/api/chat-history/export?${params.toString()}`;
-}
-
-/**
- * Converts one stored chat message into the sender used by <MockedChat/>.
- */
-function resolveChatHistoryMessageSender(message: unknown): ChatMessage['sender'] {
-    const role = ((message as { role?: string }).role || 'USER').toUpperCase();
-    return role === 'USER' ? 'USER' : 'ASSISTANT';
-}
+    if (userId) {
+        params.set('userId', String(userId));
+    }
 
-/**
- * Converts one stored chat message into the content used by <MockedChat/>.
- */
-function resolveChatHistoryMessageContent(message: unknown): ChatMessage['content'] {
-    return (message as { content?: ChatMessage['content'] }).content || JSON.stringify(message);
+    return `/api/chat-history/export?${params.toString()}`;
 }
 
 /**
@@ -208,12 +238,30 @@ function createChatHistoryMessages(items: ChatHistoryRow[], viewMode: ChatHistor
     return items.map((row) => ({
         id: String(row.id),
         sender: resolveChatHistoryMessageSender(row.message),
-        content: resolveChatHistoryMessageContent(row.message),
+        content: resolveChatHistoryMessageText(row.message) || JSON.stringify(row.message),
         isComplete: true,
         createdAt: row.createdAt as string_date_iso8601,
     }));
 }
 
+/**
+ * Converts one stored chat history row into a mocked-chat source message.
+ */
+function mapChatHistoryRowToMockedChatSourceMessage(row: ChatHistoryRow): MockedChatSourceMessage {
+    return {
+        sender: String(resolveChatHistoryMessageSender(row.message)),
+        content: resolveChatHistoryMessageText(row.message) || JSON.stringify(row.message),
+        createdAt: row.createdAt,
+    };
+}
+
+/**
+ * Builds a human-readable mocked-chat preset name for one recorded chat.
+ */
+function createMockedChatNameFromRow(row: ChatHistoryRow): string {
+    return `${row.agentName} chat ${new Date(row.createdAt).toLocaleDateString('en-US')}`;
+}
+
 /**
  * Requests confirmation before deleting one chat history row.
  */
@@ -232,7 +280,9 @@ async function confirmDeleteChatMessage(): Promise<boolean> {
 async function confirmClearAgentHistory(agentName: string, formatText: (text: string) => string): Promise<boolean> {
     return showConfirm({
         title: 'Clear chat history',
-        message: `${formatText('Are you sure you want to permanently delete all chat history for agent')} "${agentName}"?`,
+        message: `${formatText(
+            'Are you sure you want to permanently delete all chat history for agent',
+        )} "${agentName}"?`,
         confirmLabel: 'Delete history',
         cancelLabel: 'Cancel',
     }).catch(() => false);
@@ -243,21 +293,33 @@ async function confirmClearAgentHistory(agentName: string, formatText: (text: st
  *
  * @private function of <ChatHistoryClient/>
  */
-export function useChatHistoryState({ initialAgentName, formatText }: UseChatHistoryStateProps): UseChatHistoryState {
+export function useChatHistoryState({
+    initialAgentName,
+    initialChatId,
+    initialUserId,
+    initialViewMode,
+    formatText,
+}: UseChatHistoryStateProps): UseChatHistoryState {
+    const initialViewSettings = getChatHistoryViewSettings(initialViewMode ?? 'table');
     const [items, setItems] = useState<ChatHistoryRow[]>([]);
     const [total, setTotal] = useState(0);
     const [page, setPage] = useState(1);
-    const [pageSize, setPageSize] = useState(TABLE_VIEW_PAGE_SIZE);
+    const [pageSize, setPageSize] = useState(initialViewSettings.pageSize);
     const [agentName, setAgentName] = useState(initialAgentName ?? '');
+    const [chatId, setChatId] = useState(initialChatId ?? '');
+    const [userId] = useState<number | undefined>(initialUserId);
+    const [threads, setThreads] = useState<ChatHistoryThread[]>([]);
+    const [threadsLoading, setThreadsLoading] = useState(false);
     const [searchInput, setSearchInput] = useState('');
     const [search, setSearch] = useState('');
-    const [sortBy, setSortBy] = useState<ChatHistorySortField>('createdAt');
-    const [sortOrder, setSortOrder] = useState<ChatHistorySortOrder>('desc');
-    const [viewMode, setViewMode] = useState<ChatHistoryViewMode>('table');
+    const [sortBy, setSortBy] = useState<ChatHistorySortField>(initialViewSettings.sortBy);
+    const [sortOrder, setSortOrder] = useState<ChatHistorySortOrder>(initialViewSettings.sortOrder);
+    const [viewMode, setViewMode] = useState<ChatHistoryViewMode>(initialViewMode ?? 'table');
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
     const [agents, setAgents] = useState<AdminAgentInfo[]>([]);
     const [agentsLoading, setAgentsLoading] = useState(false);
+    const [isCreatingMock, setIsCreatingMock] = useState(false);
 
     const applyChatHistoryResponse = useCallback((response: ChatHistoryListResponse) => {
         setItems(response.items);
@@ -272,6 +334,8 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
                         page,
                         pageSize,
                         agentName,
+                        chatId,
+                        userId,
                         search,
                         sortBy,
                         sortOrder,
@@ -279,7 +343,7 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
                     overrides,
                 ),
             ),
-        [page, pageSize, agentName, search, sortBy, sortOrder],
+        [page, pageSize, agentName, chatId, search, sortBy, sortOrder, userId],
     );
 
     useEffect(() => {
@@ -319,6 +383,43 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
         }
     }, [initialAgentName]);
 
+    useEffect(() => {
+        if (initialChatId) {
+            setChatId(initialChatId);
+        }
+    }, [initialChatId]);
+
+    useEffect(() => {
+        let isCancelled = false;
+
+        async function loadThreads() {
+            try {
+                setThreadsLoading(true);
+                const nextThreads = await $fetchChatHistoryThreads(agentName || undefined, userId);
+                if (isCancelled) {
+                    return;
+                }
+
+                setThreads(nextThreads);
+            } catch {
+                // Note: The thread list is a browsing aid; a failure must not break the message views
+                if (!isCancelled) {
+                    setThreads([]);
+                }
+            } finally {
+                if (!isCancelled) {
+                    setThreadsLoading(false);
+                }
+            }
+        }
+
+        loadThreads();
+
+        return () => {
+            isCancelled = true;
+        };
+    }, [agentName, userId]);
+
     useEffect(() => {
         let isCancelled = false;
 
@@ -361,10 +462,15 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
         return Math.max(1, Math.ceil(total / pageSize));
     }, [total, pageSize]);
 
-    const exportUrl = useMemo(() => getChatHistoryExportUrl(agentName), [agentName]);
+    const exportUrl = useMemo(() => getChatHistoryExportUrl(agentName, chatId, userId), [agentName, chatId, userId]);
 
     const chatMessages = useMemo(() => createChatHistoryMessages(items, viewMode), [items, viewMode]);
 
+    const selectedThread = useMemo(
+        () => (chatId ? threads.find((thread) => thread.chatId === chatId) ?? null : null),
+        [chatId, threads],
+    );
+
     const handleSearchInputChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
         setSearchInput(event.target.value);
     }, []);
@@ -380,9 +486,25 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
 
     const handleAgentChange = useCallback((event: ChangeEvent<HTMLSelectElement>) => {
         setAgentName(event.target.value);
+        // Note: Chat threads are scoped to a single agent, so switching agent clears the thread filter
+        setChatId('');
         setPage(1);
     }, []);
 
+    const handleChatThreadChange = useCallback(
+        (nextChatId: string) => {
+            setChatId(nextChatId);
+            setPage(1);
+
+            // Note: Selecting a thread also aligns the agent filter so both filters stay consistent
+            const nextThread = nextChatId ? threads.find((thread) => thread.chatId === nextChatId) : undefined;
+            if (nextThread && nextThread.agentName !== agentName) {
+                setAgentName(nextThread.agentName);
+            }
+        },
+        [agentName, threads],
+    );
+
     const handlePageSizeChange = useCallback((event: ChangeEvent<HTMLSelectElement>) => {
         const nextPageSize = parseInt(event.target.value, 10);
         if (!Number.isNaN(nextPageSize) && nextPageSize > 0) {
@@ -393,13 +515,16 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
 
     const handleSortChange = useCallback(
         (field: ChatHistorySortField) => {
-            if (sortBy === field) {
-                setSortOrder(sortOrder === 'asc' ? 'desc' : 'asc');
-                return;
-            }
-
-            setSortBy(field);
-            setSortOrder(field === 'createdAt' ? 'desc' : 'asc');
+            const nextSortState = resolveNextAdminTableSortState({
+                currentSortBy: sortBy,
+                currentSortOrder: sortOrder,
+                nextSortBy: field,
+                resolveDefaultSortOrder: (nextSortBy) => (nextSortBy === 'createdAt' ? 'desc' : 'asc'),
+            });
+
+            setSortBy(nextSortState.sortBy);
+            setSortOrder(nextSortState.sortOrder);
+            setPage(1);
         },
         [sortBy, sortOrder],
     );
@@ -457,7 +582,66 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
         }
     }, [agentName, applyChatHistoryResponse, formatText, loadChatHistory]);
 
-    const isSortedBy = useCallback((field: ChatHistorySortField) => sortBy === field, [sortBy]);
+    const createMockAndNavigate = useCallback(
+        async (name: string, messages: ReadonlyArray<MockedChatSourceMessage>): Promise<void> => {
+            if (isCreatingMock) {
+                return;
+            }
+
+            if (messages.length === 0) {
+                notifyError('There are no messages to create a mocked chat from.');
+                return;
+            }
+
+            try {
+                setIsCreatingMock(true);
+                await $saveMockedChatPresetFromMessages({ name, messages });
+                notifySuccess('Mocked chat was created.');
+                window.location.href = MOCKED_CHATS_EDITOR_ROUTE;
+            } catch (actionError) {
+                notifyError(resolveChatHistoryActionErrorMessage(actionError, 'Failed to create the mocked chat'));
+            } finally {
+                setIsCreatingMock(false);
+            }
+        },
+        [isCreatingMock],
+    );
+
+    const handleCreateMockFromRow = useCallback(
+        async (row: ChatHistoryRow): Promise<void> => {
+            let mockSourceRows: ChatHistoryRow[] = [row];
+
+            if (row.chatId) {
+                try {
+                    const chatResponse = await $fetchChatHistory({
+                        chatId: row.chatId,
+                        pageSize: CHAT_VIEW_PAGE_SIZE,
+                        sortBy: 'createdAt',
+                        sortOrder: 'asc',
+                    });
+                    if (chatResponse.items.length > 0) {
+                        mockSourceRows = chatResponse.items;
+                    }
+                } catch {
+                    // Note: Falling back to the single row keeps the button usable when the chat lookup fails
+                }
+            }
+
+            await createMockAndNavigate(
+                createMockedChatNameFromRow(row),
+                mockSourceRows.map(mapChatHistoryRowToMockedChatSourceMessage),
+            );
+        },
+        [createMockAndNavigate],
+    );
+
+    const handleCreateMockFromChatView = useCallback(async (): Promise<void> => {
+        const firstRow = items[0];
+        await createMockAndNavigate(
+            firstRow ? createMockedChatNameFromRow(firstRow) : 'Recorded chat',
+            items.map(mapChatHistoryRowToMockedChatSourceMessage),
+        );
+    }, [createMockAndNavigate, items]);
 
     const goToPreviousPage = useCallback(() => {
         setPage((previousPage) => Math.max(1, previousPage - 1));
@@ -475,7 +659,13 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
         pageSize,
         totalPages,
         agentName,
+        chatId,
+        userId,
+        threads,
+        threadsLoading,
+        selectedThread,
         searchInput,
+        sortBy,
         sortOrder,
         viewMode,
         loading,
@@ -486,12 +676,15 @@ export function useChatHistoryState({ initialAgentName, formatText }: UseChatHis
         handleSearchInputChange,
         handleSearchSubmit,
         handleAgentChange,
+        handleChatThreadChange,
         handlePageSizeChange,
         handleSortChange,
         handleViewModeChange,
         handleDeleteRow,
         handleClearAgentHistory,
-        isSortedBy,
+        handleCreateMockFromRow,
+        handleCreateMockFromChatView,
+        isCreatingMock,
         goToPreviousPage,
         goToNextPage,
     };

package/apps/agents-server/src/app/admin/core-agents/page.tsx

@@ -0,0 +1,143 @@
+import { MarkdownContent } from '@promptbook-local/components';
+import Link from 'next/link';
+import { ReinstateBundledAgentsButton } from '../../../components/DefaultAgents/ReinstateBundledAgentsButton';
+import { ForbiddenPage } from '../../../components/ForbiddenPage/ForbiddenPage';
+import { resolveDefaultAgentsStatus, type CoreAgentReport } from '../../../utils/defaultAgents/resolveDefaultAgentsStatus';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
+
+/**
+ * Force dynamic rendering so the core-agent presence always reflects the live database.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Builds the link to the editable book of one present core agent.
+ *
+ * @param coreAgent - Core agent report row.
+ * @returns Book editor path, or `null` when the agent is missing.
+ */
+function resolveCoreAgentBookHref(coreAgent: CoreAgentReport): string | null {
+    const agentIdentifier = coreAgent.permanentId ?? coreAgent.agentName;
+    if (!coreAgent.isPresent) {
+        return null;
+    }
+    return `/agents/${encodeURIComponent(agentIdentifier)}/book`;
+}
+
+/**
+ * Admin page that tracks whether all core agents are present and explains why each one exists.
+ */
+export default async function CoreAgentsPage() {
+    if (!(await isUserAdmin())) {
+        return <ForbiddenPage />;
+    }
+
+    const { coreAgents, isAnyCoreAgentMissing } = await resolveDefaultAgentsStatus();
+    const missingCoreAgentCount = coreAgents.filter((coreAgent) => !coreAgent.isPresent).length;
+
+    return (
+        <div className="w-full max-w-screen-lg mx-auto px-2 py-8 sm:px-4 md:px-8">
+            <div className="mt-20 mb-8 space-y-3">
+                <h1 className="text-3xl font-light text-gray-900 dark:text-gray-100">Core agents</h1>
+                <p className="max-w-3xl text-sm text-gray-500 dark:text-gray-400">
+                    Core agents are bundled in the <code>.core</code> folder and are used as a base for every other agent
+                    on this server. This page tracks whether all core agents are present and explains why each one
+                    exists.
+                </p>
+            </div>
+
+            {isAnyCoreAgentMissing ? (
+                <section className="mb-8 rounded-2xl border border-amber-300 bg-amber-50 p-5 text-amber-900 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-100">
+                    <h2 className="text-lg font-semibold">
+                        {missingCoreAgentCount} core{' '}
+                        {missingCoreAgentCount === 1 ? 'agent is' : 'agents are'} missing
+                    </h2>
+                    <p className="mt-1 text-sm">
+                        Reinstate the missing core agents with a single click. Existing core agents are left untouched,
+                        so any edits you made are preserved.
+                    </p>
+                    <div className="mt-4">
+                        <ReinstateBundledAgentsButton
+                            scope="core"
+                            label="Reinstate core agents"
+                            pendingLabel="Reinstating…"
+                            confirmMessage="Recreate the missing core agents from the bundled repository books?"
+                            className="inline-flex items-center rounded-lg bg-amber-600 px-4 py-2 text-sm font-semibold text-white shadow-sm transition hover:bg-amber-700 disabled:cursor-not-allowed disabled:opacity-60"
+                        />
+                    </div>
+                </section>
+            ) : (
+                <section className="mb-8 rounded-2xl border border-emerald-300 bg-emerald-50 p-5 text-emerald-900 dark:border-emerald-500/40 dark:bg-emerald-500/10 dark:text-emerald-100">
+                    <h2 className="text-lg font-semibold">All core agents are present</h2>
+                    <p className="mt-1 text-sm">
+                        Every bundled core agent exists on this server. Editing a core agent is fine — differences from
+                        the bundled repository version are shown below for reference only.
+                    </p>
+                </section>
+            )}
+
+            <div className="space-y-4">
+                {coreAgents.map((coreAgent) => (
+                    <CoreAgentCard key={coreAgent.agentName} coreAgent={coreAgent} />
+                ))}
+            </div>
+        </div>
+    );
+}
+
+/**
+ * Renders one core agent row with its presence, repository difference, explanation, and edit link.
+ *
+ * @param props - Core agent report row.
+ */
+function CoreAgentCard({ coreAgent }: { readonly coreAgent: CoreAgentReport }) {
+    const bookHref = resolveCoreAgentBookHref(coreAgent);
+
+    return (
+        <article className="rounded-2xl border border-gray-200 bg-white p-5 shadow-sm dark:border-gray-700 dark:bg-gray-900">
+            <div className="flex flex-wrap items-center justify-between gap-3">
+                <div className="flex flex-wrap items-center gap-2">
+                    <h3 className="text-xl font-semibold text-gray-900 dark:text-gray-100">{coreAgent.title}</h3>
+                    <code className="text-xs text-gray-400">{coreAgent.agentName}</code>
+                </div>
+                <div className="flex flex-wrap items-center gap-2">
+                    {coreAgent.isPresent ? (
+                        <span className="inline-flex items-center rounded-full bg-emerald-100 px-3 py-1 text-xs font-medium text-emerald-800 dark:bg-emerald-500/15 dark:text-emerald-200">
+                            Present
+                        </span>
+                    ) : (
+                        <span className="inline-flex items-center rounded-full bg-amber-100 px-3 py-1 text-xs font-medium text-amber-800 dark:bg-amber-500/15 dark:text-amber-200">
+                            Missing
+                        </span>
+                    )}
+                    {coreAgent.isPresent && coreAgent.isDifferentFromRepository && (
+                        // Note: An edited core agent is fine — this chip is informational and intentionally neutral.
+                        <span className="inline-flex items-center rounded-full bg-gray-100 px-3 py-1 text-xs font-medium text-gray-600 dark:bg-gray-700 dark:text-gray-300">
+                            Edited (differs from repository)
+                        </span>
+                    )}
+                    {coreAgent.isPresent && !coreAgent.isDifferentFromRepository && (
+                        <span className="inline-flex items-center rounded-full bg-gray-100 px-3 py-1 text-xs font-medium text-gray-500 dark:bg-gray-700 dark:text-gray-400">
+                            Matches repository
+                        </span>
+                    )}
+                </div>
+            </div>
+
+            <div className="prose prose-sm prose-slate mt-3 max-w-none dark:prose-invert">
+                <MarkdownContent content={coreAgent.explanation} />
+            </div>
+
+            {bookHref && (
+                <div className="mt-4">
+                    <Link
+                        href={bookHref}
+                        className="text-sm font-medium text-blue-600 underline underline-offset-2 hover:text-blue-700 dark:text-blue-400"
+                    >
+                        Edit agent book
+                    </Link>
+                </div>
+            )}
+        </article>
+    );
+}

package/apps/agents-server/src/app/admin/email-server/actions.ts

@@ -0,0 +1,33 @@
+'use server';
+
+import { NotAllowed } from '../../../../../../src/errors/NotAllowed';
+import { spaceTrim } from '../../../../../../src/utils/organization/spaceTrim';
+import { revalidatePath } from 'next/cache';
+import { $provideServer } from '../../../tools/$provideServer';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
+import {
+    captureStalwartSynchronizationResult,
+    type StalwartSynchronizationResult,
+} from '../../../utils/stalwart/captureStalwartSynchronizationResult';
+import { synchronizeStalwartEmailDomain } from '../../../utils/stalwart/synchronizeStalwartEmailDomain';
+
+/**
+ * Synchronizes the current server's agents and transport settings to Stalwart.
+ */
+export async function $synchronizeStalwartEmailDomain(): Promise<StalwartSynchronizationResult> {
+    if (!(await isUserAdmin())) {
+        throw new NotAllowed(
+            spaceTrim(`
+                You are not allowed to synchronize the Stalwart email server.
+            `),
+        );
+    }
+
+    const server = await $provideServer();
+    const result = await captureStalwartSynchronizationResult(() =>
+        synchronizeStalwartEmailDomain(server.publicUrl.hostname),
+    );
+    revalidatePath('/admin/email-server');
+    revalidatePath('/superadmin/email-server');
+    return result;
+}