@promptbook/cli 0.113.0-8 → 0.114.0-0

package/apps/agents-server/src/utils/taskTerminal/taskTerminalLog.ts

@@ -0,0 +1,360 @@
+import { EventEmitter } from 'events';
+
+/**
+ * Maximum buffered terminal output kept in memory for one task.
+ */
+const MAX_TASK_TERMINAL_OUTPUT_LENGTH = 200_000;
+
+/**
+ * How long a finished task terminal stays readable for post-mortem inspection.
+ */
+const TASK_TERMINAL_RETENTION_MILLISECONDS = 30 * 60 * 1000;
+
+/**
+ * Maximum number of task terminals tracked at once before the oldest ones are evicted.
+ */
+const MAX_TRACKED_TASK_TERMINAL_COUNT = 200;
+
+/**
+ * ANSI dim style used for terminal line timestamps.
+ */
+const ANSI_STYLE_DIM = '\x1b[2m';
+
+/**
+ * ANSI style reset used after styled terminal fragments.
+ */
+const ANSI_STYLE_RESET = '\x1b[0m';
+
+/**
+ * Serializable snapshot of one task-scoped terminal log.
+ *
+ * The shape intentionally matches the shared `AdminTerminalSession` browser contract
+ * so the existing admin terminal SSE helper and xterm renderer can be reused.
+ */
+export type TaskTerminalLogSnapshot = {
+    /**
+     * Task identifier the terminal output belongs to.
+     */
+    readonly id: string;
+
+    /**
+     * Whether the task is still expected to produce more output.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * Buffered task terminal output.
+     */
+    readonly output: string;
+
+    /**
+     * ISO timestamp of the first captured output.
+     */
+    readonly startedAt: string;
+
+    /**
+     * ISO timestamp when the task terminal was marked finished, when available.
+     */
+    readonly finishedAt: string | null;
+
+    /**
+     * Synthetic exit code once the task finished (`0` on success, `1` otherwise).
+     */
+    readonly exitCode: number | null;
+
+    /**
+     * Always `null` — task terminals are not backed by one dedicated OS process.
+     */
+    readonly signal: null;
+};
+
+/**
+ * Output event emitted while one task terminal is collecting output.
+ */
+export type TaskTerminalLogOutputEvent = {
+    readonly type: 'output';
+    readonly chunk: string;
+};
+
+/**
+ * Exit event emitted when one task terminal is marked finished.
+ */
+export type TaskTerminalLogExitEvent = {
+    readonly type: 'exit';
+    readonly snapshot: TaskTerminalLogSnapshot;
+};
+
+/**
+ * Browser stream callbacks used by one subscribed task terminal client.
+ */
+export type TaskTerminalLogSubscriber = {
+    /**
+     * Called whenever new task terminal output arrives.
+     */
+    readonly onOutput: (event: TaskTerminalLogOutputEvent) => void;
+
+    /**
+     * Called once the task terminal is marked finished.
+     */
+    readonly onExit: (event: TaskTerminalLogExitEvent) => void;
+};
+
+/**
+ * Internal mutable per-task terminal state stored in-process.
+ */
+type TaskTerminalLogEntry = {
+    readonly taskId: string;
+    readonly events: EventEmitter<{
+        output: [TaskTerminalLogOutputEvent];
+        exit: [TaskTerminalLogExitEvent];
+    }>;
+    readonly startedAt: Date;
+    cleanupTimeout: NodeJS.Timeout | null;
+    output: string;
+    isFinished: boolean;
+    finishedAt: Date | null;
+    exitCode: number | null;
+    updatedAtMs: number;
+};
+
+/**
+ * Shared in-memory task terminal state reused across requests in the server process.
+ */
+type TaskTerminalLogState = {
+    readonly entriesByTaskId: Map<string, TaskTerminalLogEntry>;
+};
+
+/**
+ * Appends one output chunk to the terminal log of the given task.
+ *
+ * The task terminal log is created lazily on the first appended chunk. A previously
+ * finished terminal is reopened so retried tasks keep collecting output into the
+ * same buffer.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param chunk - Raw terminal text to append.
+ */
+export function appendTaskTerminalLogOutput(taskId: string, chunk: string): void {
+    if (!chunk) {
+        return;
+    }
+
+    const entry = ensureTaskTerminalLogEntry(taskId);
+
+    if (entry.isFinished) {
+        reopenTaskTerminalLogEntry(entry);
+    }
+
+    entry.output = (entry.output + chunk).slice(-MAX_TASK_TERMINAL_OUTPUT_LENGTH);
+    entry.updatedAtMs = Date.now();
+    entry.events.emit('output', {
+        type: 'output',
+        chunk,
+    });
+}
+
+/**
+ * Appends one timestamped line to the terminal log of the given task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param message - Line content, optionally containing ANSI styling.
+ */
+export function appendTaskTerminalLogLine(taskId: string, message: string): void {
+    appendTaskTerminalLogOutput(
+        taskId,
+        `${ANSI_STYLE_DIM}${new Date().toISOString()}${ANSI_STYLE_RESET} ${message}\n`,
+    );
+}
+
+/**
+ * Marks one task terminal as finished and notifies live subscribers.
+ *
+ * Does nothing when no output was ever captured for the task in this process.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param options - Finish metadata.
+ */
+export function markTaskTerminalLogFinished(taskId: string, options: { readonly isSuccessful: boolean }): void {
+    const entry = getTaskTerminalLogState().entriesByTaskId.get(taskId);
+    if (!entry || entry.isFinished) {
+        return;
+    }
+
+    entry.isFinished = true;
+    entry.finishedAt = new Date();
+    entry.exitCode = options.isSuccessful ? 0 : 1;
+    entry.updatedAtMs = Date.now();
+
+    entry.events.emit('exit', {
+        type: 'exit',
+        snapshot: createTaskTerminalLogSnapshot(entry),
+    });
+
+    scheduleTaskTerminalLogCleanup(entry);
+}
+
+/**
+ * Reads the buffered terminal log snapshot for one task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @returns Snapshot or `null` when nothing was captured for the task in this process.
+ */
+export function getTaskTerminalLogSnapshot(taskId: string): TaskTerminalLogSnapshot | null {
+    const entry = getTaskTerminalLogState().entriesByTaskId.get(taskId);
+    return entry ? createTaskTerminalLogSnapshot(entry) : null;
+}
+
+/**
+ * Subscribes one browser connection to live task terminal events.
+ *
+ * The entry is created eagerly so subscribers attached before the first output
+ * chunk still receive everything the task produces later.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @param subscriber - Stream callbacks.
+ * @returns Cleanup callback.
+ */
+export function subscribeToTaskTerminalLog(taskId: string, subscriber: TaskTerminalLogSubscriber): () => void {
+    const entry = ensureTaskTerminalLogEntry(taskId);
+
+    entry.events.on('output', subscriber.onOutput);
+    entry.events.on('exit', subscriber.onExit);
+
+    return () => {
+        entry.events.off('output', subscriber.onOutput);
+        entry.events.off('exit', subscriber.onExit);
+    };
+}
+
+/**
+ * Returns the mutable singleton state for task terminal logs.
+ *
+ * @returns Shared in-memory task terminal state.
+ */
+function getTaskTerminalLogState(): TaskTerminalLogState {
+    const globalState = globalThis as typeof globalThis & {
+        __promptbookTaskTerminalLogState?: TaskTerminalLogState;
+    };
+
+    if (!globalState.__promptbookTaskTerminalLogState) {
+        globalState.__promptbookTaskTerminalLogState = {
+            entriesByTaskId: new Map(),
+        };
+    }
+
+    return globalState.__promptbookTaskTerminalLogState;
+}
+
+/**
+ * Reads or creates the mutable terminal entry for one task.
+ *
+ * @param taskId - Task identifier used by the admin task manager.
+ * @returns Mutable terminal entry.
+ */
+function ensureTaskTerminalLogEntry(taskId: string): TaskTerminalLogEntry {
+    const state = getTaskTerminalLogState();
+    const existingEntry = state.entriesByTaskId.get(taskId);
+    if (existingEntry) {
+        return existingEntry;
+    }
+
+    evictStaleTaskTerminalLogEntries(state);
+
+    const entry: TaskTerminalLogEntry = {
+        taskId,
+        events: new EventEmitter(),
+        startedAt: new Date(),
+        cleanupTimeout: null,
+        output: '',
+        isFinished: false,
+        finishedAt: null,
+        exitCode: null,
+        updatedAtMs: Date.now(),
+    };
+
+    state.entriesByTaskId.set(taskId, entry);
+    return entry;
+}
+
+/**
+ * Reopens one finished terminal entry so a retried task keeps appending output.
+ *
+ * @param entry - Mutable terminal entry.
+ */
+function reopenTaskTerminalLogEntry(entry: TaskTerminalLogEntry): void {
+    entry.isFinished = false;
+    entry.finishedAt = null;
+    entry.exitCode = null;
+
+    if (entry.cleanupTimeout) {
+        clearTimeout(entry.cleanupTimeout);
+        entry.cleanupTimeout = null;
+    }
+}
+
+/**
+ * Schedules retention cleanup for one finished terminal entry.
+ *
+ * @param entry - Finished terminal entry.
+ */
+function scheduleTaskTerminalLogCleanup(entry: TaskTerminalLogEntry): void {
+    if (entry.cleanupTimeout) {
+        clearTimeout(entry.cleanupTimeout);
+    }
+
+    entry.cleanupTimeout = setTimeout(() => {
+        const state = getTaskTerminalLogState();
+        if (state.entriesByTaskId.get(entry.taskId) === entry) {
+            state.entriesByTaskId.delete(entry.taskId);
+        }
+    }, TASK_TERMINAL_RETENTION_MILLISECONDS);
+    entry.cleanupTimeout.unref?.();
+}
+
+/**
+ * Evicts the least recently updated entries when the registry grows past its cap.
+ *
+ * Finished entries are evicted first so terminals of still-running tasks survive bursts.
+ *
+ * @param state - Shared in-memory task terminal state.
+ */
+function evictStaleTaskTerminalLogEntries(state: TaskTerminalLogState): void {
+    if (state.entriesByTaskId.size < MAX_TRACKED_TASK_TERMINAL_COUNT) {
+        return;
+    }
+
+    const entriesOldestFirst = [...state.entriesByTaskId.values()].sort(
+        (leftEntry, rightEntry) =>
+            Number(rightEntry.isFinished) - Number(leftEntry.isFinished) ||
+            leftEntry.updatedAtMs - rightEntry.updatedAtMs,
+    );
+
+    for (const entry of entriesOldestFirst) {
+        if (state.entriesByTaskId.size < MAX_TRACKED_TASK_TERMINAL_COUNT) {
+            break;
+        }
+
+        if (entry.cleanupTimeout) {
+            clearTimeout(entry.cleanupTimeout);
+        }
+        state.entriesByTaskId.delete(entry.taskId);
+    }
+}
+
+/**
+ * Converts one mutable terminal entry into a browser-safe snapshot.
+ *
+ * @param entry - Mutable terminal entry.
+ * @returns Serializable terminal snapshot.
+ */
+function createTaskTerminalLogSnapshot(entry: TaskTerminalLogEntry): TaskTerminalLogSnapshot {
+    return {
+        id: entry.taskId,
+        isRunning: !entry.isFinished,
+        output: entry.output,
+        startedAt: entry.startedAt.toISOString(),
+        finishedAt: entry.finishedAt ? entry.finishedAt.toISOString() : null,
+        exitCode: entry.exitCode,
+        signal: null,
+    };
+}

