@promptbook/cli 0.112.0-99 → 0.112.0

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';
@@ -6,6 +7,7 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
+import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
@@ -148,13 +150,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();
@@ -186,6 +197,10 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'external',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 

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

@@ -0,0 +1,36 @@
+import { findAgentByIdentifier, findOwnedAgentByIdentifier, type OwnedAgentRow } from './agentOwnership';
+import { getCurrentUser } from './getCurrentUser';
+import { isUserAdmin } from './isUserAdmin';
+
+/**
+ * Loads one agent for the current caller, enforcing ownership-or-admin write access.
+ *
+ * Resolution order:
+ * 1. Anonymous callers receive `null` so routes can return `403`.
+ * 2. Owners are matched via {@link findOwnedAgentByIdentifier} using the authenticated user id.
+ * 3. Administrators (resolved via {@link isUserAdmin}) fall through to {@link findAgentByIdentifier} so they can manage any agent — including legacy `ADMIN_PASSWORD` admins that have no database user id.
+ *
+ * @param identifier - Permanent id or agent name supplied by the route.
+ * @returns Matching agent row when the caller owns it or is an administrator, otherwise `null`.
+ *
+ * @private internal helper of Agents Server route handlers
+ */
+export async function findAgentForCallerWriteAccess(identifier: string): Promise<OwnedAgentRow | null> {
+    const [currentUser, isAdmin] = await Promise.all([getCurrentUser(), isUserAdmin()]);
+    if (!currentUser) {
+        return null;
+    }
+
+    if (typeof currentUser.id === 'number') {
+        const ownedAgent = await findOwnedAgentByIdentifier(currentUser.id, identifier);
+        if (ownedAgent) {
+            return ownedAgent;
+        }
+    }
+
+    if (!isAdmin) {
+        return null;
+    }
+
+    return findAgentByIdentifier(identifier);
+}

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

@@ -3,6 +3,7 @@ import { cache } from 'react';
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../database/schema';
+import { isAdminPasswordEqual } from './isAdminPasswordEqual';
 import { getSession } from './session';
 
 /**
@@ -75,7 +76,7 @@ const getCachedCurrentUser = cache(async (): Promise<UserInfo | null> => {
     if (process.env.ADMIN_PASSWORD) {
         const cookieStore = await cookies();
         const adminToken = cookieStore.get('adminToken');
-        if (adminToken?.value === process.env.ADMIN_PASSWORD) {
+        if (adminToken?.value !== undefined && isAdminPasswordEqual(adminToken.value)) {
             return {
                 username: 'admin',
                 isAdmin: true,

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

@@ -1,27 +1,6 @@
 import { string_promptbook_server_url } from '@promptbook-local/types';
 import { getMetadataMap } from '../database/getMetadata';
 
-/**
- * Options that tweak the behavior of `getFederatedServers`.
- *
- * @public exported from `apps/agents-server`
- */
-export type GetFederatedServersOptions = {
-    /**
-     * When set, hide the core server from the resulting list if the metadata flag requests it.
-     *
-     * @private Internal toggle for UI surfaces that should hide the core server.
-     */
-    readonly excludeHiddenCoreServer?: boolean;
-};
-
-/**
- * Metadata key storing the core server URL.
- *
- * @private
- */
-const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
-
 /**
  * Metadata key storing the comma-separated federated servers list.
  *
@@ -29,67 +8,17 @@ const CORE_SERVER_METADATA_KEY = 'CORE_SERVER';
  */
 const FEDERATED_SERVERS_METADATA_KEY = 'FEDERATED_SERVERS';
 
-/**
- * Metadata key indicating whether the core server should be hidden from UI lists.
- *
- * @private
- */
-const IS_CORE_SERVER_HIDDEN_METADATA_KEY = 'IS_CORE_SERVER_HIDDEN';
-
 /**
  * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
  *
  * @public exported from `apps/agents-server`
  */
