@promptbook/cli 0.113.0-8 → 0.114.0-0

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';
@@ -19,10 +20,11 @@ import { useServerLanguage } from '../../../components/ServerLanguage/ServerLang
 import { ChatThreadLoadingSkeleton } from '../../../components/Skeleton/ChatThreadLoadingSkeleton';
 import { useSoundSystem } from '../../../components/SoundSystemProvider/SoundSystemProvider';
 import { fetchCalendarOAuthStatus, type CalendarOAuthStatusResponse } from '../../../utils/calendarOAuthClient';
+import { createAttachmentAwareCitationLabelResolver } from '../../../utils/chat/createAttachmentAwareCitationLabelResolver';
 import { createDefaultChatEffects } from '../../../utils/chat/createDefaultChatEffects';
 import { executeQuickActionButton } from '../../../utils/chat/executeQuickActionButton';
-import { resolveAgentsServerCitationLabel } from '../../../utils/chat/resolveAgentsServerCitationLabel';
 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);
@@ -144,6 +160,7 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
     const sendMessage = useSendMessageToLlmChat();
     const [githubAppStatus, setGithubAppStatus] = useState<GithubAppStatusResponse | null>(null);
     const [calendarOAuthStatus, setCalendarOAuthStatus] = useState<CalendarOAuthStatusResponse | null>(null);
+    const [renderedMessages, setRenderedMessages] = useState<ReadonlyArray<ChatMessage>>([]);
     const currentAgentPermanentId = useMemo(() => {
         return typeof (agent as { permanentId?: unknown } | undefined)?.permanentId === 'string'
             ? ((agent as { permanentId?: string }).permanentId as string)
@@ -283,6 +300,19 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
         t,
     });
 
