@promptbook/cli 0.112.0-99 → 0.113.0-0

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

@@ -23,10 +23,11 @@ export function createLocalUserChatJobMetadata(options: {
     agentDirectoryName: string;
     threadId: string;
     threadCreatedAt: string;
+    jobId: string;
     queuedAt: string;
     expectedMessagesBeforeAnswer: number;
 }): LocalUserChatJobMetadata {
-    const fileName = createLocalChatMessageFileName(options.threadId, options.threadCreatedAt);
+    const fileName = createLocalChatMessageFileName(options.threadId, options.threadCreatedAt, options.jobId);
 
     return {
         version: 1,
@@ -102,15 +103,24 @@ export function withoutLocalUserChatJobMetadata(parameters: UserChatJobParameter
 /**
  * Creates the filename used by one local message-thread book.
  */
-export function createLocalChatMessageFileName(threadId: string, threadCreatedAt: string): string {
+export function createLocalChatMessageFileName(threadId: string, threadCreatedAt: string, jobId?: string): string {
     const createdOnDate = resolveLocalChatThreadCreatedOnDate(threadCreatedAt);
-    const normalizedThreadId = threadId.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    const normalizedThreadId = threadId
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const normalizedJobId = jobId
+        ?.trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
 
     if (normalizedThreadId.length > 0) {
-        return `${createdOnDate}-${normalizedThreadId}.book`;
+        return `${createdOnDate}-${normalizedThreadId}${normalizedJobId ? `-${normalizedJobId}` : ''}.book`;
     }
 
-    return `${createdOnDate}-${Buffer.from(threadId, 'utf8').toString('hex') || 'thread'}.book`;
+    return `${createdOnDate}-${Buffer.from(threadId, 'utf8').toString('hex') || 'thread'}${
+        normalizedJobId ? `-${normalizedJobId}` : ''
+    }.book`;
 }
 
 /**

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,10 +9,11 @@ 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';
-import { resolvePromptThreadBeforeUserMessage } from '../userChat/userChatMessageLifecycle';
+import { createUserChatRunnerThreadMessages } from '../userChat/userChatMessageLifecycle';
 import {
     createLocalUserChatJobMetadata,
     getLocalUserChatJobMetadata,
@@ -83,9 +85,11 @@ export async function processLocalUserChatJob(job: UserChatJobRecord): Promise<P
 /**
  * Processes the next local user chat job waiting for worker attention.
  */
-export async function processNextLocalUserChatJob(options: {
-    preferredJobId?: string;
-} = {}): Promise<ProcessLocalUserChatJobResult | null> {
+export async function processNextLocalUserChatJob(
+    options: {
+        preferredJobId?: string;
+    } = {},
+): Promise<ProcessLocalUserChatJobResult | null> {
     if (options.preferredJobId) {
         const claimedPreferredJob = await claimNextQueuedUserChatJob({ preferredJobId: options.preferredJobId });
         if (claimedPreferredJob) {
@@ -140,18 +144,11 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         throw new Error(`User message "${job.userMessageId}" was not found in chat "${job.chatId}".`);
     }
 
-    const previousThreadMessages = resolvePromptThreadBeforeUserMessage(chat.messages, job.userMessageId);
-    if (previousThreadMessages.some((message) => message.sender === 'AGENT' && message.isComplete === false)) {
-        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 threadMessages = createUserChatRunnerThreadMessages({
+        messages: chat.messages,
+        userMessageId: job.userMessageId,
+        resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,
+    });
 
     const agentFolder = await ensureLocalAgentFolder(agentSourceSnapshot);
     const queuedAt = new Date().toISOString();
@@ -159,6 +156,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         agentDirectoryName: agentFolder.directoryName,
         threadId: chat.id,
         threadCreatedAt: chat.createdAt,
+        jobId: job.id,
         queuedAt,
         expectedMessagesBeforeAnswer: threadMessages.length,
     });
@@ -178,6 +176,10 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
+            progressCard: createUserChatRunnerProgressCard({
+                runnerKind: 'local',
+                phase: 'queued_for_runner',
+            }),
         }),
     });
 
@@ -213,7 +215,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,
@@ -311,7 +313,11 @@ async function handleLocalUserChatJobProcessingError(
     const metadata = getLocalUserChatJobMetadata(job);
     const failureReason = error instanceof Error ? error.message : 'Local agent runner synchronization failed.';
 
-    if (job.status === 'QUEUED' || (job.status === 'RUNNING' && !metadata) || (metadata && isLocalUserChatJobTimedOut(metadata))) {
+    if (
+        job.status === 'QUEUED' ||
+        (job.status === 'RUNNING' && !metadata) ||
+        (metadata && isLocalUserChatJobTimedOut(metadata))
+    ) {
         await persistUserChatJobTerminalState({
             job,
             status: 'FAILED',

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)})`;
+}

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

@@ -0,0 +1,32 @@
+import { cookies } from 'next/headers';
+import { getMetadataMap } from '../../database/getMetadata';
+import {
+    IS_SERVER_LANGUAGE_ENFORCED_METADATA_KEY,
+    parseServerLanguageEnforcedMetadata,
+    resolveServerLanguageCode,
+    SERVER_LANGUAGE_COOKIE_NAME,
+    SERVER_LANGUAGE_METADATA_KEY,
+    type ServerLanguageCode,
+} from '../../languages/ServerLanguageRegistry';
+
+/**
+ * Resolves the active Agents Server UI language for the current server-rendered request.
+ *
+ * @returns Active server language code derived from metadata and the language override cookie.
+ * @private internal utility for server-rendered Agents Server UI.
+ */
+export async function getRequestServerLanguage(): Promise<ServerLanguageCode> {
+    const [metadata, cookieStore] = await Promise.all([
+        getMetadataMap([SERVER_LANGUAGE_METADATA_KEY, IS_SERVER_LANGUAGE_ENFORCED_METADATA_KEY]),
+        cookies(),
+    ]);
+
+    const cookieLanguage = cookieStore.get(SERVER_LANGUAGE_COOKIE_NAME)?.value || null;
+    const rawServerLanguage = metadata[SERVER_LANGUAGE_METADATA_KEY];
+    const isServerLanguageEnforced = parseServerLanguageEnforcedMetadata(
+        metadata[IS_SERVER_LANGUAGE_ENFORCED_METADATA_KEY],
+    );
+    const preferredLanguageSource = isServerLanguageEnforced ? rawServerLanguage : cookieLanguage || rawServerLanguage;
+
+    return resolveServerLanguageCode(preferredLanguageSource);
+}