@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/app/admin/usage/UsageClientAnalyticsPanels.tsx

@@ -3,6 +3,8 @@ import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry'
 import type { UsageAnalyticsResponse, UsageMetricMode } from '@/src/utils/usageAdmin';
 import type { ReactNode } from 'react';
 import { useMemo } from 'react';
+import { AdminSortableTableHeaderCell } from '../_components/AdminSortableTableHeaderCell';
+import { useAdminTableSorting, type AdminTableSortOrder } from '../_components/adminTableSorting';
 import { UsageClientFormatting } from './UsageClientFormatting';
 import { UsageClientTimelineChart } from './UsageClientTimelineChart';
 
@@ -238,6 +240,11 @@ type UsageClientSimpleCountTableRow = {
     humanDuration: number;
 };
 
+/**
+ * Sortable columns for usage count tables.
+ */
+type UsageClientSimpleCountTableSortField = 'label' | 'calls' | 'tokens' | 'metric';
+
 /**
  * Props for `<UsageClientSimpleCountTable/>`.
  */
@@ -252,6 +259,13 @@ type UsageClientSimpleCountTableProps = {
  */
 function UsageClientSimpleCountTable(props: UsageClientSimpleCountTableProps) {
     const { rows, metric, emptyLabel } = props;
+    const sortedTable = useAdminTableSorting<UsageClientSimpleCountTableRow, UsageClientSimpleCountTableSortField>({
+        rows,
+        defaultSortBy: 'metric',
+        defaultSortOrder: 'desc',
+        resolveDefaultSortOrder: resolveUsageClientSimpleCountTableDefaultSortOrder,
+        resolveSortValue: (row, sortBy) => resolveUsageClientSimpleCountTableSortValue(row, sortBy, metric),
+    });
 
     if (rows.length === 0) {
         return <p className="mt-4 text-sm text-gray-500">{emptyLabel}</p>;
@@ -262,14 +276,53 @@ function UsageClientSimpleCountTable(props: UsageClientSimpleCountTableProps) {
             <table className="w-full text-left text-sm">
                 <thead className="sticky top-0 bg-gray-50 text-xs uppercase tracking-wide text-gray-500">
                     <tr>
-                        <th className="px-3 py-2">Name</th>
-                        <th className="px-3 py-2 text-right">Calls</th>
-                        <th className="px-3 py-2 text-right">Tokens</th>
-                        <th className="px-3 py-2 text-right">{UsageClientFormatting.usageMetricLabel(metric)}</th>
+                        <AdminSortableTableHeaderCell
+                            className="px-3 py-2"
+                            label="name"
+                            sortBy="label"
+                            activeSortBy={sortedTable.sortBy}
+                            sortOrder={sortedTable.sortOrder}
+                            onSortChange={sortedTable.handleSortChange}
+                        >
+                            Name
+                        </AdminSortableTableHeaderCell>
+                        <AdminSortableTableHeaderCell
+                            className="px-3 py-2 text-right"
+                            label="calls"
+                            sortBy="calls"
+                            activeSortBy={sortedTable.sortBy}
+                            sortOrder={sortedTable.sortOrder}
+                            onSortChange={sortedTable.handleSortChange}
+                            textAlign="right"
+                        >
+                            Calls
+                        </AdminSortableTableHeaderCell>
+                        <AdminSortableTableHeaderCell
+                            className="px-3 py-2 text-right"
+                            label="tokens"
+                            sortBy="tokens"
+                            activeSortBy={sortedTable.sortBy}
+                            sortOrder={sortedTable.sortOrder}
+                            onSortChange={sortedTable.handleSortChange}
+                            textAlign="right"
+                        >
+                            Tokens
+                        </AdminSortableTableHeaderCell>
+                        <AdminSortableTableHeaderCell
+                            className="px-3 py-2 text-right"
+                            label={UsageClientFormatting.usageMetricLabel(metric)}
+                            sortBy="metric"
+                            activeSortBy={sortedTable.sortBy}
+                            sortOrder={sortedTable.sortOrder}
+                            onSortChange={sortedTable.handleSortChange}
+                            textAlign="right"
+                        >
+                            {UsageClientFormatting.usageMetricLabel(metric)}
+                        </AdminSortableTableHeaderCell>
                     </tr>
                 </thead>
                 <tbody>
-                    {rows.map((row) => (
+                    {sortedTable.sortedRows.map((row) => (
                         <tr key={row.label} className="border-t border-gray-100">
                             <td className="px-3 py-2 font-medium text-gray-700 truncate max-w-[200px]">{row.label}</td>
                             <td className="px-3 py-2 text-right text-gray-700 whitespace-nowrap">
@@ -292,6 +345,30 @@ function UsageClientSimpleCountTable(props: UsageClientSimpleCountTableProps) {
     );
 }
 
+/**
+ * Resolves the initial direction used when switching usage count sort fields.
+ */
+function resolveUsageClientSimpleCountTableDefaultSortOrder(
+    sortBy: UsageClientSimpleCountTableSortField,
+): AdminTableSortOrder {
+    return sortBy === 'label' ? 'asc' : 'desc';
+}
+
+/**
+ * Resolves a comparable value for one usage count table row.
+ */
+function resolveUsageClientSimpleCountTableSortValue(
+    row: UsageClientSimpleCountTableRow,
+    sortBy: UsageClientSimpleCountTableSortField,
+    metric: UsageMetricMode,
+) {
+    if (sortBy === 'metric') {
+        return UsageClientFormatting.resolveMetricValue(row, metric);
+    }
+
+    return row[sortBy];
+}
+
 /**
  * Props for `<UsageClientDetailsTable/>`.
  */
@@ -301,11 +378,23 @@ type UsageClientDetailsTableProps = {
     emptyLabel: string;
 };
 
+/**
+ * Sortable column for generic usage detail tables.
+ */
+type UsageClientDetailsTableSortField = `${number}`;
+
 /**
  * Generic details table with flexible columns.
  */
 function UsageClientDetailsTable(props: UsageClientDetailsTableProps) {
     const { headers, rows, emptyLabel } = props;
+    const sortedTable = useAdminTableSorting<ReactNode[], UsageClientDetailsTableSortField>({
+        rows,
+        defaultSortBy: '1',
+        defaultSortOrder: 'desc',
+        resolveDefaultSortOrder: resolveUsageClientDetailsTableDefaultSortOrder,
+        resolveSortValue: resolveUsageClientDetailsTableSortValue,
+    });
 
     if (rows.length === 0) {
         return <p className="mt-4 text-sm text-gray-500">{emptyLabel}</p>;
@@ -317,14 +406,23 @@ function UsageClientDetailsTable(props: UsageClientDetailsTableProps) {
                 <thead className="sticky top-0 bg-gray-50 text-xs uppercase tracking-wide text-gray-500">
                     <tr>
                         {headers.map((header, index) => (
-                            <th key={index} className={`px-3 py-2 ${index > 0 ? 'text-right' : ''}`}>
+                            <AdminSortableTableHeaderCell
+                                key={index}
+                                className={`px-3 py-2 ${index > 0 ? 'text-right' : ''}`}
+                                label={header}
+                                sortBy={String(index) as UsageClientDetailsTableSortField}
+                                activeSortBy={sortedTable.sortBy}
+                                sortOrder={sortedTable.sortOrder}
+                                onSortChange={sortedTable.handleSortChange}
+                                textAlign={index > 0 ? 'right' : 'left'}
+                            >
                                 {header}
-                            </th>
+                            </AdminSortableTableHeaderCell>
                         ))}
                     </tr>
                 </thead>
                 <tbody>
-                    {rows.map((row, rowIndex) => (
+                    {sortedTable.sortedRows.map((row, rowIndex) => (
                         <tr key={rowIndex} className="border-t border-gray-100">
                             {row.map((cell, cellIndex) => (
                                 <td
@@ -343,3 +441,20 @@ function UsageClientDetailsTable(props: UsageClientDetailsTableProps) {
         </div>
     );
 }
+
+/**
+ * Resolves the initial direction used when switching usage detail sort fields.
+ */
+function resolveUsageClientDetailsTableDefaultSortOrder(sortBy: UsageClientDetailsTableSortField): AdminTableSortOrder {
+    return sortBy === '0' ? 'asc' : 'desc';
+}
+
+/**
+ * Resolves a comparable value for one generic usage detail table row.
+ */
+function resolveUsageClientDetailsTableSortValue(row: ReactNode[], sortBy: UsageClientDetailsTableSortField) {
+    const columnIndex = Number.parseInt(sortBy, 10);
+    const cell = row[columnIndex];
+
+    return typeof cell === 'string' || typeof cell === 'number' ? cell : String(cell ?? '');
+}

package/apps/agents-server/src/app/admin/users/[userId]/UserActivityTable.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import Link from 'next/link';
+import { Card } from '../../../../components/Homepage/Card';
+import { useServerLanguage } from '../../../../components/ServerLanguage/ServerLanguageProvider';
+import { useUserActivity } from '../../../../components/UsersList/useUserActivity';
+import { formatServerLanguageHumanReadableDate } from '../../../../utils/localization/formatServerLanguageHumanReadableDate';
+import { resolveChatHistoryMessageRole, resolveChatHistoryMessageText } from '../../../../utils/chatHistoryMessage';
+
+/**
+ * Props for the user activity table.
+ *
+ * @private component of <UserDetailClient/>
+ */
+type UserActivityTableProps = {
+    readonly userId: number;
+    readonly username: string;
+};
+
+/**
+ * Builds the link from one activity row to the corresponding chat-history view.
+ *
+ * @private helper of <UserActivityTable/>
+ */
+function buildChatHistoryRowHref(userId: number, row: { agentName: string; chatId: string | null }): string {
+    const searchParams = new URLSearchParams({ userId: String(userId), agentName: row.agentName });
+
+    if (row.chatId) {
+        searchParams.set('chatId', row.chatId);
+        searchParams.set('view', 'chat');
+    }
+
+    return `/admin/chat-history?${searchParams.toString()}`;
+}
+
+/**
+ * Renders recent chat activity for one user and links it to the full admin views.
+ *
+ * @private component of <UserDetailClient/>
+ */
+export function UserActivityTable({ userId, username }: UserActivityTableProps) {
+    const { language, t } = useServerLanguage();
+    const { error, isLoading, items, total } = useUserActivity(userId);
+    const allChatHistoryHref = `/admin/chat-history?userId=${encodeURIComponent(String(userId))}`;
+    const taskManagerHref = `/admin/task-manager?search=${encodeURIComponent(username)}&view=all`;
+
+    return (
+        <Card className="hover:border-gray-200 hover:shadow-md">
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                <div>
+                    <h3 className="text-lg font-semibold text-gray-900">{t('users.activityTitle')}</h3>
+                    <p className="mt-1 text-sm text-gray-500">{t('users.activityDescription')}</p>
+                </div>
+                <div className="flex flex-wrap gap-3 text-sm">
+                    <Link href={allChatHistoryHref} className="font-medium text-blue-600 hover:text-blue-800">
+                        {t('users.viewChatHistory')}
+                    </Link>
+                    <Link href={taskManagerHref} className="font-medium text-blue-600 hover:text-blue-800">
+                        {t('users.viewTasks')}
+                    </Link>
+                </div>
+            </div>
+
+            <div className="mt-5 overflow-x-auto">
+                {error ? <div className="rounded-md bg-red-50 px-4 py-3 text-sm text-red-800">{error}</div> : null}
+                {isLoading ? (
+                    <div className="py-8 text-center text-sm text-gray-500">{t('users.activityLoading')}</div>
+                ) : items.length === 0 ? (
+                    <div className="rounded-md border border-dashed border-gray-300 px-4 py-8 text-center text-sm text-gray-500">
+                        {t('users.noActivity')}
+                    </div>
+                ) : (
+                    <table className="min-w-full divide-y divide-gray-200 text-sm">
+                        <thead className="bg-gray-50">
+                            <tr>
+                                <th className="px-3 py-2 text-left font-medium text-gray-500">
+                                    {t('users.activityTime')}
+                                </th>
+                                <th className="px-3 py-2 text-left font-medium text-gray-500">
+                                    {t('users.activityAgent')}
+                                </th>
+                                <th className="px-3 py-2 text-left font-medium text-gray-500">
+                                    {t('users.activityRole')}
+                                </th>
+                                <th className="px-3 py-2 text-left font-medium text-gray-500">
+                                    {t('users.activityMessage')}
+                                </th>
+                                <th className="px-3 py-2 text-right font-medium text-gray-500">
+                                    {t('users.activityAction')}
+                                </th>
+                            </tr>
+                        </thead>
+                        <tbody className="divide-y divide-gray-200 bg-white">
+                            {items.map((row) => (
+                                <tr key={row.id} className="align-top hover:bg-gray-50">
+                                    <td className="whitespace-nowrap px-3 py-3 text-gray-600">
+                                        {formatServerLanguageHumanReadableDate(row.createdAt, language, {
+                                            fallbackLabel: '-',
+                                        })}
+                                    </td>
+                                    <td className="whitespace-nowrap px-3 py-3 font-medium text-gray-800">
+                                        {row.agentName}
+                                    </td>
+                                    <td className="whitespace-nowrap px-3 py-3 text-gray-600">
+                                        {resolveChatHistoryMessageRole(row.message)}
+                                    </td>
+                                    <td className="max-w-md px-3 py-3 text-gray-700">
+                                        <div className="max-h-16 overflow-y-auto text-xs leading-snug">
+                                            {resolveChatHistoryMessageText(row.message) || '-'}
+                                        </div>
+                                    </td>
+                                    <td className="whitespace-nowrap px-3 py-3 text-right">
+                                        <Link
+                                            href={buildChatHistoryRowHref(userId, row)}
+                                            className="font-medium text-blue-600 hover:text-blue-800"
+                                        >
+                                            {t('users.openActivity')}
+                                        </Link>
+                                    </td>
+                                </tr>
+                            ))}
+                        </tbody>
+                    </table>
+                )}
+            </div>
+
+            {total > items.length ? (
+                <p className="mt-3 text-xs text-gray-500">
+                    {t('users.activityShowing', { count: items.length, total })}
+                </p>
+            ) : null}
+        </Card>
+    );
+}

package/apps/agents-server/src/app/admin/users/[userId]/UserDetailClient.tsx

@@ -8,6 +8,7 @@ import { Section } from '../../../../components/Homepage/Section';
 import { useServerLanguage } from '../../../../components/ServerLanguage/ServerLanguageProvider';
 import { useUsersAdmin } from '../../../../components/UsersList/useUsersAdmin';
 import { formatServerLanguageHumanReadableDate } from '../../../../utils/localization/formatServerLanguageHumanReadableDate';
+import { UserActivityTable } from './UserActivityTable';
 
 /**
  * Props for user detail client.
@@ -77,7 +78,7 @@ export function UserDetailClient({ userId }: UserDetailClientProps) {
                 ← {t('users.backToUsers')}
             </Link>
 
-            <Section title={t('users.profileTitle', { username: user.username })}>
+            <Section title={t('users.profileTitle', { username: user.username })} gridClassName="space-y-6">
                 <Card>
                     <div className="flex justify-between items-start">
                         <div>
@@ -139,13 +140,7 @@ export function UserDetailClient({ userId }: UserDetailClientProps) {
                     </p>
                 </Card>
 
-                <Card>
-                    <h3 className="text-lg font-semibold text-gray-900 mb-2">{t('users.activityTitle')}</h3>
-                    <p className="text-gray-600 text-sm">
-                        {t('users.activityDescription')}
-                        {/* TODO: [🧠] Implement user activity timeline once events are stored. */}
-                    </p>
-                </Card>
+                <UserActivityTable userId={user.id} username={user.username} />
             </Section>
         </div>
     );

package/apps/agents-server/src/app/agents/[agentName]/AgentChatWrapper.tsx

@@ -7,6 +7,7 @@ import { RemoteAgent } from '@promptbook-local/core';
 import { ClientVersionMismatchError } from '@promptbook-local/utils';
 import { useCallback, useEffect, useMemo, useState, type CSSProperties } from 'react';
 import { string_agent_url } from '../../../../../../src/types/typeAliases';
+import type { AgentProjectItemInfo } from '../../../components/AgentProjects/AgentProjectReferencesList';
 import { useAgentBackground } from '../../../components/AgentProfile/useAgentBackground';
 import { useChatEnterBehaviorPreferences } from '../../../components/ChatEnterBehavior/ChatEnterBehaviorPreferencesProvider';
 import { ChatErrorDialog } from '../../../components/ChatErrorDialog';
@@ -23,6 +24,7 @@ import { createAttachmentAwareCitationLabelResolver } from '../../../utils/chat/
 import { createDefaultChatEffects } from '../../../utils/chat/createDefaultChatEffects';
 import { executeQuickActionButton } from '../../../utils/chat/executeQuickActionButton';
 import {
+    DEFAULT_CHAT_FEEDBACK_MODE,
     isChatFeedbackEnabled,
     toChatComponentFeedbackMode,
     type ChatFeedbackMode,
@@ -31,6 +33,7 @@ import { reportClientVersionMismatch } from '../../../utils/clientVersionClient'
 import type { FriendlyErrorMessage } from '../../../utils/errorMessages';
 import { handleChatError } from '../../../utils/errorMessages';
 import { fetchGithubAppStatus, type GithubAppStatusResponse } from '../../../utils/githubAppClient';
+import { createAgentProjectMarkdownReferences } from '../../../utils/agentProjects/createAgentProjectMarkdownReferences';
 import { createDefaultSpeechRecognition } from '../../../utils/speech-to-text/createDefaultSpeechRecognition';
 import { chatFileUploadHandler } from '../../../utils/upload/createBookEditorUploadHandler';
 import {
@@ -71,6 +74,10 @@ type AgentChatWrapperProps = {
      */
     feedbackMode?: ChatFeedbackMode;
     chatFailMessage?: string;
+    /**
+     * Project references resolved from `[[project-name]]` markdown tokens.
+     */
+    projectReferences?: ReadonlyArray<AgentProjectItemInfo>;
     /**
      * Optional handler for "New chat" action emitted from chat action bar.
      *
@@ -104,8 +111,9 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
         onMessagesChange,
         onInputTextChange,
         areFileAttachmentsEnabled,
-        feedbackMode = 'stars',
+        feedbackMode = DEFAULT_CHAT_FEEDBACK_MODE,
         chatFailMessage,
+        projectReferences = [],
         onStartNewChat,
         onAutoExecuteMessageConsumed,
     } = props;
@@ -136,6 +144,14 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
 
     const { value: agent } = usePromise(agentPromise, [agentPromise]);
     const teamAgentProfiles = useTeamAgentProfiles(agent?.capabilities);
+    const markdownInlineReferences = useMemo(
+        () =>
+            createAgentProjectMarkdownReferences({
+                agentPermanentId: agentName,
+                projects: projectReferences,
+            }),
+        [agentName, projectReferences],
+    );
 
     // Error state management
     const [currentError, setCurrentError] = useState<FriendlyErrorMessage | null>(null);
@@ -473,6 +489,7 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
             onReset={onStartNewChat}
             resetMode={onStartNewChat ? 'delegate' : undefined}
             teamAgentProfiles={teamAgentProfiles}
+            markdownInlineReferences={markdownInlineReferences}
             resolveCitationLabel={resolveCitationLabel}
         >
             {allowFileAttachments && !fileUploadAvailability.isUploadAvailable && (

package/apps/agents-server/src/app/agents/[agentName]/AgentProfileChat.tsx

@@ -20,11 +20,13 @@ import { FileUploadUnavailableNotice } from '../../../components/FileUploadAvail
 import { useFileUploadAvailability } from '../../../components/FileUploadAvailability/FileUploadAvailabilityContext';
 import { createMyChatsMobileMenuItem } from '../../../components/Header/createMyChatsMobileMenuItem';
 import { useHoistedMobileMenuItems } from '../../../components/Header/MobileMenuHoistingContext';
+import type { AgentProjectItemInfo } from '../../../components/AgentProjects/AgentProjectReferencesList';
 import { usePrivateModePreferences } from '../../../components/PrivateModePreferences/PrivateModePreferencesProvider';
 import { useServerLanguage } from '../../../components/ServerLanguage/ServerLanguageProvider';
 import { ChatThreadLoadingSkeleton } from '../../../components/Skeleton/ChatThreadLoadingSkeleton';
 import { usePromptbookTheme } from '../../../components/ThemeMode/usePromptbookTheme';
 import type { ServerLanguageCode } from '../../../languages/ServerLanguageRegistry';
+import { createAgentProjectMarkdownReferences } from '../../../utils/agentProjects/createAgentProjectMarkdownReferences';
 import { buildFreshAgentChatHref } from '../../../utils/agentRouting/agentRouteHrefs';
 import { executeQuickActionButton } from '../../../utils/chat/executeQuickActionButton';
 import { resolveChatMessageValidationIssue } from '../../../utils/chat/validateChatMessageContent';
@@ -58,6 +60,10 @@ export type AgentProfileChatProps = {
     speechRecognitionLanguage?: string;
     isHistoryEnabled?: boolean;
     areFileAttachmentsEnabled?: boolean;
+    /**
+     * Project references resolved from `[[project-name]]` markdown tokens.
+     */
+    projectReferences?: ReadonlyArray<AgentProjectItemInfo>;
 };
 
 /**
@@ -263,6 +269,7 @@ export function AgentProfileChat({
     speechRecognitionLanguage,
     isHistoryEnabled = false,
     areFileAttachmentsEnabled = true,
+    projectReferences = [],
 }: AgentProfileChatProps) {
     const [isCreatingAgent, setIsCreatingAgent] = useState(false);
     const [optimisticNavigationState, setOptimisticNavigationState] = useState<OptimisticChatNavigationState | null>(null);
@@ -277,6 +284,14 @@ export function AgentProfileChat({
     keepUnused(isCreatingAgent);
 
     const chatRoute = useMemo(() => `/agents/${encodeURIComponent(agentName)}/chat`, [agentName]);
+    const markdownInlineReferences = useMemo(
+        () =>
+            createAgentProjectMarkdownReferences({
+                agentPermanentId: agentName,
+                projects: projectReferences,
+            }),
+        [agentName, projectReferences],
+    );
     const agentPromise = useMemo(
         () =>
             RemoteAgent.connect({
@@ -491,10 +506,12 @@ export function AgentProfileChat({
                         ) : (
                             <Chat
                                 title={`Chat with ${fullname}`}
+                                agentIdentifier={agentName}
                                 participants={chatParticipants}
                                 chatLocale={language}
                                 timingTranslations={timingTranslations}
                                 feedbackTranslations={feedbackTranslations}
+                                markdownInlineReferences={markdownInlineReferences}
                                 messages={initialMessages}
                                 onMessage={handleMessage}
                                 onActionButton={executeQuickActionButton}

package/apps/agents-server/src/app/agents/[agentName]/AgentProfileWrapper.tsx

@@ -67,6 +67,11 @@ type AgentProfileWrapperProps = {
      */
     readonly folderContext?: AgentFolderContext | null;
 
+    /**
+     * Whether the projects view link should be shown in the agent menu.
+     */
+    readonly isProjectsViewVisible?: boolean;
+
     /***
      * Actions to be rendered within the agent profile
      */
@@ -92,6 +97,7 @@ export function AgentProfileWrapper(props: AgentProfileWrapperProps) {
         isAuthenticated,
         isHeadless,
         folderContext,
+        isProjectsViewVisible = false,
         actions,
         children,
     } = props;
@@ -141,6 +147,7 @@ export function AgentProfileWrapper(props: AgentProfileWrapperProps) {
                     agentUrl={agentUrl}
                     agentEmail={agentEmail}
                     folderContext={folderContext}
+                    isProjectsViewVisible={isProjectsViewVisible}
                     isAdmin={isAdmin}
                     isAuthenticated={isAuthenticated}
                     onShowQrCode={onShowQrCode}

package/apps/agents-server/src/app/agents/[agentName]/api/book/download/route.ts

@@ -0,0 +1,71 @@
+import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
+import {
+    createAgentBookDownloadContentDisposition,
+    createAgentBookDownloadFilename,
+} from '@/src/utils/agentBook/createAgentBookDownloadFilename';
+import { getCurrentUser } from '@/src/utils/getCurrentUser';
+import { DatabaseError, NotFoundError, UnexpectedError } from '@promptbook-local/core';
+import { NextResponse } from 'next/server';
+
+/**
+ * This route is always dynamic because it depends on live DB state and auth.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Agent collection access requires the Node.js runtime.
+ */
+export const runtime = 'nodejs';
+
+/**
+ * Streams the stored source book for one authenticated local agent.
+ *
+ * @param _request - Incoming request.
+ * @param context - Dynamic route params with the target agent name or permanent id.
+ * @returns Downloadable `.book` response or JSON error payload.
+ */
+export async function GET(_request: Request, context: { params: Promise<{ agentName: string }> }) {
+    if (!(await getCurrentUser())) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+    }
+
+    try {
+        const agentIdentifier = decodeURIComponent((await context.params).agentName);
+        const collection = await $provideAgentCollectionForServer();
+        const [agentSource, agentProfile] = await Promise.all([
+            collection.getAgentSource(agentIdentifier),
+            collection.findAgentBasicInformation(agentIdentifier),
+        ]);
+        const filename = createAgentBookDownloadFilename(agentProfile?.agentName || agentIdentifier);
+
+        return new NextResponse(agentSource, {
+            headers: {
+                'Content-Type': 'text/plain; charset=utf-8',
+                'Content-Disposition': createAgentBookDownloadContentDisposition(filename),
+                'Cache-Control': 'no-store',
+            },
+        });
+    } catch (error) {
+        return createAgentBookDownloadErrorResponse(error);
+    }
+}
+
+/**
+ * Maps branded book download errors into HTTP JSON responses.
+ *
+ * @param error - Unknown thrown error.
+ * @returns JSON error response.
+ */
+function createAgentBookDownloadErrorResponse(error: unknown): NextResponse {
+    if (error instanceof NotFoundError) {
+        return NextResponse.json({ error: error.message }, { status: 404 });
+    }
+
+    if (error instanceof DatabaseError || error instanceof UnexpectedError) {
+        console.error('Agent book download error:', error);
+        return NextResponse.json({ error: 'Failed to download agent book.' }, { status: 500 });
+    }
+
+    console.error('Agent book download error:', error);
+    return NextResponse.json({ error: 'Failed to download agent book.' }, { status: 500 });
+}

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

@@ -10,7 +10,7 @@ import {
     createUserChatDetailPayload,
     getUserChat,
     getUserChatJobByClientMessageId,
-    isFrozenUserChatSource,
+    isUserChatViewOnly,
     resolveUserChatReplyReference,
     triggerUserChatJobWorker,
 } from '@/src/utils/userChat';
@@ -78,6 +78,7 @@ export async function POST(
         const existingChat = await getUserChat({
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -86,7 +87,7 @@ export async function POST(
             return NextResponse.json({ error: 'Chat not found.' }, { status: 404 });
         }
 
-        if (isFrozenUserChatSource(existingChat.source)) {
+        if (isUserChatViewOnly({ chat: existingChat, viewerUserId: scopeResult.scope.userId })) {
             return NextResponse.json({ error: 'Frozen chats are view-only in the web UI.' }, { status: 403 });
         }
 
@@ -106,7 +107,7 @@ export async function POST(
 
         if (existingJob) {
             return NextResponse.json({
-                ...(await createUserChatDetailPayload(existingChat)),
+                ...(await createUserChatDetailPayload(existingChat, { viewerUserId: scopeResult.scope.userId })),
                 job: existingJob,
             });
         }
@@ -144,6 +145,7 @@ export async function POST(
             attachments,
             replyingTo,
             parameters,
+            chatHistoryTelemetryRequest: request,
         }).catch(async (error) => {
             if (isDuplicateUserChatJobError(error)) {
                 const duplicateJob = await getUserChatJobByClientMessageId({
@@ -178,7 +180,9 @@ export async function POST(
 
         return NextResponse.json(
             {
-                ...(await createUserChatDetailPayload(enqueuedTurn.chat)),
+                ...(await createUserChatDetailPayload(enqueuedTurn.chat, {
+                    viewerUserId: scopeResult.scope.userId,
+                })),
                 job: enqueuedTurn.job,
             },
             { status: 202 },