@promptbook/cli 0.112.0-99 → 0.113.0-0

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

@@ -0,0 +1,93 @@
+import type { ChatMessage, ToolCall } from '@promptbook-local/types';
+import { spaceTrim } from '../../../../../src/_packages/utils.index';
+import { TOOL_TITLES } from '../../../../../src/book-components/Chat/utils/getToolCallChipletInfo';
+import { isVisibleChatToolCall } from '../../../../../src/book-components/Chat/utils/isVisibleChatToolCall';
+import { resolveToolCallState } from '../../../../../src/book-components/Chat/utils/resolveToolCallState';
+
+/**
+ * Creates a user-facing progress card from the latest visible harness/tool action.
+ *
+ * @param toolCalls - Latest aggregated tool-call snapshots emitted by the agent runtime.
+ * @returns Progress card for the latest visible action, or null when there is no user-facing action yet.
+ */
+export function createUserChatHarnessProgressCard(
+    toolCalls: ReadonlyArray<ToolCall> | undefined,
+): NonNullable<ChatMessage['progressCard']> | null {
+    const latestVisibleToolCall = resolveLatestVisibleToolCall(toolCalls);
+    if (!latestVisibleToolCall) {
+        return null;
+    }
+
+    return {
+        now: createHarnessProgressNowText(latestVisibleToolCall),
+        items: [],
+        updatedAt: new Date().toISOString() as NonNullable<ChatMessage['progressCard']>['updatedAt'],
+        isVisible: true,
+    };
+}
+
+/**
+ * Resolves the latest user-facing tool call from an aggregated runtime snapshot.
+ *
+ * @private internal helper of `createUserChatHarnessProgressCard`
+ */
+function resolveLatestVisibleToolCall(toolCalls: ReadonlyArray<ToolCall> | undefined): ToolCall | null {
+    if (!toolCalls || toolCalls.length === 0) {
+        return null;
+    }
+
+    for (let index = toolCalls.length - 1; index >= 0; index--) {
+        const toolCall = toolCalls[index]!;
+        if (isVisibleChatToolCall(toolCall)) {
+            return toolCall;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Creates the current-action text shown in the progress card.
+ *
+ * @private internal helper of `createUserChatHarnessProgressCard`
+ */
+function createHarnessProgressNowText(toolCall: ToolCall): string {
+    const actionLabel = resolveToolCallActionLabel(toolCall);
+    const toolCallState = resolveToolCallState(toolCall);
+
+    switch (toolCallState) {
+        case 'COMPLETE':
+            return spaceTrim(`
+                Action completed: ${actionLabel}.
+            `);
+        case 'ERROR':
+            return spaceTrim(`
+                Action failed: ${actionLabel}.
+            `);
+        case 'PENDING':
+        case 'PARTIAL':
+        default:
+            return spaceTrim(`
+                Running action: ${actionLabel}.
+            `);
+    }
+}
+
+/**
+ * Resolves a concise user-facing action label from one technical tool call name.
+ *
+ * @private internal helper of `createUserChatHarnessProgressCard`
+ */
+function resolveToolCallActionLabel(toolCall: ToolCall): string {
+    const knownTitle = TOOL_TITLES[toolCall.name]?.title;
+    if (knownTitle) {
+        return knownTitle;
+    }
+
+    const normalizedName = toolCall.name
+        .trim()
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ');
+
+    return normalizedName || 'agent action';
+}

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

@@ -0,0 +1,57 @@
+import type { ChatMessage } from '@promptbook-local/types';
+import { spaceTrim } from '../../../../../src/_packages/utils.index';
+
+/**
+ * Runner types that can own durable chat work outside the browser request.
+ */
+export type UserChatRunnerKind = 'local' | 'external';
+
+/**
+ * Runner progress phases visible before a final answer is available.
+ */
+export type UserChatRunnerProgressPhase = 'queued_for_runner';
+
+/**
+ * User-facing labels for durable chat runners.
+ */
+const USER_CHAT_RUNNER_LABELS: Record<UserChatRunnerKind, string> = {
+    local: 'local agent runner',
+    external: 'external agent runner',
+};
+
+/**
+ * Creates a progress card for the observable state of an out-of-process chat runner.
+ *
+ * @param options - Runner kind and current progress phase.
+ * @returns Progress card with one concise real runner state.
+ */
+export function createUserChatRunnerProgressCard(options: {
+    readonly runnerKind: UserChatRunnerKind;
+    readonly phase: UserChatRunnerProgressPhase;
+}): NonNullable<ChatMessage['progressCard']> {
+    return {
+        now: createUserChatRunnerProgressNowText(options),
+        items: [],
+        updatedAt: new Date().toISOString() as NonNullable<ChatMessage['progressCard']>['updatedAt'],
+        isVisible: true,
+    };
+}
+
+/**
+ * Creates the current runner-state text shown in the progress card.
+ *
+ * @private internal helper of `createUserChatRunnerProgressCard`
+ */
+function createUserChatRunnerProgressNowText(options: {
+    readonly runnerKind: UserChatRunnerKind;
+    readonly phase: UserChatRunnerProgressPhase;
+}): string {
+    const runnerLabel = USER_CHAT_RUNNER_LABELS[options.runnerKind];
+
+    switch (options.phase) {
+        case 'queued_for_runner':
+            return spaceTrim(`
+                The ${runnerLabel} has the request and is working on the answer.
+            `);
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { ChatMessage } from '@promptbook-local/types';
+
+/**
+ * Returns `true` when the current transcript still suggests unfinished assistant work.
+ *
+ * This is intentionally message-based so readers can avoid heavier reconciliation work for
+ * settled chats while still inspecting threads that contain incomplete placeholders.
+ *
+ * @param messages - Current persisted chat transcript.
+ * @returns Whether the transcript still looks unfinished from the UI perspective.
+ * @private internal utility of `userChat`
+ */
+export function hasPotentiallyPendingAssistantMessages(messages: ReadonlyArray<ChatMessage>): boolean {
+    return messages.some((message) => {
+        const sender = String(message.sender || '').toUpperCase();
+        if (sender !== 'AGENT' && sender !== 'MODEL') {
+            return false;
+        }
+
+        return (
+            message.isComplete === false ||
+            message.lifecycleState === 'queued' ||
+            message.lifecycleState === 'running'
+        );
+    });
+}

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

@@ -1,5 +1,8 @@
 import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
+import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
+import { $provideAgentsServerSqliteDatabase } from '@/src/database/sqlite/$provideAgentsServerSqliteDatabase';
+import { ensureLocalSqliteTableReadIndexes } from '@/src/database/sqlite/$provideLocalSqliteSupabase';
 import type { ListUserChatsOptions, UserChatRecord } from './UserChatRecord';
 import type { UserChatSource } from './UserChatSource';
 import type { UserChatRow } from './UserChatRow';
@@ -31,7 +34,14 @@ const CLIENT_SQL_MISSING_CONNECTION_MESSAGE_FRAGMENT =
     'Environment variable `POSTGRES_URL` or `DATABASE_URL` must be defined.';
 
 /**
- * Lists all user chats for one agent ordered by last activity.
+ * SQLite expression that safely exposes chat messages as a JSON array.
+ *
+ * @private function of `userChat`
+ */
+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 creation time (newest first).
  */
 export async function listUserChats(options: ListUserChatsOptions): Promise<Array<UserChatRecord>> {
     const { userId, viewerIsAdmin, agentPermanentId, includeExternalChats = false } = options;
@@ -44,9 +54,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}`);
@@ -64,11 +72,15 @@ 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`
  */
 export async function listUserChatSummarySeeds(options: ListUserChatsOptions): Promise<Array<UserChatSummarySeed>> {
+    if (isAgentsServerSqliteMode()) {
+        return listUserChatSummarySeedsViaSqlite(options);
+    }
+
     if (!isDirectSqlConnectionConfigured()) {
         return listUserChatSummarySeedsViaSupabase(options);
     }
@@ -136,7 +148,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,
         );
@@ -151,6 +163,95 @@ export async function listUserChatSummarySeeds(options: ListUserChatsOptions): P
     }
 }
 
+/**
+ * Lists lightweight chat-summary seeds through direct SQLite JSON queries.
+ *
+ * @private function of `userChat`
+ */
+async function listUserChatSummarySeedsViaSqlite(options: ListUserChatsOptions): Promise<Array<UserChatSummarySeed>> {
+    const rawUserChatTableName = await $getTableName('UserChat');
+    ensureLocalSqliteTableReadIndexes(rawUserChatTableName);
+
+    const userChatTableName = quoteIdentifier(rawUserChatTableName);
+    const shouldLoadExternalChats = options.viewerIsAdmin && options.includeExternalChats;
+    const whereClause = shouldLoadExternalChats
+        ? `
+            chat."agentPermanentId" = ?
+            AND (chat."source" <> ? OR chat."userId" = ?)
+        `
+        : `
+            chat."userId" = ?
+            AND chat."agentPermanentId" = ?
+            AND chat."source" = ?
+        `;
+    const queryValues = shouldLoadExternalChats
+        ? [options.agentPermanentId, USER_CHAT_SOURCES.WEB_UI, options.userId]
+        : [options.userId, options.agentPermanentId, USER_CHAT_SOURCES.WEB_UI];
+
+    try {
+        const database = $provideAgentsServerSqliteDatabase();
+        const summaryRows = database
+            .prepare(
+                `
+                    SELECT
+                        chat."id",
+                        chat."createdAt",
+                        chat."updatedAt",
+                        chat."lastMessageAt",
+                        chat."title",
+                        chat."source",
+                        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
+                `,
+            )
+            .all(...queryValues) as Array<UserChatSummarySeedSqlRow>;
+
+        return summaryRows.map(mapUserChatSummarySeedSqlRow);
+    } catch (error) {
+        if (!isUserChatSummarySeedSqliteFallbackError(error)) {
+            throw error;
+        }
+
+        return listUserChatSummarySeedsViaSupabase(options);
+    }
+}
+
 /**
  * Raw SQL row shape loaded for lightweight chat summary seeds.
  *
@@ -260,6 +361,16 @@ function isUserChatSummarySeedSqlFallbackError(error: unknown): boolean {
     return /relation .* does not exist|column .* does not exist/i.test(errorMessage);
 }
 
+/**
+ * Returns true when SQLite summary optimization should gracefully fallback to Supabase-shaped reads.
+ *
+ * @private function of `userChat`
+ */
+function isUserChatSummarySeedSqliteFallbackError(error: unknown): boolean {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return /no such table|no such column|no such function: json_|malformed JSON/i.test(errorMessage);
+}
+
 /**
  * Loads chat-summary seeds using standard Supabase reads when SQL optimization is unavailable.
  *

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

@@ -0,0 +1,40 @@
+import {
+    createUserChatProgressCard,
+    type UserChatProgressContext,
+    type UserChatProgressPhase,
+} from './userChatProgressCard';
+import { updateUserChatAssistantMessage } from './updateUserChatAssistantMessage';
+
+/**
+ * Persists one durable chat progress phase onto the active assistant placeholder.
+ *
+ * The optional `context` carries real runtime details (agent name, provider, tool count,
+ * attachments, integrations) so the persisted progress card reflects what the worker is
+ * actually doing on this turn instead of a fixed scripted summary.
+ */
+export async function persistUserChatJobProgressCard(options: {
+    readonly userId: number;
+    readonly agentPermanentId: string;
+    readonly chatId: string;
+    readonly assistantMessageId: string;
+    readonly phase: UserChatProgressPhase;
+    readonly context?: UserChatProgressContext;
+}): Promise<void> {
+    await updateUserChatAssistantMessage({
+        userId: options.userId,
+        agentPermanentId: options.agentPermanentId,
+        chatId: options.chatId,
+        assistantMessageId: options.assistantMessageId,
+        mutateMessage: (message) => {
+            const lifecycleState = options.phase === 'queued' ? 'queued' : 'running';
+
+            return {
+                ...message,
+                lifecycleState,
+                lifecycleError: undefined,
+                isComplete: false,
+                progressCard: createUserChatProgressCard(options.phase, options.context),
+            };
+        },
+    });
+}

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

@@ -0,0 +1,100 @@
+import type { LlmToolDefinition } from '@promptbook-local/types';
+
+/**
+ * Maximum number of tool highlight labels surfaced in the progress card text.
+ *
+ * Keeps the rendered sentence readable when an agent exposes many tools.
+ */
+const MAX_TOOL_HIGHLIGHTS = 4;
+
+/**
+ * Maps technical tool identifiers to short user-facing labels shown in the
+ * durable chat progress card while capabilities are being checked.
+ */
+const USER_CHAT_PROGRESS_TOOL_LABEL_BY_NAME: Record<string, string> = {
+    web_search: 'web search',
+    deep_search: 'deep research',
+    useSearchEngine: 'web search',
+    search: 'web search',
+    useBrowser: 'web browser',
+    browse: 'web browser',
+    fetch_url_content: 'web browser',
+    run_browser: 'web browser',
+    get_current_time: 'time awareness',
+    useTime: 'time awareness',
+    set_timeout: 'timers',
+    cancel_timeout: 'timers',
+    list_timeouts: 'timers',
+    update_timeout: 'timers',
+    get_user_location: 'user location',
+    send_email: 'email sending',
+    useEmail: 'email sending',
+    spawn_agent: 'teammate agents',
+    retrieve_user_memory: 'long-term memory',
+    store_user_memory: 'long-term memory',
+    project_list_files: 'project files',
+    project_read_file: 'project files',
+    project_upsert_file: 'project files',
+    project_delete_file: 'project files',
+    project_create_branch: 'project repository',
+    project_create_pull_request: 'project repository',
+};
+
+/**
+ * Tool identifiers that should never appear as user-facing capability highlights.
+ *
+ * `agent_progress` is an internal runtime tool used by the worker to update this
+ * very progress card, and `assistant_preparation` is the engine-level chip shown
+ * while the model is being prepared. Neither describes a user-relevant capability.
+ */
+const HIDDEN_PROGRESS_TOOL_NAMES: ReadonlySet<string> = new Set(['agent_progress', 'assistant_preparation']);
+
+/**
+ * Derives a short, deduplicated list of user-facing tool labels for one durable chat turn.
+ *
+ * @public exported for `createRunUserChatJobExecutionContext`
+ */
+export function resolveUserChatProgressToolHighlights(
+    tools: ReadonlyArray<LlmToolDefinition>,
+): ReadonlyArray<string> {
+    const highlights: Array<string> = [];
+    const seenLabels = new Set<string>();
+
+    for (const tool of tools) {
+        if (!tool || typeof tool.name !== 'string') {
+            continue;
+        }
+
+        if (HIDDEN_PROGRESS_TOOL_NAMES.has(tool.name)) {
+            continue;
+        }
+
+        const label = USER_CHAT_PROGRESS_TOOL_LABEL_BY_NAME[tool.name] ?? humanizeToolName(tool.name);
+        if (!label || seenLabels.has(label)) {
+            continue;
+        }
+
+        seenLabels.add(label);
+        highlights.push(label);
+
+        if (highlights.length >= MAX_TOOL_HIGHLIGHTS) {
+            break;
+        }
+    }
+
+    return highlights;
+}
+
+/**
+ * Converts a technical tool identifier into a short readable label as a fallback.
+ *
+ * @private internal helper of `resolveUserChatProgressToolHighlights`
+ */
+function humanizeToolName(name: string): string {
+    const normalized = name.replace(/[_-]+/g, ' ').trim().toLowerCase();
+    if (!normalized) {
+        return '';
+    }
+
+    return normalized;
+}

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

@@ -1,18 +1,72 @@
-import { createHash } from 'crypto';
+import { randomBytes } from 'crypto';
+import { spaceTrim } from 'spacetrim';
+import { EnvironmentMismatchError } from '../../../../../src/errors/EnvironmentMismatchError';
+
+/**
+ * Cached internal worker token resolved from `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN` on first use.
+ *
+ * Computed lazily so module imports never fail eagerly at build time and the
+ * environment can still be configured before the first internal worker request.
+ *
+ * @private internal cache of `resolveUserChatWorkerInternalToken`
+ */
+let resolvedUserChatWorkerInternalToken: string | null = null;
 
 /**
  * Resolves the shared internal token used to protect background worker routes.
+ *
+ * In production, `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN` must be configured
+ * explicitly — falling back to any shared credential (in particular
+ * `ADMIN_PASSWORD` or `SUPABASE_SERVICE_ROLE_KEY`) or a hardcoded literal would
+ * let anyone who learns that value (or computes its publicly-known hash) drive
+ * internal worker jobs at will. Outside production, a per-process random token
+ * is generated on first use so local development works without configuration
+ * while still rejecting unsafe shared fallbacks.
+ *
+ * @returns Shared internal worker token.
+ * @throws {EnvironmentMismatchError} When the environment variable is missing in production.
+ *
+ * @private internal utility of Agents Server
  */
 export function resolveUserChatWorkerInternalToken(): string {
-    if (process.env.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN) {
-        return process.env.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN;
+    if (resolvedUserChatWorkerInternalToken !== null) {
+        return resolvedUserChatWorkerInternalToken;
+    }
+
+    const configuredToken = process.env.PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN?.trim();
+    if (configuredToken) {
+        resolvedUserChatWorkerInternalToken = configuredToken;
+        return resolvedUserChatWorkerInternalToken;
     }
 
-    const entropySource =
-        process.env.SUPABASE_SERVICE_ROLE_KEY ||
-        process.env.ADMIN_PASSWORD ||
-        process.env.NEXT_PUBLIC_SITE_URL ||
-        'promptbook-user-chat-worker';
+    if (process.env.NODE_ENV === 'production') {
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+                Missing required \`PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN\` environment variable in production.
+
+                The Agents Server protects its internal worker routes
+                (\`/api/internal/user-chat-jobs/run\`,
+                \`/api/internal/user-chat-timeouts/run\`, and
+                \`/api/internal/agent-runner-limits\`) with this shared token.
+                Reusing \`ADMIN_PASSWORD\`, \`SUPABASE_SERVICE_ROLE_KEY\`, or a
+                hardcoded fallback would let anyone who learns that value drive
+                background jobs at will.
+
+                **Fix:** set \`PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN\` to a long
+                random string (for example the output of \`openssl rand -hex 32\`)
+                in the deployment environment and restart the server.
+            `),
+        );
+    }
 
-    return createHash('sha256').update(`user-chat-worker:${entropySource}`).digest('hex');
+    resolvedUserChatWorkerInternalToken = randomBytes(32).toString('hex');
+    console.warn(
+        spaceTrim(`
+            \`PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN\` is not configured — generated
+            a random per-process internal worker token for this non-production run.
+            Pending internal worker invocations will be invalidated on every restart
+            until \`PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN\` is set.
+        `),
+    );
+    return resolvedUserChatWorkerInternalToken;
 }

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

@@ -44,7 +44,7 @@ type RunImmediateUserChatAnswerOptions = {
 };
 
 /**
- * Runs a fast local LLM answer into the incomplete assistant placeholder while the external runner is still working.
+ * Runs a fast local LLM pre-answer into the incomplete assistant placeholder while the external runner is still working.
  */
 export async function runImmediateUserChatAnswer(
     job: UserChatJobRecord,

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

@@ -20,7 +20,9 @@ import { finalizeUserChatJob } from './finalizeUserChatJob';
 import { getUserChat } from './getUserChat';
 import { heartbeatUserChatJob } from './heartbeatUserChatJob';
 import { persistUserChatJobTerminalState } from './persistUserChatJobTerminalState';
+import { persistUserChatJobProgressCard } from './persistUserChatJobProgressCard';
 import type { UserChatJobRecord } from './UserChatJobRecord';
+import type { UserChatProgressContext, UserChatProgressPhase } from './userChatProgressCard';
 import { createReplyAwareUserChatPromptContent, createReplyAwareUserChatPromptMessage } from './userChatReplies';
 import { resolvePromptThreadBeforeUserMessage } from './userChatMessageLifecycle';
 import { isUserChatNotFoundScopeError } from './UserChatScopeError';
@@ -107,6 +109,7 @@ export async function runUserChatJob(job: UserChatJobRecord): Promise<RunUserCha
         const executionContext = await createRunUserChatJobExecutionContext({
             job,
             ...startContext,
+            reportProgress: createRunUserChatJobProgressReporter(job),
         });
 
         return await executeRunUserChatJob({
@@ -122,6 +125,33 @@ export async function runUserChatJob(job: UserChatJobRecord): Promise<RunUserCha
     }
 }
 
+/**
+ * Creates a non-critical progress reporter for one durable chat job.
+ *
+ * @private function of `runUserChatJob`
+ */
+function createRunUserChatJobProgressReporter(
+    job: Pick<UserChatJobRecord, 'userId' | 'agentPermanentId' | 'chatId' | 'assistantMessageId' | 'id'>,
+): (phase: UserChatProgressPhase, context?: UserChatProgressContext) => Promise<void> {
+    return async (phase, context) => {
+        await persistUserChatJobProgressCard({
+            userId: job.userId,
+            agentPermanentId: job.agentPermanentId,
+            chatId: job.chatId,
+            assistantMessageId: job.assistantMessageId,
+            phase,
+            context,
+        }).catch((error) => {
+            console.warn('[user-chat-job] progress_update_failed', {
+                chatId: job.chatId,
+                jobId: job.id,
+                phase,
+                error,
+            });
+        });
+    };
+}
+
 /**
  * Loads and validates the chat/user/message snapshot required before one job can start.
  *