package/apps/agents-server/src/utils/thinkingMessages.ts

@@ -1,4 +1,8 @@
 import { DEFAULT_THINKING_MESSAGES } from '../../../../src/utils/DEFAULT_THINKING_MESSAGES';
+import {
+    normalizeThinkingMessageVariants,
+    parseThinkingMessageVariants,
+} from '../../../../src/book-components/Chat/utils/thinkingMessageVariants';
 import { getMetadata } from '../database/getMetadata';
 import { parseSlashSeparatedMetadata } from './metadataVariants';
 
@@ -11,8 +15,22 @@ export { DEFAULT_THINKING_MESSAGES };
  * @returns Trimmed, non-empty variants or the shared defaults.
  */
 export function parseThinkingMessages(raw: string | null | undefined): ReadonlyArray<string> {
-    const variants = parseSlashSeparatedMetadata(raw);
-    return variants.length > 0 ? variants : DEFAULT_THINKING_MESSAGES;
+    return normalizeThinkingMessageVariants(parseSlashSeparatedMetadata(raw));
+}
+
+/**
+ * Resolves agent-specific thinking messages with server metadata as fallback.
+ *
+ * @param agentThinkingMessages - Variants parsed from `META THINKING MESSAGE` commitments.
+ * @param serverThinkingMessages - Server-level metadata variants.
+ * @returns Agent variants when present, otherwise server variants/defaults.
+ */
+export function resolveThinkingMessages(
+    agentThinkingMessages: ReadonlyArray<string> | null | undefined,
+    serverThinkingMessages: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+    const agentVariants = parseThinkingMessageVariants(agentThinkingMessages);
+    return agentVariants.length > 0 ? agentVariants : normalizeThinkingMessageVariants(serverThinkingMessages);
 }
 
 /**

package/apps/agents-server/src/utils/userChat/UserChatRecord.ts

@@ -42,6 +42,11 @@ export type UserChatSummary = {
     lastMessageAt: string | null;
     source: UserChatSource;
     isReadOnly: boolean;
+    /**
+     * True when the chat belongs to a different user than the current viewer
+     * (visible only to admins/super-admins browsing external chats).
+     */
+    isExternalUserChat: boolean;
     messagesCount: number;
     title: string;
     preview: string;
