@promptbook/cli 0.112.0-117 → 0.112.0-119

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

@@ -168,10 +168,7 @@ function resolveAgentChatSidebarExpandedStatusClassName(activityKind: AgentChatS
  *
  * @private function of AgentChatSidebar
  */
-function AgentChatSidebarDefaultCollapsedRow({
-    item,
-    onChatSelect,
-}: AgentChatSidebarDefaultCollapsedRowProps) {
+function AgentChatSidebarDefaultCollapsedRow({ item, onChatSelect }: AgentChatSidebarDefaultCollapsedRowProps) {
     const statusClassName = resolveAgentChatSidebarCollapsedStatusClassName(
         item.content.activityIndicator.kind,
         item.isActive,
@@ -444,7 +441,9 @@ function AgentChatSidebarDefaultCollapsedSection({
             ) : (
                 <div className="flex min-h-0 w-full flex-1 flex-col gap-2 overflow-y-auto scrollbar-hidden">
                     {sidebarItems.length === 0 ? (
-                        <p className="px-1 text-center text-[11px] text-slate-500 dark:text-slate-400">{emptyStateText}</p>
+                        <p className="px-1 text-center text-[11px] text-slate-500 dark:text-slate-400">
+                            {emptyStateText}
+                        </p>
                     ) : (
                         sidebarItems.map((item) => (
                             <AgentChatSidebarDefaultCollapsedRow
@@ -600,7 +599,7 @@ export function AgentChatSidebarDefault({
                     </div>
                 </div>
 
-                <div className="agent-chat-sidebar-toggle-slot pointer-events-none absolute inset-y-0 right-0 z-10 hidden translate-x-1/2 items-center justify-center md:flex">
+                <div className="agent-chat-sidebar-toggle-slot pointer-events-none absolute inset-y-0 right-0 z-10 hidden translate-x-1 items-center justify-center md:flex">
                     <SolidArrowButton
                         direction={isCollapsed ? 'right' : 'left'}
                         onClick={onToggleCollapse}

package/apps/agents-server/src/app/api/page-preview/check/route.ts

@@ -0,0 +1,31 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
+
+/**
+ * Checks whether a given URL can be embedded in an iframe by inspecting
+ * `X-Frame-Options` and `Content-Security-Policy` `frame-ancestors` headers.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to check
+ *
+ * Returns `{ canEmbed: boolean }`.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    try {
+        const canEmbed = await checkIfUrlCanBeEmbedded(url);
+        return NextResponse.json({ canEmbed });
+    } catch (error) {
+        assertsError(error);
+        console.warn('Failed to check if URL can be embedded:', error.message);
+        // When the check fails, allow the iframe to try — the browser will handle it
+        return NextResponse.json({ canEmbed: true });
+    }
+}

package/apps/agents-server/src/app/api/page-preview/screenshot/route.ts

@@ -0,0 +1,57 @@
+import { $provideBrowserForServer } from '@/src/tools/$provideBrowserForServer';
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+
+/**
+ * Takes a screenshot of the given URL using a headless browser.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to screenshot
+ *
+ * Returns a PNG image.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    let parsedUrl: URL;
+    try {
+        parsedUrl = new URL(url);
+    } catch {
+        return NextResponse.json({ error: 'Invalid URL' }, { status: 400 });
+    }
+
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        return NextResponse.json({ error: 'Only http and https URLs are supported' }, { status: 400 });
+    }
+
+    try {
+        const browserContext = await $provideBrowserForServer();
+        const page = await browserContext.newPage();
+
+        try {
+            await page.setViewportSize({ width: 1280, height: 800 });
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            const screenshotBuffer = await page.screenshot({ type: 'png' });
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return new NextResponse(new Blob([screenshotBuffer as any]), {
+                headers: {
+                    'Content-Type': 'image/png',
+                    'Cache-Control': 'public, max-age=300',
+                },
+            });
+        } finally {
+            await page.close().catch(() => {});
+        }
+    } catch (error) {
+        assertsError(error);
+        console.error('Error taking page screenshot:', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/upload/route.ts

@@ -15,6 +15,7 @@ import {
 } from '../../../tools/$provideCdnForServer';
 import { $provideServer } from '../../../tools/$provideServer';
 import { getSafeCdnPath } from '../../../utils/cdn/utils/getSafeCdnPath';
+import { getUserFileCdnKey } from '../../../utils/cdn/utils/getUserFileCdnKey';
 import { FILE_SECURITY_CHECKERS } from '../../../file-security-checkers';
 import { getUserIdFromRequest } from '../../../utils/getUserIdFromRequest';
 import { getMaxFileUploadSizeBytes } from '../../../utils/serverLimits';
@@ -223,7 +224,7 @@ export async function POST(request: NextRequest) {
         const providedServer = await $provideServer();
         assertFileUploadAvailable(providedServer);
 
-        const { file, pathname, purpose, contentType } = await parseUploadRequest(request);
+        const { file, purpose, contentType } = await parseUploadRequest(request);
         const fileBuffer = Buffer.from(await file.arrayBuffer());
         const maxFileSize = await getMaxFileUploadSizeBytes();
 
@@ -237,6 +238,14 @@ export async function POST(request: NextRequest) {
             );
         }
 
+        // [✨🏣] Compute a content-addressed CDN key so the public URL contains
+        // the file hash and does not expose the internal S3 bucket or path prefix.
+        const rawKey = getUserFileCdnKey(fileBuffer, file.name);
+        const pathname = getSafeCdnPath({
+            pathname: rawKey,
+            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX,
+        });
+
         const cdn = $provideCdnForServer({
             cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
         });

package/apps/agents-server/src/app/s3/[first]/[second]/[hash]/[filename]/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+    $provideCdnForServer,
+    resolveCdnPublicUrlForServer,
+} from '../../../../../../tools/$provideCdnForServer';
+import { $provideServer } from '../../../../../../tools/$provideServer';
+
+/**
+ * Serves files stored under the hash-based CDN key format:
+ * `{hash[0]}/{hash[1]}/{sha256-hash}/{filename}`
+ *
+ * This route is reached when nginx routes a request matching
+ * `^/s3/[0-9a-f]/[0-9a-f]/[0-9a-f]{64}/` to Next.js instead of VersityGW,
+ * which keeps the internal S3 bucket and path prefix hidden from the public URL.
+ *
+ * [✨🏣] Companion route for `getUserFileCdnKey` and the `publicCdnBaseUrl`
+ * configuration in `$provideCdnForServer`.
+ */
+export async function GET(
+    _request: NextRequest,
+    {
+        params,
+    }: {
+        params: Promise<{
+            first: string;
+            second: string;
+            hash: string;
+            filename: string;
+        }>;
+    },
+) {
+    const { first, second, hash, filename } = await params;
+    const key = `${first}/${second}/${hash}/${filename}`;
+
+    const providedServer = await $provideServer();
+    const cdn = $provideCdnForServer({
+        cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
+    });
+
+    const file = await cdn.getItem(key);
+
+    if (!file) {
+        return new NextResponse(null, { status: 404 });
+    }
+
+    return new NextResponse(file.data, {
+        headers: {
+            'Content-Type': file.type,
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        },
+    });
+}

package/apps/agents-server/src/database/$provideClientSql.ts

@@ -31,6 +31,33 @@ export type ClientSqlExecutor = ClientSql & {
     readonly raw: ClientSqlRaw;
 };
 
+/**
+ * Maximum number of PostgreSQL connections in the shared pool.
+ *
+ * Configurable via `DATABASE_POOL_MAX` environment variable.
+ * Defaults to 20 which comfortably handles concurrent chat-stream polling loads.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const DATABASE_POOL_MAX = Math.max(1, parseInt(process.env.DATABASE_POOL_MAX || '20', 10));
+
+/**
+ * Milliseconds to wait for a free pool connection before failing.
+ *
+ * Without a timeout the default `pg` behaviour is to queue requests indefinitely,
+ * which causes the server to become unresponsive under pool exhaustion.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_CONNECTION_TIMEOUT_MS = 15_000;
+
+/**
+ * Milliseconds an idle client stays in the pool before being closed.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_IDLE_TIMEOUT_MS = 30_000;
+
 /**
  * Shared PostgreSQL pool reused across all requests in the server process.
  *
@@ -52,6 +79,16 @@ export async function $provideClientSql(): Promise<ClientSqlExecutor> {
         clientPool = new Pool({
             connectionString: resolvePostgresConnectionString(),
             ssl: { rejectUnauthorized: false },
+            max: DATABASE_POOL_MAX,
+            idleTimeoutMillis: POOL_IDLE_TIMEOUT_MS,
+            connectionTimeoutMillis: POOL_CONNECTION_TIMEOUT_MS,
+            allowExitOnIdle: true,
+        });
+
+        // Prevent unhandled errors from crashing the pool or the process.
+        // Individual query errors are still thrown at the call site.
+        clientPool.on('error', (error) => {
+            console.error('[database] Unexpected error on idle PostgreSQL client:', error);
         });
     }
 

package/apps/agents-server/src/database/$provideSupabaseForServer.ts

@@ -4,6 +4,44 @@ import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
 import { $provideLocalSqliteSupabase } from './sqlite/$provideLocalSqliteSupabase';
 import { AgentsServerDatabase } from './schema';
 
+/**
+ * Hard timeout for every Supabase HTTP request.
+ *
+ * Without this, a slow or unreachable PostgREST endpoint causes requests to
+ * hang indefinitely, eventually making the server appear unresponsive.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const SUPABASE_REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * Wraps the native `fetch` with a per-request timeout so Supabase queries
+ * always resolve (with an error) within `SUPABASE_REQUEST_TIMEOUT_MS`.
+ *
+ * When the caller already passes an AbortSignal the request is aborted when
+ * either that signal fires or the timeout fires — whichever comes first.
+ *
+ * Uses manual composition instead of `AbortSignal.any` for Node.js 18 compatibility
+ * (`AbortSignal.any` is only available in Node.js 20.3+).
+ *
+ * @private internal helper of Agents Server database layer
+ */
+function fetchWithSupabaseTimeout(url: RequestInfo | URL, options?: RequestInit): Promise<Response> {
+    const existingSignal = options?.signal instanceof AbortSignal ? options.signal : null;
+
+    if (!existingSignal) {
+        return fetch(url, { ...options, signal: AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS) });
+    }
+
+    // Compose the caller signal with the timeout: abort when either fires.
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    existingSignal.addEventListener('abort', abort, { once: true });
+    AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS).addEventListener('abort', abort, { once: true });
+
+    return fetch(url, { ...options, signal: controller.signal });
+}
+
 /**
  * Internal cache for `$provideSupabaseForServer`
  *
@@ -42,6 +80,9 @@ export function $provideSupabaseForServer(): SupabaseClient<AgentsServerDatabase
                     autoRefreshToken: false,
                     persistSession: false,
                 },
+                global: {
+                    fetch: fetchWithSupabaseTimeout,
+                },
             },
         );
     }

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -74,6 +74,13 @@ function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
             gzip: true,
             forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
             region: resolveS3CompatibleStorageRegion(),
+            // [✨🏣] For self-contained S3: hash-based CDN keys get a public URL that
+            // omits the internal bucket and pathPrefix so users can't infer the storage
+            // structure. The `/s3/` segment is preserved so nginx routes those requests
+            // to the Next.js hash-file route instead of directly to VersityGW.
+            publicCdnBaseUrl: isSelfContainedS3StorageSelected()
+                ? resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl)
+                : undefined,
         });
     }
 
@@ -84,6 +91,23 @@ function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
     });
 }
 
+/**
+ * Derives the public base URL used for hash-based file URLs on self-contained S3.
+ *
+ * Strips the bucket segment from the configured CDN URL so that the public URL
+ * exposes only the `/s3/` prefix — the internal bucket name and path prefix
+ * remain hidden from users.
+ *
+ * Example: `https://s24.ptbk.io/s3/promptbook-files/` → `https://s24.ptbk.io/s3/`
+ *
+ * [✨🏣] Companion to `isHashBasedCdnKey` in `DigitalOceanSpaces`.
+ *
+ * @private helper of `createCdnStorageForServer`
+ */
+function resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl: URL): URL {
+    return new URL('/s3/', cdnPublicUrl);
+}
+
 /**
  * Resolves the CDN public URL from environment configuration.
  *

package/apps/agents-server/src/utils/cdn/classes/DigitalOceanSpaces.ts

@@ -19,6 +19,16 @@ type IDigitalOceanSpacesConfig = {
     readonly forcePathStyle?: boolean;
     readonly region?: string;
 
+    /**
+     * When set, `getItemUrl` generates `new URL(key, publicCdnBaseUrl)` for
+     * hash-based CDN keys instead of the default formula that prepends the
+     * `pathPrefix`. This allows self-contained S3 to expose an unguessable URL
+     * that hides the internal bucket name and path prefix.
+     *
+     * [✨🏣] Used by self-contained S3 to serve files via the Next.js hash route.
+     */
+    readonly publicCdnBaseUrl?: URL;
+
     // TODO: [⛳️] Probbably prefix should be in this config not on the consumer side
 };
 
@@ -27,7 +37,7 @@ type IDigitalOceanSpacesConfig = {
  */
 export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     public get cdnPublicUrl() {
-        return this.config.cdnPublicUrl;
+        return this.config.publicCdnBaseUrl ?? this.config.cdnPublicUrl;
     }
 
     private s3: S3Client;
@@ -45,7 +55,13 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     }
 
     public getItemUrl(key: string): URL {
-        return new URL(this.config.pathPrefix + '/' + key, this.cdnPublicUrl);
+        // [✨🏣] For hash-based keys, omit the pathPrefix from the public URL so
+        // the internal S3 structure (bucket, prefix, upload directory) is hidden.
+        if (this.config.publicCdnBaseUrl && isHashBasedCdnKey(key)) {
+            return new URL(key, this.config.publicCdnBaseUrl);
+        }
+
+        return new URL(this.config.pathPrefix + '/' + key, this.config.cdnPublicUrl);
     }
 
     public async getItem(key: string): Promise<IFile | null> {
@@ -122,6 +138,18 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     }
 }
 
+/**
+ * Returns `true` when `key` matches the hash-based CDN key format produced by
+ * `getUserFileCdnKey`: `{hex}/{hex}/{sha256-64-chars}/{filename}`.
+ *
+ * [✨🏣] Used by `getItemUrl` to decide whether to strip the internal path prefix.
+ *
+ * @private helper of `DigitalOceanSpaces`
+ */
+function isHashBasedCdnKey(key: string): boolean {
+    return /^[0-9a-f]\/[0-9a-f]\/[0-9a-f]{64}\//.test(key);
+}
+
 /**
  * Normalizes endpoint values from legacy host-only configuration and full S3 URLs.
  *

package/apps/agents-server/src/utils/cdn/utils/getUserFileCdnKey.ts

@@ -2,10 +2,15 @@ import hexEncoder from 'crypto-js/enc-hex';
 import sha256 from 'crypto-js/sha256';
 import type { string_uri } from '../../../../../../src/types/typeAliases';
 import { titleToName } from '../../../../../../src/utils/normalization/titleToName';
-import { nameToSubfolderPath } from './nameToSubfolderPath';
 
 /**
- * Generates a path for the user content
+ * Generates a content-addressed path for user-uploaded files.
+ *
+ * The returned key uses the SHA-256 hash of the file buffer so the URL is
+ * unguessable and does not expose internal storage structure (bucket, prefix,
+ * or upload directory). The first two hex characters are used as single-level
+ * shard directories, matching the same convention as the public URL served by
+ * the hash-based file route.
  */
 export function getUserFileCdnKey(file: Buffer, originalFilename: string): string_uri {
     const hash = sha256(hexEncoder.parse(file.toString('hex'))).toString(/* hex */);
@@ -18,7 +23,9 @@ export function getUserFileCdnKey(file: Buffer, originalFilename: string): strin
     const filename = name + '.' + extension;
     // <- Note: [⛳️] Preserving original file name
 
-    return `user/files/${nameToSubfolderPath(hash).join('/')}/${filename}`;
+    // [✨🏣] Hash-based key: {hash[0]}/{hash[1]}/{fullHash}/{filename}
+    // The single-char shard dirs and full hash hide the internal S3 structure.
+    return `${hash[0]}/${hash[1]}/${hash}/${filename}`;
 }
 
 // TODO: [🌍] Unite this logic in one place

package/apps/agents-server/src/utils/externalChatRunner/processExternalUserChatJob.ts

@@ -1,4 +1,5 @@
 import type { Json } from '@/src/database/schema';
+import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
 import { finalizeUserChatJob } from '../userChat/finalizeUserChatJob';
@@ -148,13 +149,22 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
         return { didMutate: false, outcome: 'waiting' };
     }
 
-    const threadMessages = [...previousThreadMessages, userMessage]
-        .filter((message) => message.isComplete !== false)
-        .filter((message) => message.sender === 'USER' || message.sender === 'AGENT')
-        .map((message) => ({
-            sender: String(message.sender),
-            content: message.content,
-        }));
+    const agentInitialMessage = previousThreadMessages.length === 0
+        ? parseAgentSource(agentSourceSnapshot.agentSource).initialMessage
+        : null;
+    const initialAgentThreadMessages = agentInitialMessage
+        ? [{ sender: 'AGENT' as const, content: agentInitialMessage }]
+        : [];
+
+    const threadMessages = [
+        ...initialAgentThreadMessages,
+        ...[...previousThreadMessages, userMessage]
+            .filter((message) => message.isComplete !== false)
+            .filter((message) => message.sender === 'USER' || message.sender === 'AGENT'),
+    ].map((message) => ({
+        sender: String(message.sender),
+        content: message.content,
+    }));
 
     const repository = await ensureExternalAgentRepository(agentSourceSnapshot);
     const queuedAt = new Date().toISOString();

package/apps/agents-server/src/utils/iframe/checkIfUrlCanBeEmbedded.ts

@@ -0,0 +1,68 @@
+/**
+ * Parses the X-Frame-Options header value and returns whether embedding is allowed.
+ *
+ * Some servers set multiple values (e.g. "DENY, SAMEORIGIN") which results in a
+ * comma-separated string. Any DENY or SAMEORIGIN token blocks embedding.
+ */
+function canEmbedByXFrameOptions(headerValue: string): boolean {
+    const values = headerValue
+        .split(',')
+        .map((v) => v.trim().toUpperCase());
+    return !values.some((v) => v === 'DENY' || v === 'SAMEORIGIN');
+}
+
+/**
+ * Parses the Content-Security-Policy header and checks the `frame-ancestors` directive.
+ *
+ * Returns false when `frame-ancestors` is present and does not include a wildcard or
+ * protocol-level allow (`*`, `https:`, `http:`).
+ */
+function canEmbedByCsp(cspHeader: string): boolean {
+    const match = cspHeader.match(/frame-ancestors\s+([^;]+)/i);
+    if (!match) {
+        return true;
+    }
+
+    const directive = (match[1] ?? '').trim();
+    const tokens = directive.split(/\s+/);
+
+    for (const token of tokens) {
+        if (token === '*' || token === 'https:' || token === 'http:') {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Checks whether a given HTTP(S) URL allows being embedded in an iframe by
+ * inspecting `X-Frame-Options` and `Content-Security-Policy` `frame-ancestors`.
+ *
+ * Returns `true` when the page is embeddable, `false` when it is blocked.
+ * Throws when the URL is not HTTP(S) or the network request fails.
+ */
+export async function checkIfUrlCanBeEmbedded(url: string): Promise<boolean> {
+    const parsedUrl = new URL(url);
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new Error(`Only http and https URLs are supported, got: ${parsedUrl.protocol}`);
+    }
+
+    const response = await fetch(url, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(10_000),
+        redirect: 'follow',
+    });
+
+    const xFrameOptions = response.headers.get('X-Frame-Options');
+    if (xFrameOptions !== null && !canEmbedByXFrameOptions(xFrameOptions)) {
+        return false;
+    }
+
+    const csp = response.headers.get('Content-Security-Policy');
+    if (csp !== null && !canEmbedByCsp(csp)) {
+        return false;
+    }
+
+    return true;
+}

package/apps/agents-server/src/utils/localChatRunner/processLocalUserChatJob.ts

@@ -1,6 +1,7 @@
 import type { Json } from '@/src/database/schema';
 import { mkdir, readFile, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
+import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
 import { finalizeUserChatJob } from '../userChat/finalizeUserChatJob';
@@ -145,13 +146,22 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         return { didMutate: false, outcome: 'waiting' };
     }
 
-    const threadMessages = [...previousThreadMessages, userMessage]
-        .filter((message) => message.isComplete !== false)
-        .filter((message) => message.sender === 'USER' || message.sender === 'AGENT')
-        .map((message) => ({
-            sender: String(message.sender),
-            content: message.content,
-        }));
+    const agentInitialMessage = previousThreadMessages.length === 0
+        ? parseAgentSource(agentSourceSnapshot.agentSource).initialMessage
+        : null;
+    const initialAgentThreadMessages = agentInitialMessage
+        ? [{ sender: 'AGENT' as const, content: agentInitialMessage }]
+        : [];
+
+    const threadMessages = [
+        ...initialAgentThreadMessages,
+        ...[...previousThreadMessages, userMessage]
+            .filter((message) => message.isComplete !== false)
+            .filter((message) => message.sender === 'USER' || message.sender === 'AGENT'),
+    ].map((message) => ({
+        sender: String(message.sender),
+        content: message.content,
+    }));
 
     const agentFolder = await ensureLocalAgentFolder(agentSourceSnapshot);
     const queuedAt = new Date().toISOString();

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

@@ -29,7 +29,9 @@ const IMMEDIATE_USER_CHAT_ANSWER_INSTRUCTION_COMMITMENTS = new Set<string>([
  * Prefix added to the immediate pre-answer system message.
  */
 const IMMEDIATE_USER_CHAT_ANSWER_SYSTEM_PREAMBLE = spaceTrim(`
+    
     You are preparing a short in-progress confirmation for the user while a slower full agent run continues separately.
+
     This response is not the final answer. It is only a confirmation that the task is being handled.
     These immediate-answer rules override any agent instruction below that would make the answer sound final or complete.
 
@@ -37,6 +39,7 @@ const IMMEDIATE_USER_CHAT_ANSWER_SYSTEM_PREAMBLE = spaceTrim(`
     - You understood what the user wants.
     - You are working on it now or the job has already started.
     - The final answer will arrive after the background processing finishes.
+    - You can use Markdown formatting in the messages like **bold** or *italic*
 
     Keep the whole response short, preferably one or two sentences.
     Do not provide any part of the final answer yet.
@@ -46,6 +49,14 @@ const IMMEDIATE_USER_CHAT_ANSWER_SYSTEM_PREAMBLE = spaceTrim(`
     Do not use or claim to have used external tools, memory, knowledge bases, web browsing, search, calendar, email, projects, or teammate agents.
     Never present this message as complete, definitive, or ready to use.
     If the user asks for something that clearly requires unavailable capabilities, simply say the checked final answer is still being prepared.
+
+
+    Example of a good immediate pre-answer response:
+
+    \`\`\`markdown
+    xxx
+    \`\`\`
+
 `);
 
 /**

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

@@ -40,7 +40,7 @@ const CLIENT_SQL_MISSING_CONNECTION_MESSAGE_FRAGMENT =
 const SQLITE_CHAT_MESSAGES_JSON_EXPRESSION = `CASE WHEN json_valid(chat."messages") THEN chat."messages" ELSE '[]' END`;
 
 /**
- * Lists all user chats for one agent ordered by last activity.
+ * Lists all user chats for one agent ordered by creation time (newest first).
  */
 export async function listUserChats(options: ListUserChatsOptions): Promise<Array<UserChatRecord>> {
     const { userId, viewerIsAdmin, agentPermanentId, includeExternalChats = false } = options;
@@ -53,9 +53,7 @@ export async function listUserChats(options: ListUserChatsOptions): Promise<Arra
               .eq('userId', userId)
               .eq('agentPermanentId', agentPermanentId)
               .eq('source', USER_CHAT_SOURCES.WEB_UI);
-    const { data, error } = await query
-        .order('lastMessageAt', { ascending: false, nullsFirst: false })
-        .order('updatedAt', { ascending: false });
+    const { data, error } = await query.order('createdAt', { ascending: false });
 
     if (error) {
         throw new Error(`Failed to list user chats: ${error.message}`);
@@ -73,7 +71,7 @@ export async function listUserChats(options: ListUserChatsOptions): Promise<Arra
 }
 
 /**
- * Lists lightweight chat-summary seeds without loading full `messages` JSON payloads.
+ * Lists lightweight chat-summary seeds without loading full `messages` JSON payloads, ordered by creation time (newest first).
  *
  * @private function of `userChat`
  */
@@ -149,7 +147,7 @@ export async function listUserChatSummarySeeds(options: ListUserChatsOptions): P
                     ) AS "pendingAssistantMessageCount"
                 FROM ${userChatTableName}
                 WHERE ${whereClause}
-                ORDER BY "lastMessageAt" DESC NULLS LAST, "updatedAt" DESC
+                ORDER BY "createdAt" DESC
             `,
             queryValues,
         );
@@ -235,7 +233,7 @@ async function listUserChatSummarySeedsViaSqlite(options: ListUserChatsOptions):
                         ) AS "pendingAssistantMessageCount"
                     FROM ${userChatTableName} AS chat
                     WHERE ${whereClause}
-                    ORDER BY chat."lastMessageAt" IS NULL ASC, chat."lastMessageAt" DESC, chat."updatedAt" DESC
+                    ORDER BY chat."createdAt" DESC
                 `,
             )
             .all(...queryValues) as Array<UserChatSummarySeedSqlRow>;