@promptbook/cli 0.114.0-0 → 0.114.0-10

package/apps/agents-server/src/utils/agentProjects/readAgentProjectRootTextFile.ts

@@ -0,0 +1,73 @@
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * Text file loaded from the root of one agent project.
+ */
+export type AgentProjectRootTextFile = {
+    /**
+     * Original filename used on disk.
+     */
+    readonly fileName: string;
+
+    /**
+     * File content decoded as UTF-8 text.
+     */
+    readonly content: string;
+};
+
+/**
+ * Reads the first recognized text file from the root of one project directory.
+ *
+ * Project files are written by the agent, so their filename casing cannot be relied on — the
+ * recognized filenames are matched case-insensitively and the real filename on disk is preserved.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @param recognizedFileNames - Lowercase filenames ordered by priority.
+ * @returns Content of the first matching file, or `null` when the project has none of them.
+ */
+export async function readAgentProjectRootTextFile(
+    projectPath: string,
+    recognizedFileNames: ReadonlyArray<string>,
+): Promise<AgentProjectRootTextFile | null> {
+    let projectRootEntries;
+
+    try {
+        projectRootEntries = await readdir(projectPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+
+    const projectFileNameByNormalizedName = new Map(
+        projectRootEntries
+            .filter((projectRootEntry) => projectRootEntry.isFile())
+            .map((projectRootEntry) => [projectRootEntry.name.toLowerCase(), projectRootEntry.name]),
+    );
+
+    for (const recognizedFileName of recognizedFileNames) {
+        const projectFileName = projectFileNameByNormalizedName.get(recognizedFileName.toLowerCase());
+        if (!projectFileName) {
+            continue;
+        }
+
+        try {
+            return {
+                fileName: projectFileName,
+                content: await readFile(join(projectPath, projectFileName), 'utf-8'),
+            };
+        } catch (error) {
+            if (isMissingPathError(error)) {
+                return null;
+            }
+
+            throw error;
+        }
+    }
+
+    return null;
+}

package/apps/agents-server/src/utils/agentProjects/resolveAgentProjectFaviconRelativePath.ts

@@ -0,0 +1,108 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+import { AGENT_PROJECT_CONVENTIONAL_FAVICON_RELATIVE_PATHS } from './agentProjectFileNames';
+import { isSafeAgentProjectPathSegment } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+import { resolveAgentProjectFileContentType } from './resolveAgentProjectFileContentType';
+
+/**
+ * Matches an icon reference which is not served from the project folder itself,
+ * for example `https://example.com/favicon.ico`, `//example.com/favicon.ico` or a `data:` URI.
+ */
+const EXTERNAL_ICON_HREF_REGEX = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/**
+ * Content type prefix every usable project icon file must have.
+ */
+const ICON_CONTENT_TYPE_PREFIX = 'image/';
+
+/**
+ * Resolves the icon of one project as a path relative to the project root.
+ *
+ * The icon linked by the project `index.html` wins, the conventional favicon locations are searched
+ * afterwards. Only files which really exist inside the project folder are returned, so the resolved
+ * path can always be served through the project file route.
+ *
+ * @param options - Project directory and the icon href linked by its `index.html`.
+ * @returns Project-relative icon path using `/` separators, or `null` when the project has no icon.
+ */
+export async function resolveAgentProjectFaviconRelativePath(options: {
+    readonly projectPath: string;
+    readonly indexHtmlFaviconHref: string | null;
+}): Promise<string | null> {
+    const linkedFaviconRelativePath = resolveLocalIconRelativePath(options.indexHtmlFaviconHref);
+    const faviconRelativePathCandidates = [
+        ...(linkedFaviconRelativePath === null ? [] : [linkedFaviconRelativePath]),
+        ...AGENT_PROJECT_CONVENTIONAL_FAVICON_RELATIVE_PATHS,
+    ];
+
+    for (const faviconRelativePathCandidate of faviconRelativePathCandidates) {
+        if (await isExistingProjectIconFile(options.projectPath, faviconRelativePathCandidate)) {
+            return faviconRelativePathCandidate;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Normalizes one icon href written in a project `index.html` into a project-relative path.
+ *
+ * The href is written by the agent and therefore untrusted — an icon hosted outside of the project
+ * folder and any path escaping the project root are refused instead of being reported as an error.
+ *
+ * @param iconHref - Icon href exactly as written in the document.
+ * @returns Project-relative icon path using `/` separators, or `null` when the href is not usable.
+ */
+function resolveLocalIconRelativePath(iconHref: string | null): string | null {
+    const trimmedIconHref = (iconHref || '').trim();
+
+    if (!trimmedIconHref || EXTERNAL_ICON_HREF_REGEX.test(trimmedIconHref)) {
+        return null;
+    }
+
+    const iconPath = trimmedIconHref.split(/[?#]/u)[0] || '';
+    let iconPathSegments: ReadonlyArray<string>;
+
+    try {
+        iconPathSegments = iconPath
+            .split('/')
+            .filter((iconPathSegment) => iconPathSegment !== '' && iconPathSegment !== '.')
+            .map((iconPathSegment) => decodeURIComponent(iconPathSegment));
+    } catch {
+        return null;
+    }
+
+    if (iconPathSegments.length === 0 || !iconPathSegments.every(isSafeAgentProjectPathSegment)) {
+        return null;
+    }
+
+    return iconPathSegments.join('/');
+}
+
+/**
+ * Returns whether one project-relative path points to an image file inside the project.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @param iconRelativePath - Project-relative icon path using `/` separators.
+ * @returns `true` when the path is an existing image file.
+ */
+async function isExistingProjectIconFile(projectPath: string, iconRelativePath: string): Promise<boolean> {
+    const iconPathSegments = iconRelativePath.split('/');
+    const iconFileName = iconPathSegments[iconPathSegments.length - 1] || '';
+
+    if (!resolveAgentProjectFileContentType(iconFileName).startsWith(ICON_CONTENT_TYPE_PREFIX)) {
+        return false;
+    }
+
+    try {
+        const iconStats = await stat(join(projectPath, ...iconPathSegments));
+        return iconStats.isFile();
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return false;
+        }
+
+        throw error;
+    }
+}

package/apps/agents-server/src/utils/agentProjects/resolveAgentProjectInfo.ts

@@ -5,8 +5,10 @@ import type { AgentProjectInfo } from './AgentProjectInfo';
 import { resolveAgentProjectsRootPath, resolveSafeAgentProjectPath } from './agentProjectsPaths';
 import { isMissingPathError } from './isMissingPathError';
 import { measureDirectoryUsage } from './measureDirectoryUsage';
+import { readAgentProjectIndexHtmlProfile } from './readAgentProjectIndexHtmlProfile';
 import { readAgentProjectReadme } from './readAgentProjectReadme';
-import { resolveAgentProjectReadmeProfile } from './resolveAgentProjectReadmeProfile';
+import { resolveAgentProjectFaviconRelativePath } from './resolveAgentProjectFaviconRelativePath';
+import { resolveAgentProjectProfile } from './resolveAgentProjectProfile';
 
 /**
  * Builds metadata for one project directory.
@@ -20,14 +22,20 @@ export async function createAgentProjectInfo(
     projectDirectoryName: string,
 ): Promise<AgentProjectInfo> {
     const projectPath = join(projectsRootPath, projectDirectoryName);
-    const [projectUsage, isGitRepository, readme] = await Promise.all([
+    const [projectUsage, isGitRepository, readme, indexHtmlProfile] = await Promise.all([
         measureDirectoryUsage(projectPath),
         isGitRepositoryDirectory(projectPath),
         readAgentProjectReadme(projectPath),
+        readAgentProjectIndexHtmlProfile(projectPath),
     ]);
-    const profile = resolveAgentProjectReadmeProfile({
+    const profile = resolveAgentProjectProfile({
         projectDirectoryName,
         readme,
+        indexHtmlTitle: indexHtmlProfile?.title ?? null,
+    });
+    const faviconRelativePath = await resolveAgentProjectFaviconRelativePath({
+        projectPath,
+        indexHtmlFaviconHref: indexHtmlProfile?.faviconHref ?? null,
     });
 
     return {
@@ -35,6 +43,7 @@ export async function createAgentProjectInfo(
         displayName: profile.displayName,
         description: profile.description,
         readmeFileName: profile.readmeFileName,
+        faviconRelativePath,
         relativePath: `${AGENT_PROJECTS_DIRECTORY_PATH}/${projectDirectoryName}`,
         absolutePath: projectPath,
         sizeBytes: projectUsage.sizeBytes,

package/apps/agents-server/src/utils/agentProjects/{resolveAgentProjectReadmeProfile.ts → resolveAgentProjectProfile.ts}

@@ -1,6 +1,7 @@
 import { parseMarkdownSection, splitMarkdownIntoSections } from '@promptbook-local/markdown-utils';
 import type { string_markdown } from '@promptbook-local/types';
 import { stripMarkdownText } from '../stripMarkdownText';
+import { humanizeAgentProjectName } from './humanizeAgentProjectName';
 import type { AgentProjectReadme } from './readAgentProjectReadme';
 
 /**
@@ -29,9 +30,9 @@ type AgentProjectReadmeSections = {
 };
 
 /**
- * Project profile values resolved from a project folder and optional README.
+ * Project profile values resolved from a project folder, its README and its `index.html`.
  */
-export type AgentProjectReadmeProfile = {
+export type AgentProjectProfile = {
     /**
      * User-facing project name.
      */
@@ -49,35 +50,30 @@ export type AgentProjectReadmeProfile = {
 };
 
 /**
- * Resolves display metadata for one agent project from its README.
+ * Resolves display metadata for one agent project.
  *
- * @param options - Project folder name and optional README content.
+ * @param options - Project folder name, optional README content and optional `index.html` title.
  * @returns Project display profile.
  */
-export function resolveAgentProjectReadmeProfile(options: {
+export function resolveAgentProjectProfile(options: {
     readonly projectDirectoryName: string;
     readonly readme: AgentProjectReadme | null;
-}): AgentProjectReadmeProfile {
-    const { projectDirectoryName, readme } = options;
-    if (!readme) {
-        return {
-            displayName: projectDirectoryName,
-            description: '',
-            readmeFileName: null,
-        };
-    }
-
-    const sections = parseMarkdownProfileSections(readme.content);
-    const displayName = resolveProjectDisplayName(
-        projectDirectoryName,
-        sections.firstExplicitHeadingSection?.title ?? null,
-    );
-    const description = resolveProjectDescription(readme.content, sections.firstSection?.content ?? readme.content);
+    readonly indexHtmlTitle: string | null;
+}): AgentProjectProfile {
+    const { projectDirectoryName, readme, indexHtmlTitle } = options;
+    const sections = readme === null ? null : parseMarkdownProfileSections(readme.content);
 
     return {
-        displayName,
-        description,
-        readmeFileName: readme.fileName,
+        displayName: resolveProjectDisplayName({
+            projectDirectoryName,
+            readmeHeadingTitle: sections?.firstExplicitHeadingSection?.title ?? null,
+            indexHtmlTitle,
+        }),
+        description:
+            readme === null
+                ? ''
+                : resolveProjectDescription(readme.content, sections?.firstSection?.content ?? readme.content),
+        readmeFileName: readme?.fileName ?? null,
     };
 }
 
@@ -112,19 +108,23 @@ function parseMarkdownProfileSections(markdown: string): AgentProjectReadmeSecti
 }
 
 /**
- * Resolves a project display name from the README heading or folder fallback.
+ * Resolves a project display name from the README heading, the `index.html` title or the folder name.
+ *
+ * A project which describes itself neither in a README nor in an `index.html` still gets a readable
+ * name, because its folder name is humanized — `prague-murders-map` reads as `Prague Murders Map`.
  *
- * @param projectDirectoryName - Project folder name.
- * @param parsedHeadingTitle - Title returned by the markdown section parser.
+ * @param options - Project folder name and the titles found in the project files.
  * @returns Display name.
  */
-function resolveProjectDisplayName(projectDirectoryName: string, parsedHeadingTitle: string | null): string {
-    if (!parsedHeadingTitle) {
-        return projectDirectoryName;
-    }
+function resolveProjectDisplayName(options: {
+    readonly projectDirectoryName: string;
+    readonly readmeHeadingTitle: string | null;
+    readonly indexHtmlTitle: string | null;
+}): string {
+    const readmeDisplayName = options.readmeHeadingTitle === null ? '' : stripMarkdownText(options.readmeHeadingTitle);
+    const indexHtmlDisplayName = (options.indexHtmlTitle || '').trim();
 
-    const displayName = stripMarkdownText(parsedHeadingTitle);
-    return displayName || projectDirectoryName;
+    return readmeDisplayName || indexHtmlDisplayName || humanizeAgentProjectName(options.projectDirectoryName);
 }
 
 /**

package/apps/agents-server/src/utils/agentProjects/resolveAgentProjectPublicUrls.ts

@@ -0,0 +1,34 @@
+import { listAgentProjectDomainRecords, resolveAgentProjectRuntimeBaseDomain } from './agentProjectRuntimeDomains';
+import { resolveCurrentAgentProjectServerDomain } from './resolveCurrentAgentProjectServerDomain';
+
+/**
+ * Resolves the stable public URLs of the projects of one agent.
+ *
+ * The public URL of one project comes from its persisted domain assignment, so it stays the same
+ * whether the project runtime is running or stopped.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the projects.
+ * @returns Public project URLs keyed by lowercase project name.
+ */
+export async function resolveAgentProjectPublicUrls(agentPermanentId: string): Promise<ReadonlyMap<string, string>> {
+    const [projectDomainRecords, currentServerDomain] = await Promise.all([
+        listAgentProjectDomainRecords(),
+        resolveCurrentAgentProjectServerDomain(),
+    ]);
+    const serverDomain = resolveAgentProjectRuntimeBaseDomain(currentServerDomain);
+    const publicUrlByProjectName = new Map<string, string>();
+
+    for (const projectDomainRecord of projectDomainRecords) {
+        if (projectDomainRecord.agentPermanentId.toLowerCase() !== agentPermanentId.toLowerCase()) {
+            continue;
+        }
+
+        if (serverDomain && resolveAgentProjectRuntimeBaseDomain(projectDomainRecord.serverDomain) !== serverDomain) {
+            continue;
+        }
+
+        publicUrlByProjectName.set(projectDomainRecord.projectName.toLowerCase(), projectDomainRecord.publicUrl);
+    }
+
+    return publicUrlByProjectName;
+}

package/apps/agents-server/src/utils/bookLanguageDocumentation/createBookLanguageDocumentationPdfResponse.ts

@@ -81,23 +81,25 @@ export function createBookLanguageDocumentationPdfHtml(
     const branding = getPromptbookExportBranding();
     const documentHtml = groupHtmlHeadingSections(highlightBookCodeBlocksInHtml(renderMarkdown(markdown)));
 
-    return `<!doctype html>
-<html lang="${escapeHtml(language)}">
-<head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    ${createPromptbookBrandingMetaTags(branding)}
-    <title>${escapeHtml(branding.productName)} - Book Language Manual</title>
-    <style>${createBookLanguageDocumentationPdfStyles()}</style>
-</head>
-<body>
-    <main>
-        ${createPromptbookBrandingHeader(branding, logoDataUrl)}
-        ${documentHtml}
-        ${createPromptbookBrandingFooter(branding)}
-    </main>
-</body>
-</html>`;
+    return spaceTrim(
+        (block) => `<!doctype html>
+    <html lang="${block(escapeHtml(language))}">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        ${block(createPromptbookBrandingMetaTags(branding))}
+        <title>${block(escapeHtml(branding.productName))} - Book Language Manual</title>
+        <style>${block(createBookLanguageDocumentationPdfStyles())}</style>
+    </head>
+    <body>
+        <main>
+            ${block(createPromptbookBrandingHeader(branding, logoDataUrl))}
+            ${block(documentHtml)}
+            ${block(createPromptbookBrandingFooter(branding))}
+        </main>
+    </body>
+    </html>`,
+    );
 }
 
 /**

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

@@ -72,6 +72,15 @@ export type AdminChatTaskRecord = {
     workerId: string | null;
     queueName: string | null;
 
+    /**
+     * True when the task runs in the agent's own goal chat instead of a chat started by a user.
+     *
+     * Goal-chat tasks keep their normal kind (they really are chat completions / chat timeouts) and
+     * are only flagged, so they stay in the regular task streams while remaining distinguishable
+     * from user-invoked work.
+     */
+    isAgentGoalTask?: boolean;
+
     /**
      * Registered server this task belongs to, when the source task is bound to one server or the
      * VPS-wide superadmin aggregation adds the owning server.

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

@@ -1,5 +1,6 @@
 import type { AgentBasicInformation, AgentCollection, string_book } from '@promptbook-local/types';
 import type { CreateAgentInput } from '../../../../src/collection/agent-collection/CreateAgentInput';
+import { recordAgentGoalChatLifecycleNote } from './agentGoalChat/recordAgentGoalChatLifecycleNote';
 import { assignAgentOwner } from './agentOwnership';
 import { parseAgentSourceVisibility } from './agentVisibility';
 import { getDefaultAgentVisibility } from './getDefaultAgentVisibility';
@@ -40,5 +41,12 @@ export async function createAgentWithDefaultVisibility(
         await assignAgentOwner(createdAgent.permanentId, userId);
     }
 
+    await recordAgentGoalChatLifecycleNote({
+        event: 'CREATED',
+        agentPermanentId: createdAgent.permanentId,
+        agentName: createdAgent.agentName,
+        agentSource,
+    });
+
     return createdAgent;
 }

package/apps/agents-server/src/utils/dnsRecords/DnsRecordInstruction.ts

@@ -31,3 +31,23 @@ export type DnsRecordInstruction = {
      */
     readonly note: string | null;
 };
+
+/**
+ * DNS records which belong together and share one all-or-one configuration rule.
+ *
+ * One DNS manual can show more groups at once, for example the server domain records, the generated project domain
+ * records, and the email records of one Agents Server.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordGroup = {
+    /**
+     * Whether every record of the group or just one of its alternatives must be configured.
+     */
+    readonly recordSelection: DnsRecordSelection;
+
+    /**
+     * DNS records of the group.
+     */
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+};

package/apps/agents-server/src/utils/dnsRecords/DnsRecordsSection.ts

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react';
+import type { DnsRecordGroup } from './DnsRecordInstruction';
+
+/**
+ * One alternative setup of a DNS record section.
+ *
+ * A section with a single variant has nothing to choose from, a section with more variants lets the administrator
+ * pick exactly one of them, for example the wildcard or the single-project setup of generated project domains.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordsSectionVariant = DnsRecordGroup & {
+    /**
+     * Stable identifier of the variant, unique within its section.
+     */
+    readonly id: string;
+
+    /**
+     * Label of the variant button.
+     */
+    readonly label: string;
+
+    /**
+     * Explanation of what the selected variant covers.
+     */
+    readonly description?: ReactNode;
+};
+
+/**
+ * One part of the DNS setup of an Agents Server, for example its domain, its projects, or its email.
+ *
+ * Every page shows the same sections in the same shared component, just filtered down to the sections which are
+ * relevant for that page.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordsSection = {
+    /**
+     * Stable identifier of the section, unique within one DNS manual.
+     */
+    readonly id: string;
+
+    /**
+     * Human-readable name of the configured part, for example `Email`.
+     */
+    readonly title: string;
+
+    /**
+     * Explanation of what the section configures.
+     */
+    readonly description?: ReactNode;
+
+    /**
+     * Label shown above the variant buttons.
+     */
+    readonly variantsLabel?: string;
+
+    /**
+     * Alternative setups of the section, at least one of them.
+     */
+    readonly variants: ReadonlyArray<DnsRecordsSectionVariant>;
+
+    /**
+     * Current DNS verification state of the section, when it is known.
+     */
+    readonly statusSummary?: string | null;
+
+    /**
+     * Addresses currently returned by public DNS, when verification is available.
+     */
+    readonly resolvedAddresses?: ReadonlyArray<string>;
+
+    /**
+     * Whether the section currently needs attention.
+     */
+    readonly isDnsIssue?: boolean;
+};

package/apps/agents-server/src/utils/dnsRecords/createServerDnsRecordsSections.ts

@@ -0,0 +1,58 @@
+import type { ManagedServerDnsDiagnostic } from '../../app/superadmin/servers/ServersRegistryDnsTypes';
+import { createAgentProjectsDnsRecordsSection } from '../agentProjects/createAgentProjectsDnsRecordsSection';
+import { createEmailDnsRecordsSection } from '../stalwart/createEmailDnsRecordsSection';
+import type { DnsRecordsSection } from './DnsRecordsSection';
+import { createServerDomainDnsRecordsSection } from './createServerDomainDnsRecordsSection';
+
+/**
+ * Creates every DNS section which one Agents Server needs to be fully configured.
+ *
+ * This is the single source of truth of the complete DNS setup of one server, so that `/superadmin/servers` can show
+ * the server domain, the generated project domains, and the email records in one manual and one Cloudflare wizard.
+ *
+ * @param options - Server domain, its DNS diagnostic, and the generated project domain state.
+ * @returns All DNS sections of one server.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createServerDnsRecordsSections(options: {
+    /**
+     * Public domain of the Agents Server.
+     */
+    readonly serverDomain: string;
+
+    /**
+     * DNS verification details of the server domain, when the deployment provides them.
+     */
+    readonly dnsDiagnostic: ManagedServerDnsDiagnostic | null | undefined;
+
+    /**
+     * Whether at least one generated project domain currently fails DNS verification.
+     */
+    readonly isProjectDnsIssue?: boolean;
+
+    /**
+     * Example generated project domain, when one is already assigned.
+     */
+    readonly projectDomain?: string | null;
+}): ReadonlyArray<DnsRecordsSection> {
+    const publicIpAddress = options.dnsDiagnostic?.publicIpAddress ?? null;
+    const serverDomainSection = createServerDomainDnsRecordsSection({
+        serverDomain: options.serverDomain,
+        dnsDiagnostic: options.dnsDiagnostic,
+    });
+
+    return [
+        ...(serverDomainSection ? [serverDomainSection] : []),
+        createAgentProjectsDnsRecordsSection({
+            isDnsIssue: options.isProjectDnsIssue,
+            projectDomain: options.projectDomain,
+            publicIpAddress,
+            serverDomain: options.serverDomain,
+        }),
+        createEmailDnsRecordsSection({
+            domain: options.serverDomain,
+            publicIpAddress,
+        }),
+    ];
+}

package/apps/agents-server/src/utils/dnsRecords/createServerDomainDnsRecordsSection.ts

@@ -0,0 +1,48 @@
+import {
+    isManagedServerDnsDiagnosticIssue,
+    type ManagedServerDnsDiagnostic,
+} from '../../app/superadmin/servers/ServersRegistryDnsTypes';
+import type { DnsRecordsSection } from './DnsRecordsSection';
+
+/**
+ * Creates the DNS section which makes the Agents Server itself reachable on its own domain.
+ *
+ * @param options - Server domain and its DNS diagnostic.
+ * @returns Server domain section, or `null` when the deployment does not verify server domains.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createServerDomainDnsRecordsSection(options: {
+    /**
+     * Public domain of the Agents Server.
+     */
+    readonly serverDomain: string;
+
+    /**
+     * DNS verification details of the server domain, when the deployment provides them.
+     */
+    readonly dnsDiagnostic: ManagedServerDnsDiagnostic | null | undefined;
+}): DnsRecordsSection | null {
+    const { dnsDiagnostic, serverDomain } = options;
+
+    if (!dnsDiagnostic || dnsDiagnostic.expectedRecords.length === 0) {
+        return null;
+    }
+
+    return {
+        id: 'server-domain',
+        title: `Server domain ${serverDomain}`,
+        description: `Makes the Agents Server reachable on ${serverDomain} and lets it issue its HTTPS certificate.`,
+        variants: [
+            {
+                id: 'server-domain',
+                label: 'Server domain',
+                recordSelection: 'one',
+                records: dnsDiagnostic.expectedRecords,
+            },
+        ],
+        statusSummary: dnsDiagnostic.summary,
+        resolvedAddresses: dnsDiagnostic.resolvedAddresses,
+        isDnsIssue: isManagedServerDnsDiagnosticIssue(dnsDiagnostic),
+    };
+}