@@ -55,6 +60,11 @@ export type UserChatSummary = {
 export type ListUserChatsOptions = {
     userId: number;
     viewerIsAdmin: boolean;
+    /**
+     * True when the viewer is the environment-backed super-admin
+     * who may browse all users' chats on the server.
+     */
+    viewerIsSuperAdmin?: boolean;
     agentPermanentId: string;
     includeExternalChats?: boolean;
 };
@@ -65,6 +75,11 @@ export type ListUserChatsOptions = {
 export type GetUserChatOptions = {
     userId: number;
     viewerIsAdmin?: boolean;
+    /**
+     * True when the viewer is the environment-backed super-admin
+     * who may open other users' chats in a view-only mode.
+     */
+    viewerIsSuperAdmin?: boolean;
     agentPermanentId: string;
     chatId: string;
 };
@@ -77,6 +92,7 @@ export type CreateUserChatOptions = {
     agentPermanentId: string;
     source?: UserChatSource;
     chatId?: string;
+    title?: string | null;
     messages?: ReadonlyArray<ChatMessage>;
 };
 

package/apps/agents-server/src/utils/userChat/UserChatSource.ts

@@ -5,6 +5,7 @@ export const USER_CHAT_SOURCES = {
     WEB_UI: 'WEB_UI',
     OPENAI_API: 'OPENAI_API',
     TEAM_MEMBER: 'TEAM_MEMBER',
+    EMAIL: 'EMAIL',
 } as const;
 
 /**
@@ -31,6 +32,10 @@ export function getUserChatSourceChipLabel(source: UserChatSource): string | nul
         return 'TEAM';
     }
 
+    if (source === USER_CHAT_SOURCES.EMAIL) {
+        return 'EMAIL';
+    }
+
     return null;
 }
 
@@ -46,5 +51,9 @@ export function getUserChatSourceBannerLabel(source: UserChatSource): string | n
         return 'team member';
     }
 
+    if (source === USER_CHAT_SOURCES.EMAIL) {
+        return 'email';
+    }
+
     return null;
 }

package/apps/agents-server/src/utils/userChat/appendQueuedUserChatTurn.ts

@@ -1,8 +1,10 @@
 import type { ChatMessage } from '@promptbook-local/types';
+import type { ChatHistoryActorType, ChatHistorySource } from '../chat/createChatHistoryRecorder';
 import { $randomBase58 } from '../../../../../src/utils/random/$randomBase58';
 import { createUserChatJob } from './createUserChatJob';
 import { deleteUserChatJob } from './deleteUserChatJob';
 import { mutateUserChat } from './mutateUserChat';
+import { recordUserChatMessageInChatHistory } from './recordUserChatMessageInChatHistory';
 import type { UserChatJobRecord } from './UserChatJobRecord';
 import type { UserChatRecord } from './UserChatRecord';
 import { assertValidUserChatMessageReplies } from './userChatReplies';
@@ -30,6 +32,18 @@ export async function appendQueuedUserChatTurn(options: {
     attachments?: ChatMessage['attachments'];
     replyingTo?: ChatMessage['replyingTo'];
     parameters?: Record<string, unknown>;
+    /**
+     * Optional HTTP request used only for chat-history telemetry (ip, user-agent,...).
+     */
+    chatHistoryTelemetryRequest?: Request | null;
+    /**
+     * Source marker mirrored into the administrator chat-history audit.
+     */
+    chatHistorySource?: ChatHistorySource;
+    /**
+     * Actor marker mirrored into the administrator chat-history audit.
+     */
+    chatHistoryActorType?: ChatHistoryActorType;
 }): Promise<{
     chat: UserChatRecord;
     job: UserChatJobRecord;
@@ -85,6 +99,23 @@ export async function appendQueuedUserChatTurn(options: {
             },
         });
 