+    // Track rendered messages so cited chat attachments resolve to their original filenames.
+    const handleChatMessagesChange = useCallback(
+        (messages: ReadonlyArray<ChatMessage>) => {
+            setRenderedMessages(messages);
+            handleMessagesChange(messages);
+        },
+        [handleMessagesChange],
+    );
+    const resolveCitationLabel = useMemo(
+        () => createAttachmentAwareCitationLabelResolver(renderedMessages),
+        [renderedMessages],
+    );
+
     // Handle errors from chat
     const handleError = useCallback((error: unknown, retry: () => void) => {
         if (error instanceof ClientVersionMismatchError) {
@@ -439,7 +469,7 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
             autoExecuteMessage={effectiveAutoExecuteMessage}
             autoExecuteMessageAttachments={effectiveAutoExecuteMessageAttachments}
             persistenceKey={persistenceKey}
-            onChange={handleMessagesChange}
+            onChange={handleChatMessagesChange}
             onInputTextChange={onInputTextChange}
             onActionButton={executeQuickActionButton}
             sendMessage={sendMessage}
@@ -459,7 +489,8 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
             onReset={onStartNewChat}
             resetMode={onStartNewChat ? 'delegate' : undefined}
             teamAgentProfiles={teamAgentProfiles}
-            resolveCitationLabel={resolveAgentsServerCitationLabel}
+            markdownInlineReferences={markdownInlineReferences}
+            resolveCitationLabel={resolveCitationLabel}
         >
             {allowFileAttachments && !fileUploadAvailability.isUploadAvailable && (
                 <FileUploadUnavailableNotice className="mx-4 mt-4" />

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 },

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

@@ -3,7 +3,7 @@ import {
     createUserChatDetailPayload,
     deleteUserChat,
     getUserChat,
-    isFrozenUserChatSource,
+    isUserChatViewOnly,
     updateUserChatMessages,
 } from '@/src/utils/userChat';
 import { UserChatReplyValidationError } from '@/src/utils/userChat/UserChatReplyValidationError';
@@ -40,6 +40,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         const chat = await getUserChat({
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -48,7 +49,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             return NextResponse.json({ error: 'Chat not found.' }, { status: 404 });
         }
 
-        return NextResponse.json(await createUserChatDetailPayload(chat));
+        return NextResponse.json(await createUserChatDetailPayload(chat, { viewerUserId: scopeResult.scope.userId }));
     } catch (error) {
         return NextResponse.json(
             { error: error instanceof Error ? error.message : 'Failed to load chat.' },
@@ -84,6 +85,7 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
         const existingChat = await getUserChat({
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -92,7 +94,7 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             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 });
         }
 
@@ -108,7 +110,9 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             messages: body.messages as Array<ChatMessage>,
         });
 
-        return NextResponse.json(await createUserChatDetailPayload(updatedChat));
+        return NextResponse.json(
+            await createUserChatDetailPayload(updatedChat, { viewerUserId: scopeResult.scope.userId }),
+        );
     } catch (error) {
         if (error instanceof UserChatScopeError) {
             return resolveUserChatUpdateScopeErrorResponse(error);
@@ -196,6 +200,7 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ a
         const existingChat = await getUserChat({
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -204,7 +209,7 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ a
             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 });
         }
 

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

@@ -1,6 +1,7 @@
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
 import { canAccessAgentVisibility, resolveAgentVisibility } from '@/src/utils/agentAccess';
 import { resolveCurrentUserIdentity } from '@/src/utils/currentUserIdentity';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
 import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
 
 /**
@@ -9,6 +10,11 @@ import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTim
 export type ResolvedUserChatScope = {
     userId: number;
     viewerIsAdmin: boolean;
+    /**
+     * True when the viewer is the environment-backed super-admin
+     * who may browse all users' chats in a view-only mode.
+     */
+    viewerIsSuperAdmin: boolean;
     agentPermanentId: string;
 };
 
@@ -32,7 +38,10 @@ export async function resolveUserChatScope(
 
     try {
         const collection = await $provideAgentCollectionForServer();
-        const agentPermanentId = await collection.getAgentPermanentId(agentIdentifier);
+        const [agentPermanentId, viewerIsSuperAdmin] = await Promise.all([
+            collection.getAgentPermanentId(agentIdentifier),
+            isUserGlobalAdmin(),
+        ]);
         const visibility = await resolveAgentVisibility(agentPermanentId);
         const isAllowed = canAccessAgentVisibility({
             visibility,
@@ -48,6 +57,7 @@ export async function resolveUserChatScope(
             scope: {
                 userId: currentUserIdentity.userId,
                 viewerIsAdmin: currentUserIdentity.isAdmin,
+                viewerIsSuperAdmin,
                 agentPermanentId,
             },
         };

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

@@ -41,11 +41,14 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         const chatSummarySeeds = await listUserChatSummarySeeds({
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             includeExternalChats: showExternalChats,
         });
         const activityUserId =
-            scopeResult.scope.viewerIsAdmin && showExternalChats ? undefined : scopeResult.scope.userId;
+            (scopeResult.scope.viewerIsAdmin || scopeResult.scope.viewerIsSuperAdmin) && showExternalChats
+                ? undefined
+                : scopeResult.scope.userId;
         const [timeoutActivities, jobActivityCounts] = await Promise.all([
             listUserChatTimeoutActivities({
                 userId: activityUserId,
@@ -67,15 +70,19 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             ? await getUserChat({
                   userId: scopeResult.scope.userId,
                   viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+                  viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
                   agentPermanentId: scopeResult.scope.agentPermanentId,
                   chatId: activeChatSummarySeed.id,
               })
             : null;
-        const activeChatDetail = activeChat ? await createUserChatDetailPayload(activeChat) : null;
+        const activeChatDetail = activeChat
+            ? await createUserChatDetailPayload(activeChat, { viewerUserId: scopeResult.scope.userId })
+            : null;
         const chatSummaries = chatSummarySeeds.map((chat) =>
             createUserChatSummaryFromSeed(chat, {
                 timeoutActivity: timeoutActivities[chat.id],
                 activeJobCount: jobActivityCounts[chat.id],
+                viewerUserId: scopeResult.scope.userId,
             }),
         );