@promptbook/cli 0.114.0-3 → 0.114.0-30

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

@@ -1,17 +1,17 @@
 import { spaceTrim } from 'spacetrim';
 
 /**
- * Wallet service id used by USE EMAIL for SMTP credentials.
+ * Wallet service id used by agent email for SMTP credentials.
  */
 export const USE_EMAIL_SMTP_WALLET_SERVICE = 'smtp';
 
 /**
- * Wallet key used by USE EMAIL for SMTP credentials.
+ * Wallet key used by agent email for SMTP credentials.
  */
 export const USE_EMAIL_SMTP_WALLET_KEY = 'use-email-smtp-credentials';
 
 /**
- * JSON schema expected in ACCESS_TOKEN secret for USE EMAIL SMTP credentials.
+ * JSON schema expected in ACCESS_TOKEN secret for agent email SMTP credentials.
  */
 export const USE_EMAIL_SMTP_WALLET_SECRET_JSON_SCHEMA = {
     type: 'object',
@@ -49,7 +49,7 @@ export const USE_EMAIL_SMTP_WALLET_SECRET_JSON_SCHEMA = {
 } as const;
 
 /**
- * Multiline JSON example for USE EMAIL SMTP secret payload.
+ * Multiline JSON example for agent email SMTP secret payload.
  */
 export const USE_EMAIL_SMTP_WALLET_SECRET_JSON_EXAMPLE = spaceTrim(`
     {
@@ -62,7 +62,7 @@ export const USE_EMAIL_SMTP_WALLET_SECRET_JSON_EXAMPLE = spaceTrim(`
 `);
 
 /**
- * Builds user-facing guidance for missing USE EMAIL SMTP wallet credentials.
+ * Builds user-facing guidance for missing agent email SMTP wallet credentials.
  */
 export function createUseEmailSmtpWalletMissingCredentialMessage(defaultFromAddress?: string): string {
     const defaultSenderLine = defaultFromAddress ? `Default sender from commitment: ${defaultFromAddress}` : undefined;

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

@@ -41,12 +41,21 @@ export type UserChatSummary = {
     updatedAt: string;
     lastMessageAt: string | null;
     source: UserChatSource;
+    /**
+     * Database user id owning the chat, used to link a super-admin to its owner.
+     */
+    userId?: number;
     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;
+    /**
+     * True for the singleton goal chat the agent keeps with itself, which is pinned above
+     * every other chat and rendered with its own icon.
+     */
+    isAgentGoalChat: boolean;
     messagesCount: number;
     title: string;
     preview: string;
@@ -80,6 +89,10 @@ export type GetUserChatOptions = {
      * who may open other users' chats in a view-only mode.
      */
     viewerIsSuperAdmin?: boolean;
+    /**
+     * True when the viewer may read the agent source book and therefore also the agent goal chat.
+     */
+    viewerCanAccessAgentGoalChat?: boolean;
     agentPermanentId: string;
     chatId: string;
 };

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

@@ -6,6 +6,11 @@ export const USER_CHAT_SOURCES = {
     OPENAI_API: 'OPENAI_API',
     TEAM_MEMBER: 'TEAM_MEMBER',
     EMAIL: 'EMAIL',
+
+    /**
+     * Singleton chat every agent keeps with itself to plan work towards its goal.
+     */
+    AGENT_GOAL: 'AGENT_GOAL',
 } as const;
 
 /**
@@ -24,6 +29,10 @@ export function isFrozenUserChatSource(source: UserChatSource): boolean {
  * Resolves a compact chip label for one chat source.
  */
 export function getUserChatSourceChipLabel(source: UserChatSource): string | null {
+    if (source === USER_CHAT_SOURCES.AGENT_GOAL) {
+        return 'GOAL';
+    }
+
     if (source === USER_CHAT_SOURCES.OPENAI_API) {
         return 'API';
     }
@@ -43,6 +52,11 @@ export function getUserChatSourceChipLabel(source: UserChatSource): string | nul
  * Resolves the banner copy used for frozen external chats.
  */
 export function getUserChatSourceBannerLabel(source: UserChatSource): string | null {
+    if (source === USER_CHAT_SOURCES.AGENT_GOAL) {
+        // Note: Goal chats explain their own specialty through a dedicated notice instead of the generic frozen banner
+        return null;
+    }
+
     if (source === USER_CHAT_SOURCES.OPENAI_API) {
         return 'API key';
     }

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

@@ -29,6 +29,11 @@ export async function appendQueuedUserChatTurn(options: {
     chatId: string;
     clientMessageId: string;
     messageContent: string;
+    /**
+     * Sender persisted for the input message. Defaults to `USER`; autonomous goal-chat turns use
+     * `AGENT` so the transcript cannot imply that the goal-chat owner wrote the internal wake-up.
+     */
+    messageSender?: 'USER' | 'AGENT';
     attachments?: ChatMessage['attachments'];
     replyingTo?: ChatMessage['replyingTo'];
     parameters?: Record<string, unknown>;
@@ -75,6 +80,7 @@ export async function appendQueuedUserChatTurn(options: {
                         messageId: userMessageId,
                         clientMessageId: options.clientMessageId,
                         content: options.messageContent,
+                        ...(options.messageSender ? { sender: options.messageSender } : {}),
                         attachments: options.attachments,
                         replyingTo: options.replyingTo,
                         createdAt: nowIso,
@@ -100,14 +106,15 @@ export async function appendQueuedUserChatTurn(options: {
         });
 
         // Note: Recording is best-effort telemetry for `/admin/chat-history` and must never block the chat turn
+        const isAgentAuthoredInput = options.messageSender === 'AGENT';
         void recordUserChatMessageInChatHistory({
             agentPermanentId: options.agentPermanentId,
             chatId: options.chatId,
             taskId: jobId,
             userId: options.userId,
             message: {
-                role: 'USER',
-                sender: 'USER',
+                role: isAgentAuthoredInput ? 'MODEL' : 'USER',
+                sender: isAgentAuthoredInput ? 'MODEL' : 'USER',
                 content: options.messageContent,
                 attachments: options.attachments,
             },

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

@@ -19,6 +19,7 @@ const IMMEDIATE_USER_CHAT_ANSWER_INSTRUCTION_COMMITMENTS = new Set<string>([
     'STYLE',
     'STYLES',
     'WRITING RULES',
+    'WRITING RULE',
     'FORMAT',
     'FORMATS',
     'SCENARIO',

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

@@ -1,7 +1,6 @@
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
 import { $provideOpenAiAgentKitExecutionToolsForServer } from '@/src/tools/$provideOpenAiAgentKitExecutionToolsForServer';
-import { createAgentProgressTools } from '@/src/tools/createAgentProgressTools';
-import { createChatAttachmentTools } from '@/src/tools/createChatAttachmentTools';
+import { createServerChatRuntimeTools } from '@/src/tools/createServerChatRuntimeTools';
 import {
     AGENT_PREPARATION_CHAT_WAIT_TIMEOUT_MS,
     resolveAgentCollectionTablePrefix,
@@ -14,7 +13,6 @@ import {
     resolveCachedServerAgentModelRequirements,
 } from '@/src/utils/cachedServerAgentRuntime';
 import { extractUseCalendarConnectionsFromAgentSource } from '@/src/utils/calendars/extractUseCalendarConnectionsFromAgentSource';
-import { extractUseEmailConfigurationFromAgentSource } from '@/src/utils/emails/extractUseEmailConfigurationFromAgentSource';
 import { getTeacherRemoteAgent } from '@/src/utils/getTeacherRemoteAgent';
 import { composePromptParametersWithMemoryContext } from '@/src/utils/memoryRuntimeContext';
 import { extractProjectRepositoriesFromAgentSource } from '@/src/utils/projects/extractProjectRepositoriesFromAgentSource';
@@ -112,7 +110,6 @@ export async function createRunUserChatJobExecutionContext(options: {
     const resolvedAgentName = resolvedAgentContext.resolvedAgentName;
     const projectRepositories = extractProjectRepositoriesFromAgentSource(agentSource);
     const calendarConnections = extractUseCalendarConnectionsFromAgentSource(agentSource);
-    const useEmailConfiguration = extractUseEmailConfigurationFromAgentSource(agentSource);
     const agentToolDefinitions = preparedAgentModelRequirements.modelRequirements.tools ?? [];
     const agentKnowledgeSources = preparedAgentModelRequirements.modelRequirements.knowledgeSources ?? [];
 
@@ -124,7 +121,7 @@ export async function createRunUserChatJobExecutionContext(options: {
         toolCount: agentToolDefinitions.length,
         toolHighlights: resolveUserChatProgressToolHighlights(agentToolDefinitions),
         hasCalendarAccess: calendarConnections.length > 0,
-        hasEmailAccess: useEmailConfiguration.isEnabled,
+        hasEmailAccess: true,
         hasProjectAccess: projectRepositories.length > 0,
     };
 
@@ -135,11 +132,8 @@ export async function createRunUserChatJobExecutionContext(options: {
             userId: options.job.userId,
             agentPermanentId,
             calendarConnections,
-            isEmailEnabled: useEmailConfiguration.isEnabled,
         });
-    const runtimeTools = createAgentProgressTools(
-        createChatAttachmentTools([], options.userMessageAttachments || []),
-    );
+    const runtimeTools = createServerChatRuntimeTools(options.userMessageAttachments || []);
 
     /**
      * Full list of tools that were available to the model for this chat turn.
@@ -164,7 +158,6 @@ export async function createRunUserChatJobExecutionContext(options: {
         projectRepositories,
         projectGithubToken,
         emailSmtpCredential,
-        emailFromAddress: useEmailConfiguration.senderEmail,
         calendarGoogleAccessToken,
         calendarConnections,
         chatAttachments: options.userMessageAttachments,
@@ -255,7 +248,6 @@ async function resolveRunUserChatJobCredentials(options: {
     userId: number;
     agentPermanentId: string;
     calendarConnections: ReturnType<typeof extractUseCalendarConnectionsFromAgentSource>;
-    isEmailEnabled: boolean;
 }) {
     const [projectGithubToken, calendarGoogleAccessToken, emailSmtpCredential] = await Promise.all([
         resolveUseProjectGithubToken({
@@ -268,12 +260,10 @@ async function resolveRunUserChatJobCredentials(options: {
                   agentPermanentId: options.agentPermanentId,
               })
             : Promise.resolve(undefined),
-        options.isEmailEnabled
-            ? resolveUseEmailSmtpCredential({
-                  userId: options.userId,
-                  agentPermanentId: options.agentPermanentId,
-              })
-            : Promise.resolve(undefined),
+        resolveUseEmailSmtpCredential({
+            userId: options.userId,
+            agentPermanentId: options.agentPermanentId,
+        }),
     ]);
 
     return {

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

@@ -2,7 +2,7 @@ import type { UserChatRecord, UserChatSummary, UserChatTimeoutActivity } from '.
 import { createUserChatRunningActivity } from './createUserChatRunningActivity';
 import { shortenText } from '../shortenText';
 import { textToPreviewText } from '../textToPreviewText';
-import { isFrozenUserChatSource } from './UserChatSource';
+import { isFrozenUserChatSource, USER_CHAT_SOURCES } from './UserChatSource';
 
 /**
  * Max title length in chat list.
@@ -122,8 +122,14 @@ export function createUserChatSummaryFromSeed(
         options.activeJobCount && options.activeJobCount > 0
             ? options.activeJobCount
             : resolveSummaryPendingActivityCount(chat.updatedAt, chat.pendingAssistantMessageCount);
+    const isAgentGoalChat = chat.source === USER_CHAT_SOURCES.AGENT_GOAL;
+    // Note: Goal chats are owned by the agent rather than by any human, so they are never treated
+    //       as somebody else's chat even when the viewer is not their stored owner
     const isExternalUserChat =
-        options.viewerUserId !== undefined && chat.userId !== undefined && chat.userId !== options.viewerUserId;
+        !isAgentGoalChat &&
+        options.viewerUserId !== undefined &&
+        chat.userId !== undefined &&
+        chat.userId !== options.viewerUserId;
 
     return {
         id: chat.id,
@@ -131,8 +137,10 @@ export function createUserChatSummaryFromSeed(
         updatedAt: chat.updatedAt,
         lastMessageAt: chat.lastMessageAt,
         source: chat.source,
+        userId: chat.userId,
         isReadOnly: isFrozenUserChatSource(chat.source) || isExternalUserChat,
         isExternalUserChat,
+        isAgentGoalChat,
         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/finalizeUserChatJob.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
@@ -46,7 +47,7 @@ async function persistFinalUserChatJobStatus(options: {
         const sql = await $provideClientSql();
         const userChatJobTable = quoteIdentifier(await $getTableName('UserChatJob'));
         const rows = await sql.raw<Array<UserChatJobRecord>>(
-            `
+            spaceTrim(`
                 UPDATE ${userChatJobTable}
                 SET
                     "status" = $1,
@@ -79,7 +80,7 @@ async function persistFinalUserChatJobStatus(options: {
                     "attemptCount",
                     "provider",
                     "failureReason"
-            `,
+            `),
             [
                 options.status,
                 nowIso,

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

@@ -8,7 +8,14 @@ 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, viewerIsSuperAdmin = false, agentPermanentId, chatId } = options;
+    const {
+        userId,
+        viewerIsAdmin = false,
+        viewerIsSuperAdmin = false,
+        viewerCanAccessAgentGoalChat = false,
+        agentPermanentId,
+        chatId,
+    } = options;
     const userChatTable = await provideUserChatTable();
 
     const { data, error } = await userChatTable
@@ -36,5 +43,13 @@ export async function getUserChat(options: GetUserChatOptions): Promise<UserChat
         return viewerIsSuperAdmin ? chat : null;
     }
 
+    if (chat.source === USER_CHAT_SOURCES.AGENT_GOAL) {
+        // Note: Goal chats follow agent-source-book access, and stay readable for the background
+        //       workers that run under the goal chat's own owner identity
+        return viewerCanAccessAgentGoalChat || viewerIsAdmin || viewerIsSuperAdmin || chat.userId === userId
+            ? chat
+            : null;
+    }
+
     return viewerIsAdmin || viewerIsSuperAdmin ? chat : null;
 }

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

@@ -0,0 +1,31 @@
+import { getUserChat } from './getUserChat';
+import type { UserChatRecord } from './UserChatRecord';
+
+/**
+ * Job identity a background runner needs to load the chat it is about to answer.
+ */
+export type UserChatJobRunnerChatIdentity = {
+    readonly userId: number;
+    readonly agentPermanentId: string;
+    readonly chatId: string;
+};
+
+/**
+ * Loads the chat one durable job belongs to, on behalf of the background runner executing it.
+ *
+ * `getUserChat` answers a *viewer* and therefore discloses the externally created chat sources -
+ * `EMAIL`, `OPENAI_API` and `TEAM_MEMBER` - to administrators only. A background runner is not a
+ * viewer: it already owns the job, runs under the job owner's identity, and has to read every chat
+ * source. Without this distinction each externally created job is cancelled as if its chat had been
+ * deleted, so every inbound email stays unanswered.
+ */
+export async function getUserChatForJobRunner(job: UserChatJobRunnerChatIdentity): Promise<UserChatRecord | null> {
+    return await getUserChat({
+        userId: job.userId,
+        // Note: The runner is trusted machinery behind an already-persisted job, not a person browsing
+        //       somebody else's conversation
+        viewerIsAdmin: true,
+        agentPermanentId: job.agentPermanentId,
+        chatId: job.chatId,
+    });
+}

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

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
@@ -97,19 +98,19 @@ export async function listUserChatSummarySeeds(options: ListUserChatsOptions): P
         shouldLoadAllUsersChats || (options.viewerIsAdmin && options.includeExternalChats);
 
     const whereClause = shouldLoadAllUsersChats
-        ? `
+        ? spaceTrim(`
             "agentPermanentId" = $1
-        `
+        `)
         : shouldLoadExternalChats
-        ? `
+        ? spaceTrim(`
             "agentPermanentId" = $1
             AND ("source" <> '${USER_CHAT_SOURCES.WEB_UI}' OR "userId" = $2)
-        `
-        : `
+        `)
+        : spaceTrim(`
             "userId" = $1
             AND "agentPermanentId" = $2
             AND "source" = '${USER_CHAT_SOURCES.WEB_UI}'
-        `;
+        `);
     const queryValues = shouldLoadAllUsersChats
         ? [options.agentPermanentId]
         : shouldLoadExternalChats
@@ -117,53 +118,55 @@ export async function listUserChatSummarySeeds(options: ListUserChatsOptions): P
         : [options.userId, options.agentPermanentId];
     try {
         const summaryRows = await sql.raw<Array<UserChatSummarySeedSqlRow>>(
-            `
-                SELECT
-                    "id",
-                    "createdAt",
-                    "updatedAt",
-                    "lastMessageAt",
-                    "title",
-                    "source",
-                    "userId",
-                    COALESCE(jsonb_array_length("messages"), 0) AS "messagesCount",
-                    COALESCE(
-                        (
-                            SELECT message."value"->>'content'
-                            FROM jsonb_array_elements("messages") WITH ORDINALITY AS message("value", "ordinality")
-                            WHERE UPPER(COALESCE(message."value"->>'sender', '')) = 'USER'
-                            ORDER BY message."ordinality" ASC
-                            LIMIT 1
-                        ),
-                        ''
-                    ) AS "firstUserMessageContent",
-                    COALESCE(
-                        (
-                            SELECT message."value"->>'content'
-                            FROM jsonb_array_elements("messages") WITH ORDINALITY AS message("value", "ordinality")
-                            WHERE LENGTH(BTRIM(COALESCE(message."value"->>'content', ''))) > 0
-                            ORDER BY message."ordinality" DESC
-                            LIMIT 1
-                        ),
-                        ''
-                    ) AS "lastPreviewMessageContent",
-                    COALESCE(
-                        (
-                            SELECT COUNT(*)::INT
-                            FROM jsonb_array_elements("messages") AS message("value")
-                            WHERE
-                                UPPER(COALESCE(message."value"->>'sender', '')) IN ('AGENT', 'MODEL')
-                                AND (
-                                    COALESCE(message."value"->>'isComplete', '') = 'false'
-                                    OR LOWER(COALESCE(message."value"->>'lifecycleState', '')) IN ('queued', 'running')
-                                )
-                        ),
-                        0
-                    ) AS "pendingAssistantMessageCount"
-                FROM ${userChatTableName}
-                WHERE ${whereClause}
-                ORDER BY "createdAt" DESC
-            `,
+            spaceTrim(
+                (block) => `
+                    SELECT
+                        "id",
+                        "createdAt",
+                        "updatedAt",
+                        "lastMessageAt",
+                        "title",
+                        "source",
+                        "userId",
+                        COALESCE(jsonb_array_length("messages"), 0) AS "messagesCount",
+                        COALESCE(
+                            (
+                                SELECT message."value"->>'content'
+                                FROM jsonb_array_elements("messages") WITH ORDINALITY AS message("value", "ordinality")
+                                WHERE UPPER(COALESCE(message."value"->>'sender', '')) = 'USER'
+                                ORDER BY message."ordinality" ASC
+                                LIMIT 1
+                            ),
+                            ''
+                        ) AS "firstUserMessageContent",
+                        COALESCE(
+                            (
+                                SELECT message."value"->>'content'
+                                FROM jsonb_array_elements("messages") WITH ORDINALITY AS message("value", "ordinality")
+                                WHERE LENGTH(BTRIM(COALESCE(message."value"->>'content', ''))) > 0
+                                ORDER BY message."ordinality" DESC
+                                LIMIT 1
+                            ),
+                            ''
+                        ) AS "lastPreviewMessageContent",
+                        COALESCE(
+                            (
+                                SELECT COUNT(*)::INT
+                                FROM jsonb_array_elements("messages") AS message("value")
+                                WHERE
+                                    UPPER(COALESCE(message."value"->>'sender', '')) IN ('AGENT', 'MODEL')
+                                    AND (
+                                        COALESCE(message."value"->>'isComplete', '') = 'false'
+                                        OR LOWER(COALESCE(message."value"->>'lifecycleState', '')) IN ('queued', 'running')
+                                    )
+                            ),
+                            0
+                        ) AS "pendingAssistantMessageCount"
+                    FROM ${userChatTableName}
+                    WHERE ${block(whereClause)}
+                    ORDER BY "createdAt" DESC
+                `,
+            ),
             queryValues,
         );
 
@@ -194,19 +197,19 @@ async function listUserChatSummarySeedsViaSqlite(options: ListUserChatsOptions):
     const shouldLoadExternalChats =
         shouldLoadAllUsersChats || (options.viewerIsAdmin && options.includeExternalChats);
     const whereClause = shouldLoadAllUsersChats
-        ? `
+        ? spaceTrim(`
             chat."agentPermanentId" = ?
-        `
+        `)
         : shouldLoadExternalChats
-        ? `
+        ? spaceTrim(`
             chat."agentPermanentId" = ?
             AND (chat."source" <> ? OR chat."userId" = ?)
-        `
-        : `
+        `)
+        : spaceTrim(`
             chat."userId" = ?
             AND chat."agentPermanentId" = ?
             AND chat."source" = ?
-        `;
+        `);
     const queryValues = shouldLoadAllUsersChats
         ? [options.agentPermanentId]
         : shouldLoadExternalChats
@@ -216,54 +219,56 @@ async function listUserChatSummarySeedsViaSqlite(options: ListUserChatsOptions):
     try {
         const summaryRows = database
             .prepare(
-                `
-                    SELECT
-                        chat."id",
-                        chat."createdAt",
-                        chat."updatedAt",
-                        chat."lastMessageAt",
-                        chat."title",
-                        chat."source",
-                        chat."userId",
-                        COALESCE(json_array_length(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}), 0) AS "messagesCount",
-                        COALESCE(
-                            (
-                                SELECT CAST(json_extract(message.value, '$.content') AS TEXT)
-                                FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
-                                WHERE UPPER(CAST(COALESCE(json_extract(message.value, '$.sender'), '') AS TEXT)) = 'USER'
-                                ORDER BY CAST(message.key AS INTEGER) ASC
-                                LIMIT 1
-                            ),
-                            ''
-                        ) AS "firstUserMessageContent",
-                        COALESCE(
-                            (
-                                SELECT CAST(json_extract(message.value, '$.content') AS TEXT)
-                                FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
-                                WHERE LENGTH(TRIM(CAST(COALESCE(json_extract(message.value, '$.content'), '') AS TEXT))) > 0
-                                ORDER BY CAST(message.key AS INTEGER) DESC
-                                LIMIT 1
-                            ),
-                            ''
-                        ) AS "lastPreviewMessageContent",
-                        COALESCE(
-                            (
-                                SELECT COUNT(*)
-                                FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
-                                WHERE
-                                    UPPER(CAST(COALESCE(json_extract(message.value, '$.sender'), '') AS TEXT)) IN ('AGENT', 'MODEL')
-                                    AND (
-                                        json_extract(message.value, '$.isComplete') = 0
-                                        OR LOWER(CAST(COALESCE(json_extract(message.value, '$.isComplete'), '') AS TEXT)) = 'false'
-                                        OR LOWER(CAST(COALESCE(json_extract(message.value, '$.lifecycleState'), '') AS TEXT)) IN ('queued', 'running')
-                                    )
-                            ),
-                            0
-                        ) AS "pendingAssistantMessageCount"
-                    FROM ${userChatTableName} AS chat
-                    WHERE ${whereClause}
-                    ORDER BY chat."createdAt" DESC
-                `,
+                spaceTrim(
+                    (block) => `
+                        SELECT
+                            chat."id",
+                            chat."createdAt",
+                            chat."updatedAt",
+                            chat."lastMessageAt",
+                            chat."title",
+                            chat."source",
+                            chat."userId",
+                            COALESCE(json_array_length(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}), 0) AS "messagesCount",
+                            COALESCE(
+                                (
+                                    SELECT CAST(json_extract(message.value, '$.content') AS TEXT)
+                                    FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
+                                    WHERE UPPER(CAST(COALESCE(json_extract(message.value, '$.sender'), '') AS TEXT)) = 'USER'
+                                    ORDER BY CAST(message.key AS INTEGER) ASC
+                                    LIMIT 1
+                                ),
+                                ''
+                            ) AS "firstUserMessageContent",
+                            COALESCE(
+                                (
+                                    SELECT CAST(json_extract(message.value, '$.content') AS TEXT)
+                                    FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
+                                    WHERE LENGTH(TRIM(CAST(COALESCE(json_extract(message.value, '$.content'), '') AS TEXT))) > 0
+                                    ORDER BY CAST(message.key AS INTEGER) DESC
+                                    LIMIT 1
+                                ),
+                                ''
+                            ) AS "lastPreviewMessageContent",
+                            COALESCE(
+                                (
+                                    SELECT COUNT(*)
+                                    FROM json_each(${SQLITE_CHAT_MESSAGES_JSON_EXPRESSION}) AS message
+                                    WHERE
+                                        UPPER(CAST(COALESCE(json_extract(message.value, '$.sender'), '') AS TEXT)) IN ('AGENT', 'MODEL')
+                                        AND (
+                                            json_extract(message.value, '$.isComplete') = 0
+                                            OR LOWER(CAST(COALESCE(json_extract(message.value, '$.isComplete'), '') AS TEXT)) = 'false'
+                                            OR LOWER(CAST(COALESCE(json_extract(message.value, '$.lifecycleState'), '') AS TEXT)) IN ('queued', 'running')
+                                        )
+                                ),
+                                0
+                            ) AS "pendingAssistantMessageCount"
+                        FROM ${userChatTableName} AS chat
+                        WHERE ${block(whereClause)}
+                        ORDER BY chat."createdAt" DESC
+                    `,
+                ),
             )
             .all(...queryValues) as Array<UserChatSummarySeedSqlRow>;
 
@@ -410,10 +415,8 @@ async function listUserChatSummarySeedsViaSupabase(options: ListUserChatsOptions
 
 /**
  * Maps one full chat record into a lightweight summary seed.
- *
- * @private function of `userChat`
  */
-function createUserChatSummarySeedFromChatRecord(chat: UserChatRecord): UserChatSummarySeed {
+export function createUserChatSummarySeedFromChatRecord(chat: UserChatRecord): UserChatSummarySeed {
     return {
         id: chat.id,
         createdAt: chat.createdAt,