+        // Note: Recording is best-effort telemetry for `/admin/chat-history` and must never block the chat turn
+        void recordUserChatMessageInChatHistory({
+            agentPermanentId: options.agentPermanentId,
+            chatId: options.chatId,
+            taskId: jobId,
+            userId: options.userId,
+            message: {
+                role: 'USER',
+                sender: 'USER',
+                content: options.messageContent,
+                attachments: options.attachments,
+            },
+            request: options.chatHistoryTelemetryRequest,
+            source: options.chatHistorySource,
+            actorType: options.chatHistoryActorType,
+        });
+
         return { chat, job };
     } catch (error) {
         await deleteUserChatJob(jobId).catch((cleanupError) => {

package/apps/agents-server/src/utils/userChat/createUserChat.ts

@@ -50,7 +50,8 @@ export async function createUserChat(options: CreateUserChatOptions): Promise<Us
             createdAt: now,
             updatedAt: now,
             lastMessageAt: resolveLastMessageAt(messages, now),
-            source,
+            title: options.title,
+            source: source as unknown as UserChatInsert['source'],
             messages: messages as unknown as Json,
         };
 

package/apps/agents-server/src/utils/userChat/createUserChatDetailPayload.ts

@@ -8,10 +8,23 @@ import { getUserChat } from './getUserChat';
 import { listUserChatJobs } from './listUserChatJobs';
 import { reconcileUserChatActiveJobs } from './reconcileUserChatActiveJobs';
 
+/**
+ * Optional viewer context injected while building one chat detail payload.
+ */
+type CreateUserChatDetailPayloadOptions = {
+    /**
+     * Database user id of the current viewer, used to mark other users' chats as view-only.
+     */
+    viewerUserId?: number;
+};
+
 /**
  * Builds the API payload used for one canonical scoped chat detail.
  */
-export async function createUserChatDetailPayload(chat: UserChatRecord): Promise<{
+export async function createUserChatDetailPayload(
+    chat: UserChatRecord,
+    options: CreateUserChatDetailPayloadOptions = {},
+): Promise<{
     chat: ReturnType<typeof createUserChatSummary>;
     messages: UserChatRecord['messages'];
     draftMessage: string | null;
@@ -89,6 +102,7 @@ export async function createUserChatDetailPayload(chat: UserChatRecord): Promise
         chat: createUserChatSummary(currentChat, {
             timeoutActivity: createUserChatTimeoutActivity(activeTimeouts),
             activeJobCount: activeJobs.length,
+            viewerUserId: options.viewerUserId,
         }),
         messages: currentChat.messages,
         draftMessage: currentChat.draftMessage,

package/apps/agents-server/src/utils/userChat/createUserChatSummary.ts

@@ -50,6 +50,10 @@ const SUMMARY_RUNNING_ACTIVITY_MAX_AGE_MS = 6 * 60 * 1_000;
 type CreateUserChatSummaryOptions = {
     timeoutActivity?: UserChatTimeoutActivity;
     activeJobCount?: number;
+    /**
+     * Database user id of the current viewer, used to mark other users' chats as view-only.
+     */
+    viewerUserId?: number;
 };
 
 /**
@@ -64,6 +68,10 @@ export type UserChatSummarySeed = {
     lastMessageAt: string | null;
     title: string | null;
     source: UserChatRecord['source'];
+    /**
+     * Database user id owning the chat, used to mark other users' chats as view-only.
+     */
+    userId?: number;
     messagesCount: number;
     firstUserMessageContent: string;
     lastPreviewMessageContent: string;
@@ -89,6 +97,7 @@ export function createUserChatSummary(
             lastMessageAt: chat.lastMessageAt,
             title: chat.title,
             source: chat.source,
+            userId: chat.userId,
             messagesCount: chat.messages.length,
             firstUserMessageContent: firstUserMessage?.content || '',
             lastPreviewMessageContent: lastMessage?.content || '',
@@ -113,6 +122,8 @@ export function createUserChatSummaryFromSeed(
         options.activeJobCount && options.activeJobCount > 0
             ? options.activeJobCount
             : resolveSummaryPendingActivityCount(chat.updatedAt, chat.pendingAssistantMessageCount);
+    const isExternalUserChat =
+        options.viewerUserId !== undefined && chat.userId !== undefined && chat.userId !== options.viewerUserId;
 
     return {
         id: chat.id,
@@ -120,7 +131,8 @@ export function createUserChatSummaryFromSeed(
         updatedAt: chat.updatedAt,
         lastMessageAt: chat.lastMessageAt,
         source: chat.source,
-        isReadOnly: isFrozenUserChatSource(chat.source),
+        isReadOnly: isFrozenUserChatSource(chat.source) || isExternalUserChat,
+        isExternalUserChat,
         messagesCount: chat.messagesCount,
         title: shortenText(storedTitle || titleSource || DEFAULT_CHAT_TITLE, CHAT_TITLE_MAX_LENGTH),
         preview: shortenText(previewSource, CHAT_PREVIEW_MAX_LENGTH),

package/apps/agents-server/src/utils/userChat/expiredRunningUserChatJobDiagnostics.ts

@@ -39,6 +39,8 @@ export async function loadExpiredRunningUserChatJobRuntimeSnapshot(): Promise<Ex
             pageSize: EXPIRED_USER_CHAT_JOB_DIAGNOSTIC_TASK_LIMIT,
             view: 'active',
             search: '',
+            sortBy: 'default',
+            sortOrder: 'desc',
             timeWindowHours: EXPIRED_USER_CHAT_JOB_DIAGNOSTIC_TIME_WINDOW_HOURS,
         }),
     ]);

package/apps/agents-server/src/utils/userChat/finalizeUserChatJob.ts

@@ -1,6 +1,7 @@
 import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
+import { markTaskTerminalLogFinished } from '../taskTerminal/taskTerminalLog';
 import type { UserChatJobRow } from './UserChatJobRow';
 import type { UserChatJobRecord, UserChatJobStatus } from './UserChatJobRecord';
 import { mapUserChatJobRow } from './mapUserChatJobRow';
@@ -20,6 +21,21 @@ export async function finalizeUserChatJob(options: {
     provider?: string | null;
     failureReason?: string | null;
     failureDetails?: string | null;
+}): Promise<UserChatJobRecord | null> {
+    const finalizedJob = await persistFinalUserChatJobStatus(options);
+    markTaskTerminalLogFinished(options.jobId, { isSuccessful: options.status === 'COMPLETED' });
+    return finalizedJob;
+}
+
+/**
+ * Persists one final job status through the mode-specific database path.
+ */
+async function persistFinalUserChatJobStatus(options: {
+    jobId: string;
+    status: FinalUserChatJobStatus;
+    provider?: string | null;
+    failureReason?: string | null;
+    failureDetails?: string | null;
 }): Promise<UserChatJobRecord | null> {
     if (isAgentsServerSqliteMode()) {
         return finalizeUserChatJobViaSupabaseQuery(options);

package/apps/agents-server/src/utils/userChat/getUserChat.ts

@@ -8,7 +8,7 @@ import { USER_CHAT_SOURCES } from './UserChatSource';
  * Loads one user chat by id.
  */
 export async function getUserChat(options: GetUserChatOptions): Promise<UserChatRecord | null> {
-    const { userId, viewerIsAdmin = false, agentPermanentId, chatId } = options;
+    const { userId, viewerIsAdmin = false, viewerIsSuperAdmin = false, agentPermanentId, chatId } = options;
     const userChatTable = await provideUserChatTable();
 
     const { data, error } = await userChatTable
@@ -28,8 +28,13 @@ export async function getUserChat(options: GetUserChatOptions): Promise<UserChat
     const chat = mapUserChatRow(data as UserChatRow);
 
     if (chat.source === USER_CHAT_SOURCES.WEB_UI) {
-        return chat.userId === userId ? chat : null;
+        if (chat.userId === userId) {
+            return chat;
+        }
+
+        // Note: Super-admins may open other users' chats in a view-only mode
+        return viewerIsSuperAdmin ? chat : null;
     }
 
-    return viewerIsAdmin ? chat : null;
+    return viewerIsAdmin || viewerIsSuperAdmin ? chat : null;
 }

package/apps/agents-server/src/utils/userChat/isUserChatViewOnly.ts

@@ -0,0 +1,16 @@
+import type { UserChatRecord } from './UserChatRecord';
+import { isFrozenUserChatSource } from './UserChatSource';
+
+/**
+ * Returns true when the chat must stay view-only for the given viewer.
+ *
+ * A chat is view-only when it was captured from an external channel (frozen source)
+ * or when it belongs to a different user (super-admins browsing all users' chats).
+ */
+export function isUserChatViewOnly(options: {
+    chat: Pick<UserChatRecord, 'source' | 'userId'>;
+    viewerUserId: number;
+}): boolean {
+    const { chat, viewerUserId } = options;
+    return isFrozenUserChatSource(chat.source) || chat.userId !== viewerUserId;
+}