-export async function getFederatedServers(options?: GetFederatedServersOptions): Promise<string_promptbook_server_url[]> {
-    const metadata = await getMetadataMap([
-        FEDERATED_SERVERS_METADATA_KEY,
-        CORE_SERVER_METADATA_KEY,
-        IS_CORE_SERVER_HIDDEN_METADATA_KEY,
-    ]);
+export async function getFederatedServers(): Promise<string_promptbook_server_url[]> {
+    const metadata = await getMetadataMap([FEDERATED_SERVERS_METADATA_KEY]);
     const federatedServersString = metadata[FEDERATED_SERVERS_METADATA_KEY] || '';
-    const rawCoreServer = metadata[CORE_SERVER_METADATA_KEY] || '';
-    const coreServer = rawCoreServer.trim() as string_promptbook_server_url;
 
-    if (!coreServer) {
-        throw new Error('Missing CORE_SERVER metadata value');
-    }
-
-    const federatedServers = federatedServersString
+    return federatedServersString
         .split(',')
         .map((server) => server.trim())
         .filter((server): server is string_promptbook_server_url => server !== '');
-
-    const allServers = [coreServer, ...federatedServers];
-    if (options?.excludeHiddenCoreServer && isCoreServerHidden(metadata)) {
-        const normalizedCoreServer = normalizeServerUrl(coreServer);
-        return allServers.filter((server) => normalizeServerUrl(server) !== normalizedCoreServer);
-    }
-
-    return allServers;
-}
-
-/**
- * Determines if the metadata flag explicitly hides the core server from UI lists.
- *
- * @param metadata - Metadata map containing IS_CORE_SERVER_HIDDEN value.
- * @returns Whether the core server should be hidden.
- *
- * @private Internal helper for filtering UI-friendly lists.
- */
-function isCoreServerHidden(metadata: Record<string, string | null>): boolean {
-    const rawValue = metadata[IS_CORE_SERVER_HIDDEN_METADATA_KEY] || '';
-    return rawValue.trim().toLowerCase() === 'true';
-}
-
-/**
- * Normalizes a server URL by trimming trailing slashes for comparison purposes.
- *
- * @param value - Raw server URL.
- * @returns Normalized server URL.
- *
- * @private Internal helper used when filtering hidden servers.
- */
-function normalizeServerUrl(value: string): string {
-    return value.replace(/\/+$/, '');
 }

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

@@ -3,21 +3,35 @@ import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForSer
 import type { AgentsServerDatabase } from '@/src/database/schema';
 
 /**
- * Database row shape for `User`.
+ * User row shape needed by durable chat execution.
  */
-type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+type UserByIdRow = Pick<
+    AgentsServerDatabase['public']['Tables']['User']['Row'],
+    'id' | 'username' | 'isAdmin' | 'profileImageUrl'
+>;
+
+/**
+ * Supabase projection for user fields needed by durable chat execution.
+ */
+const USER_BY_ID_SELECT_COLUMNS = 'id, username, isAdmin, profileImageUrl';
 
 /**
  * Loads one user row by database id.
+ *
+ * @private internal Agents Server user lookup helper
  */
-export async function getUserById(userId: number): Promise<UserRow | null> {
+export async function getUserById(userId: number): Promise<UserByIdRow | null> {
     const supabase = $provideSupabaseForServer();
     const tableName = await $getTableName('User');
-    const { data, error } = await supabase.from(tableName).select('*').eq('id', userId).maybeSingle();
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(USER_BY_ID_SELECT_COLUMNS)
+        .eq('id', userId)
+        .maybeSingle();
 
     if (error) {
         throw new Error(`Failed to resolve user "${userId}": ${error.message}`);
     }
 
-    return (data as UserRow | null) || null;
+    return (data as UserByIdRow | null) || null;
 }

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

@@ -1,14 +1,20 @@
 import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../servers';
 import { string_agent_url } from '../../../../src/_packages/types.index'; // <- [🚾]
-import { getMetadata } from '../database/getMetadata';
+import { resolveCurrentOrInternalServerOrigin } from './resolveCurrentOrInternalServerOrigin';
 
 /**
- * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
+ * Resolves the URL of one well-known agent (Adam, Teacher, ...) hosted locally in the `.core` folder of the current Agents Server.
+ *
+ * @param agentName - Logical well-known agent identifier.
+ * @returns Absolute URL of the well-known agent on the current server.
+ *
+ * @private utility of Agents Server
  */
 export async function getWellKnownAgentUrl(
     agentName: keyof typeof CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES,
 ): Promise<string_agent_url> {
-    const coreServer = (await getMetadata('CORE_SERVER'))!;
+    const localServerOrigin = await resolveCurrentOrInternalServerOrigin();
+    const normalizedServerOrigin = localServerOrigin.replace(/\/+$/g, '');
 
-    return `${coreServer}agents/${CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]}` as string_agent_url;
+    return `${normalizedServerOrigin}/agents/${CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]}` as string_agent_url;
 }

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/interactiveTerminalSession.ts

@@ -188,7 +188,12 @@ export function startInteractiveTerminalSession(
     const sessionId = randomUUID();
     const childProcess = spawn(options.command, [...(options.arguments || [])], {
         cwd: options.cwd,
-        env: options.env,
+        env: {
+            ...process.env,
+            TERM: 'xterm-256color',
+            COLORTERM: 'truecolor',
+            ...options.env,
+        },
         stdio: ['pipe', 'pipe', 'pipe'],
     });
 
@@ -359,13 +364,13 @@ function appendInteractiveTerminalOutput(session: InteractiveTerminalSession, ra
 }
 
 /**
- * Normalizes streamed terminal output for browser rendering.
+ * Preserves streamed terminal output for the xterm browser renderer.
  *
  * @param output - Raw process output chunk.
- * @returns UI-friendly terminal text.
+ * @returns Raw terminal text with ANSI control sequences intact.
  */
 function normalizeInteractiveTerminalOutput(output: string): string {
-    return output.replace(/\r\n/gu, '\n').replace(/\r/gu, '\n');
+    return output;
 }
 
 /**

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

@@ -0,0 +1,28 @@
+import { timingSafeEqual } from 'crypto';
+
+/**
+ * Compares a candidate string against the `ADMIN_PASSWORD` environment variable
+ * using a constant-time algorithm to prevent timing attacks.
+ *
+ * Returning `false` early when the byte lengths differ does not expose character
+ * content — only length — which is an acceptable trade-off, since `timingSafeEqual`
+ * requires equal-length buffers and length is typically not secret.
+ *
+ * @param candidate The value to compare against the configured admin password.
+ * @returns `true` when `candidate` matches `ADMIN_PASSWORD`, `false` otherwise.
+ */
+export function isAdminPasswordEqual(candidate: string): boolean {
+    const adminPassword = process.env.ADMIN_PASSWORD;
+    if (!adminPassword) {
+        return false;
+    }
+
+    const candidateBuffer = Buffer.from(candidate);
+    const adminPasswordBuffer = Buffer.from(adminPassword);
+
+    if (candidateBuffer.length !== adminPasswordBuffer.length) {
+        return false;
+    }
+
+    return timingSafeEqual(candidateBuffer, adminPasswordBuffer);
+}

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

@@ -1,5 +1,6 @@
 import { cookies } from 'next/headers';
 import { cache } from 'react';
+import { isAdminPasswordEqual } from './isAdminPasswordEqual';
 import { getSession } from './session';
 
 /**
@@ -18,7 +19,8 @@ const getCachedIsUserGlobalAdmin = cache(async (): Promise<boolean> => {
     }
 
     const cookieStore = await cookies();
-    return cookieStore.get('adminToken')?.value === process.env.ADMIN_PASSWORD;
+    const adminToken = cookieStore.get('adminToken')?.value;
+    return adminToken !== undefined && isAdminPasswordEqual(adminToken);
 });
 
 /**

package/apps/agents-server/src/utils/knowledge/createInlineKnowledgeSourceUploader.ts

@@ -1,8 +1,15 @@
-import { $provideCdnForServer } from '@/src/tools/$provideCdnForServer';
+import {
+    $provideCdnForServer,
+    isSelfContainedS3StorageSelected,
+    resolveCdnPublicUrlForServer,
+} from '@/src/tools/$provideCdnForServer';
+import { $provideServer } from '@/src/tools/$provideServer';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
 import { InlineKnowledgeSourceUploader } from '../../../../../src/utils/knowledge/inlineKnowledgeSource';
 import type { string_knowledge_source_link } from '../../../../../src/types/typeAliases';
 import { getSafeCdnPath } from '../cdn/utils/getSafeCdnPath';
 import { getUserFileCdnKey } from '../cdn/utils/getUserFileCdnKey';
+import { resolveFileUploadAvailability } from '../upload/fileUploadAvailability';
 
 /**
  * Options for create inline knowledge uploader.
@@ -23,18 +30,30 @@ const uploadCache = new Map<string, Promise<string_knowledge_source_link>>();
 export function createInlineKnowledgeSourceUploader(
     options: CreateInlineKnowledgeUploaderOptions = {},
 ): InlineKnowledgeSourceUploader {
-    const cdn = $provideCdnForServer();
     const { purpose = 'KNOWLEDGE', userId } = options;
 
     return async (source) => {
+        const providedServer = await $provideServer();
+        const fileUploadAvailability = resolveFileUploadAvailability({
+            serverId: providedServer.id,
+            serverPublicUrl: providedServer.publicUrl,
+            isSelfContainedS3StorageSelected: isSelfContainedS3StorageSelected(),
+        });
+        if (!fileUploadAvailability.isUploadAvailable) {
+            throw new NotAllowed(fileUploadAvailability.message || 'File uploads are not available for this server.');
+        }
+
+        const cdnPublicUrl = resolveCdnPublicUrlForServer(providedServer.publicUrl);
+        const cdn = $provideCdnForServer({ cdnPublicUrl });
         const rawKey = getUserFileCdnKey(source.buffer, source.filename);
         const safeKey = getSafeCdnPath({
             pathname: rawKey,
             pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX,
         });
+        const uploadCacheKey = `${providedServer.tablePrefix}:${cdnPublicUrl.href}:${safeKey}`;
 
-        if (uploadCache.has(safeKey)) {
-            return uploadCache.get(safeKey)!;
+        if (uploadCache.has(uploadCacheKey)) {
+            return uploadCache.get(uploadCacheKey)!;
         }
 
         const promise: Promise<string_knowledge_source_link> = (async () => {
@@ -48,7 +67,7 @@ export function createInlineKnowledgeSourceUploader(
             return cdn.getItemUrl(safeKey).href;
         })();
 
-        uploadCache.set(safeKey, promise);
+        uploadCache.set(uploadCacheKey, promise);
         return promise;
     };
 }

package/apps/agents-server/src/utils/knowledge/resolveWebsiteKnowledgeSourcesForServer.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import type { string_knowledge_source_link } from '../../../../../src/types/typeAliases';
 import { $provideFilesystemForNode } from '../../../../../src/scrapers/_common/register/$provideFilesystemForNode';
 import type { ScraperSourceHandler } from '../../../../../src/scrapers/_common/Scraper';
@@ -121,7 +122,15 @@ export async function resolveWebsiteKnowledgeSourcesForServer(
                 continue;
             }
 
-            const inlineSource = createInlineKnowledgeSourceFile(`Source URL: ${source}\n\n${markdown}`);
+            const inlineSource = createInlineKnowledgeSourceFile(
+                spaceTrim(
+                    (block) => `
+                        Source URL: ${source}
+
+                        ${block(markdown)}
+                    `,
+                ),
+            );
             const uploadedSource = await uploadInlineKnowledgeSource(inlineSource);
             resolvedKnowledgeSources.push(uploadedSource);
         } catch (error) {

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';
@@ -8,6 +9,7 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
+import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
@@ -145,13 +147,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();
@@ -178,6 +189,10 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'local',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 
@@ -213,7 +228,7 @@ async function synchronizeLocalUserChatJob(
     }
 
     const failedFileContent = await readOptionalTextFile(join(agentDirectoryPath, metadata.failedPath));
-    if (failedFileContent !== null) {
+    if (failedFileContent !== null && job.status !== 'FAILED') {
         const failureReason = parseLocalChatFailedMessageBook({
             bookContent: failedFileContent,
             expectedMessagesBeforeAnswer: metadata.expectedMessagesBeforeAnswer,

package/apps/agents-server/src/utils/localization/formatServerLanguageHumanReadableDate.ts

@@ -0,0 +1,70 @@
+import moment from 'moment';
+import type { ServerLanguageCode } from '../../languages/ServerLanguageRegistry';
+import { createServerLanguageMoment } from './createServerLanguageMoment';
+
+/**
+ * Default fallback for missing date values.
+ *
+ * @private internal constant of `formatServerLanguageHumanReadableDate`
+ */
+const DEFAULT_FALLBACK_LABEL = 'N/A';
+
+/**
+ * Default localized exact-date format appended when requested.
+ *
+ * @private internal constant of `formatServerLanguageHumanReadableDate`
+ */
+const DEFAULT_EXACT_DATE_FORMAT = 'L LT';
+
+/**
+ * Options for localized human-readable date formatting.
+ *
+ * @private internal type of `formatServerLanguageHumanReadableDate`
+ */
+type FormatServerLanguageHumanReadableDateOptions = {
+    /**
+     * Text returned when the date value is empty.
+     */
+    readonly fallbackLabel?: string;
+
+    /**
+     * Whether to append the localized exact timestamp after the relative label.
+     */
+    readonly isExactDateIncluded?: boolean;
+};
+
+/**
+ * Formats one timestamp for the active Agents Server language.
+ *
+ * @param value - Date-like value, usually an ISO timestamp from the database.
+ * @param language - Active Agents Server language code.
+ * @param options - Formatting options.
+ * @returns Localized relative date label, with optional exact timestamp.
+ * @private internal utility for Agents Server UI.
+ */
+export function formatServerLanguageHumanReadableDate(
+    value: moment.MomentInput | null | undefined,
+    language: ServerLanguageCode,
+    options: FormatServerLanguageHumanReadableDateOptions = {},
+): string {
+    const fallbackLabel = options.fallbackLabel ?? DEFAULT_FALLBACK_LABEL;
+
+    if (value === null || value === undefined || value === '') {
+        return fallbackLabel;
+    }
+
+    const localizedMoment =
+        typeof value === 'string'
+            ? moment(value, moment.ISO_8601, true).locale(language)
+            : createServerLanguageMoment(value, language);
+    if (!localizedMoment.isValid()) {
+        return typeof value === 'string' ? value : fallbackLabel;
+    }
+
+    const relativeLabel = localizedMoment.fromNow();
+    if (!options.isExactDateIncluded) {
+        return relativeLabel;
+    }
+
+    return `${relativeLabel} (${localizedMoment.format(DEFAULT_EXACT_DATE_FORMAT)})`;
+}