@promptbook/cli 0.113.0-8 → 0.114.0-0

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

@@ -0,0 +1,117 @@
+/**
+ * Options of one page-preview frame pump.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewFramePumpOptions = {
+    /**
+     * Minimum milliseconds between two written frames (caps the stream frame rate).
+     */
+    readonly minimumFrameIntervalMs: number;
+
+    /**
+     * Milliseconds of inactivity after which the latest frame is re-sent to keep the
+     * multipart connection alive across proxies.
+     */
+    readonly heartbeatIntervalMs: number;
+
+    /**
+     * Writes one JPEG frame into the multipart stream.
+     */
+    readonly writeFrame: (frame: Buffer) => void;
+};
+
+/**
+ * Pacing gate between a push-based frame source (CDP screencast) and the multipart stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewFramePump = {
+    /**
+     * Offers one fresh frame; it is written immediately, or replaces the pending frame
+     * when the stream is already at its frame-rate cap.
+     */
+    readonly pushFrame: (frame: Buffer) => void;
+
+    /**
+     * Stops the pump, its scheduled writes, and its heartbeat.
+     */
+    readonly stop: () => void;
+};
+
+/**
+ * Creates a pacing gate that caps the stream frame rate and keeps idle streams alive.
+ *
+ * A push-based source (CDP screencast) can deliver frames faster than the preview needs;
+ * excess frames are dropped in favor of the latest one. When the source goes quiet
+ * (static page), the latest frame is re-sent as a heartbeat.
+ *
+ * @param options - Pump options.
+ * @returns Running frame pump.
+ *
+ * @private internal utility of Agents Server page-preview streaming
+ */
+export function createPagePreviewFramePump(options: PagePreviewFramePumpOptions): PagePreviewFramePump {
+    let latestWrittenFrame: Buffer | null = null;
+    let pendingFrame: Buffer | null = null;
+    let lastWriteAtMs = 0;
+    let scheduledWriteTimeout: NodeJS.Timeout | null = null;
+    let isStopped = false;
+
+    const writeFrameNow = (frame: Buffer): void => {
+        latestWrittenFrame = frame;
+        lastWriteAtMs = Date.now();
+        options.writeFrame(frame);
+    };
+
+    const pushFrame = (frame: Buffer): void => {
+        if (isStopped) {
+            return;
+        }
+
+        const elapsedMs = Date.now() - lastWriteAtMs;
+        if (elapsedMs >= options.minimumFrameIntervalMs) {
+            writeFrameNow(frame);
+            return;
+        }
+
+        pendingFrame = frame;
+        if (scheduledWriteTimeout === null) {
+            scheduledWriteTimeout = setTimeout(() => {
+                scheduledWriteTimeout = null;
+                if (isStopped || pendingFrame === null) {
+                    return;
+                }
+
+                const frameToWrite = pendingFrame;
+                pendingFrame = null;
+                writeFrameNow(frameToWrite);
+            }, Math.max(1, options.minimumFrameIntervalMs - elapsedMs));
+        }
+    };
+
+    const heartbeatInterval = setInterval(() => {
+        if (isStopped || latestWrittenFrame === null) {
+            return;
+        }
+
+        if (Date.now() - lastWriteAtMs >= options.heartbeatIntervalMs) {
+            writeFrameNow(latestWrittenFrame);
+        }
+    }, options.heartbeatIntervalMs);
+    heartbeatInterval.unref?.();
+
+    const stop = (): void => {
+        isStopped = true;
+        if (scheduledWriteTimeout !== null) {
+            clearTimeout(scheduledWriteTimeout);
+            scheduledWriteTimeout = null;
+        }
+
+        clearInterval(heartbeatInterval);
+        latestWrittenFrame = null;
+        pendingFrame = null;
+    };
+
+    return { pushFrame, stop };
+}

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

@@ -13,6 +13,7 @@ import { ParseError } from '../../../../src/errors/ParseError';
 import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { normalizeDomainForMatching } from '../../../../src/utils/validators/url/normalizeDomainForMatching';
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
+import { isSameAgentPermanentId } from './agentIdentifier';
 import { createServerAgentReferenceResolver } from './agentReferenceResolver/createServerAgentReferenceResolver';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getFederatedServers } from './getFederatedServers';
@@ -143,7 +144,8 @@ function createResolverAgentCollection(agents: ReadonlyArray<CustomDomainAgentRo
     const resolveAgent = (agentNameOrPermanentId: string): CustomDomainAgentRow => {
         const agent = agents.find(
             (candidate) =>
-                candidate.agentName === agentNameOrPermanentId || candidate.permanentId === agentNameOrPermanentId,
+                candidate.agentName === agentNameOrPermanentId ||
+                isSameAgentPermanentId(candidate.permanentId, agentNameOrPermanentId),
         );
 
         if (!agent) {

package/apps/agents-server/src/utils/defaultAgents/coreAgentExplanations.ts

@@ -0,0 +1,53 @@
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Curated explanation of why each bundled core agent exists.
+ *
+ * The authoritative set of core agents is defined by the `*.book` files in `agents/default/.core`; this map only adds a
+ * human-readable rationale keyed by the normalized agent name so the Core Agents admin page can explain the purpose of
+ * each one. Core agents that are not listed here fall back to `GENERIC_CORE_AGENT_EXPLANATION`.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export const CORE_AGENT_EXPLANATION_BY_AGENT_NAME: Readonly<Record<string, string>> = {
+    adam: spaceTrim(`
+        **Adam** is the root ancestor agent. Every agent that does not use an explicit \`FROM\` commitment inherits from
+        Adam, so its persona, rules, and base capabilities form the shared foundation of all agents on this server.
+        Removing Adam breaks the default inheritance chain for new and existing agents.
+    `),
+    expert: spaceTrim(`
+        **Expert** is the Book-language specialist that other core agents build on. It carries the knowledge about the
+        Book language used whenever an agent needs to reason about or generate Book sources, and it is the ancestor of
+        the Creator agent.
+    `),
+    creator: spaceTrim(`
+        **Creator** turns any input into a Book-language agent. It powers the "create an agent from a description"
+        flows and inherits from Expert, so it depends on the other core agents being present.
+    `),
+    teacher: spaceTrim(`
+        **Teacher** explains and consults on the Book language and guides users while they write or modify agents. It is
+        used by the self-learning features and inherits from Adam.
+    `),
+};
+
+/**
+ * Fallback explanation shown for a core agent that has no curated rationale.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export const GENERIC_CORE_AGENT_EXPLANATION = spaceTrim(`
+    This is a core agent bundled in the \`.core\` folder. Core agents are used as a shared base building block for the
+    other agents on this server.
+`);
+
+/**
+ * Resolves the human-readable explanation of why one core agent exists.
+ *
+ * @param agentName - Normalized agent name (for example \`adam\`).
+ * @returns Curated explanation, or a generic fallback for unknown core agents.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export function resolveCoreAgentExplanation(agentName: string): string {
+    return CORE_AGENT_EXPLANATION_BY_AGENT_NAME[agentName.toLowerCase()] ?? GENERIC_CORE_AGENT_EXPLANATION;
+}

package/apps/agents-server/src/utils/defaultAgents/resolveDefaultAgentsStatus.ts

@@ -0,0 +1,249 @@
+import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { prepareAgentSourceForPersistence } from '../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/prepareAgentSourceForPersistence';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
+import { resolveCoreAgentExplanation } from './coreAgentExplanations';
+import { loadCoreAgentBooks, loadDefaultAgentBooks, type LoadDefaultAgentBooksOptions } from './loadDefaultAgentBooks';
+
+/**
+ * Identity of one bundled agent book used to match it against a persisted agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type BundledAgentIdentity = {
+    /**
+     * Normalized agent name that matches the persisted `agentName` column.
+     */
+    readonly agentName: string;
+
+    /**
+     * Human-readable title taken from the first line of the book.
+     */
+    readonly title: string;
+
+    /**
+     * Hash the persisted agent would have right after seeding from the repository book.
+     */
+    readonly expectedAgentHash: string;
+};
+
+/**
+ * Presence and repository-difference report for one bundled core agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type CoreAgentReport = BundledAgentIdentity & {
+    /**
+     * Explanation of why this core agent exists.
+     */
+    readonly explanation: string;
+
+    /**
+     * Whether the core agent currently exists on this server.
+     */
+    readonly isPresent: boolean;
+
+    /**
+     * Whether the present core agent differs from the bundled repository book.
+     *
+     * This is informational only — an edited core agent is perfectly fine and must not be treated as a warning.
+     */
+    readonly isDifferentFromRepository: boolean;
+
+    /**
+     * Permanent id of the present agent, used to link to its editable book.
+     */
+    readonly permanentId: string | null;
+};
+
+/**
+ * Presence report for one bundled normal default agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type DefaultAgentReport = BundledAgentIdentity & {
+    /**
+     * Whether the default agent currently exists on this server.
+     */
+    readonly isPresent: boolean;
+
+    /**
+     * Permanent id of the present agent, used to link to its editable book.
+     */
+    readonly permanentId: string | null;
+};
+
+/**
+ * Combined status of the bundled normal default agents and core default agents on the current server.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type DefaultAgentsStatus = {
+    readonly coreAgents: ReadonlyArray<CoreAgentReport>;
+    readonly defaultAgents: ReadonlyArray<DefaultAgentReport>;
+    readonly isAnyCoreAgentMissing: boolean;
+    readonly isAnyDefaultAgentMissing: boolean;
+};
+
+/**
+ * In-memory cache of parsed bundled identities keyed by the resolved default-agent directory.
+ *
+ * The bundled books never change while the process runs, so parsing them once avoids repeated disk reads on every
+ * admin page render.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+const cachedIdentitiesByDirectoryKey = new Map<
+    string,
+    {
+        readonly defaultAgents: ReadonlyArray<BundledAgentIdentity>;
+        readonly coreAgents: ReadonlyArray<BundledAgentIdentity>;
+    }
+>();
+
+/**
+ * Loads the parsed identities of the bundled default and core agent books.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Parsed identities for the normal default agents and the core agents.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export async function loadBundledAgentIdentities(options: LoadDefaultAgentBooksOptions = {}): Promise<{
+    readonly defaultAgents: ReadonlyArray<BundledAgentIdentity>;
+    readonly coreAgents: ReadonlyArray<BundledAgentIdentity>;
+}> {
+    const directoryKey = options.defaultAgentDirectory ?? '<default>';
+    const cachedIdentities = cachedIdentitiesByDirectoryKey.get(directoryKey);
+    if (cachedIdentities) {
+        return cachedIdentities;
+    }
+
+    const [defaultAgentBooks, coreAgentBooks] = await Promise.all([
+        loadDefaultAgentBooks(options),
+        loadCoreAgentBooks(options),
+    ]);
+    const identities = {
+        defaultAgents: defaultAgentBooks.map(createBundledAgentIdentity),
+        coreAgents: coreAgentBooks.map(createBundledAgentIdentity),
+    };
+    cachedIdentitiesByDirectoryKey.set(directoryKey, identities);
+    return identities;
+}
+
+/**
+ * Resolves the presence and repository-difference status of the bundled default and core agents.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Combined status used by the home page notices and the Core Agents admin page.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export async function resolveDefaultAgentsStatus(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<DefaultAgentsStatus> {
+    const [{ defaultAgents: defaultIdentities, coreAgents: coreIdentities }, presentAgentByName] = await Promise.all([
+        loadBundledAgentIdentities(options),
+        loadPresentAgentsByName(),
+    ]);
+
+    const coreAgents = coreIdentities.map((identity) => {
+        const presentAgent = presentAgentByName.get(identity.agentName);
+        return {
+            ...identity,
+            explanation: resolveCoreAgentExplanation(identity.agentName),
+            isPresent: presentAgent !== undefined,
+            isDifferentFromRepository:
+                presentAgent !== undefined && presentAgent.agentHash !== identity.expectedAgentHash,
+            permanentId: presentAgent?.permanentId ?? null,
+        };
+    });
+    const defaultAgents = defaultIdentities.map((identity) => {
+        const presentAgent = presentAgentByName.get(identity.agentName);
+        return {
+            ...identity,
+            isPresent: presentAgent !== undefined,
+            permanentId: presentAgent?.permanentId ?? null,
+        };
+    });
+
+    return {
+        coreAgents,
+        defaultAgents,
+        isAnyCoreAgentMissing: coreAgents.some((coreAgent) => !coreAgent.isPresent),
+        isAnyDefaultAgentMissing: defaultAgents.some((defaultAgent) => !defaultAgent.isPresent),
+    };
+}
+
+/**
+ * Returns the normalized names of core agents that are missing from a set of present agent names.
+ *
+ * This lightweight check reuses an already-loaded agent list (for example the header organization state) so the admin
+ * menu can flag missing core agents without an extra database query.
+ *
+ * @param coreIdentities - Parsed identities of the bundled core agents.
+ * @param presentAgentNames - Names of the agents already present on the server.
+ * @returns Normalized names of the core agents that are not present.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export function resolveMissingCoreAgentNames(
+    coreIdentities: ReadonlyArray<BundledAgentIdentity>,
+    presentAgentNames: Iterable<string>,
+): ReadonlyArray<string> {
+    const presentAgentNameSet = new Set(presentAgentNames);
+    return coreIdentities
+        .filter((identity) => !presentAgentNameSet.has(identity.agentName))
+        .map((identity) => identity.agentName);
+}
+
+/**
+ * Builds one bundled agent identity from a raw book source.
+ *
+ * The expected hash is computed exactly the way the seeding flow persists the agent, so a freshly seeded agent is never
+ * reported as differing from the repository.
+ *
+ * @param agentBook - Raw bundled agent book source.
+ * @returns Parsed identity for the bundled agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+function createBundledAgentIdentity(agentBook: string_book): BundledAgentIdentity {
+    const { agentProfile } = prepareAgentSourceForPersistence(agentBook);
+    return {
+        agentName: agentProfile.agentName,
+        title: resolveBundledAgentTitle(agentBook) ?? agentProfile.agentName,
+        expectedAgentHash: agentProfile.agentHash,
+    };
+}
+
+/**
+ * Extracts the human-readable title (first non-empty line) from a book source.
+ *
+ * @param agentBook - Raw bundled agent book source.
+ * @returns Title line, or `null` when the book has no visible title.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+function resolveBundledAgentTitle(agentBook: string_book): string | null {
+    for (const line of agentBook.split(/\r?\n/)) {
+        const trimmedLine = line.trim();
+        if (trimmedLine !== '') {
+            return trimmedLine;
+        }
+    }
+    return null;
+}
+
+/**
+ * Loads all active agents on the current server indexed by their normalized name.
+ *
+ * @returns Map from normalized agent name to its basic information.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+async function loadPresentAgentsByName(): Promise<ReadonlyMap<string, AgentBasicInformation>> {
+    const collection = await $provideAgentCollectionForServer();
+    const presentAgents = await collection.listAgents();
+    return new Map(presentAgents.map((presentAgent) => [presentAgent.agentName, presentAgent]));
+}

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

@@ -0,0 +1,38 @@
+/**
+ * One external DNS-provider help link shown with DNS setup guidance.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsProviderGuide = {
+    /**
+     * Human-readable provider label.
+     */
+    readonly label: string;
+
+    /**
+     * Official provider help URL.
+     */
+    readonly href: string;
+};
+
+/**
+ * Common DNS-provider help links shown with server and project DNS instructions.
+ */
+export const DNS_PROVIDER_GUIDES: ReadonlyArray<DnsProviderGuide> = [
+    {
+        label: 'Cloudflare DNS records',
+        href: 'https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/',
+    },
+    {
+        label: 'GoDaddy DNS records',
+        href: 'https://www.godaddy.com/help/manage-dns-records-680',
+    },
+    {
+        label: 'Namecheap DNS records',
+        href: 'https://www.namecheap.com/support/knowledgebase/article.aspx/319/2237/how-can-i-set-up-an-a-address-record-for-my-domain/',
+    },
+    {
+        label: 'Squarespace DNS records',
+        href: 'https://support.squarespace.com/hc/en-us/articles/360002101888-Adding-custom-DNS-records-to-your-Squarespace-managed-domain',
+    },
+];

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

@@ -0,0 +1,33 @@
+/**
+ * Whether every shown DNS record has to be configured or just one of the shown alternatives.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordSelection = 'all' | 'one';
+
+/**
+ * One DNS record shown to an Agents Server administrator for configuration at a DNS provider.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordInstruction = {
+    /**
+     * DNS record type.
+     */
+    readonly type: string;
+
+    /**
+     * Fully qualified DNS record name.
+     */
+    readonly name: string;
+
+    /**
+     * DNS record value to configure.
+     */
+    readonly value: string;
+
+    /**
+     * Explanation of when or why this record is needed.
+     */
+    readonly note: string | null;
+};

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

@@ -0,0 +1,91 @@
+import { spaceTrim } from 'spacetrim';
+import { CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC } from '../cloudflare/CloudflareApi';
+import type { DnsRecordInstruction } from './DnsRecordInstruction';
+
+/**
+ * DNS record types whose value is a hostname which has to be absolute in a zone file.
+ */
+const DNS_ZONE_FILE_HOSTNAME_RECORD_TYPES: ReadonlySet<string> = new Set(['CNAME', 'NS', 'PTR']);
+
+/**
+ * A zone-file character string can hold at most 255 characters, longer `TXT` values are split into more strings.
+ */
+const DNS_ZONE_FILE_TEXT_CHUNK_LENGTH = 255;
+
+/**
+ * Creates a BIND zone file with all given DNS records.
+ *
+ * The file can be imported at once by DNS providers which support zone-file imports, so that an administrator does
+ * not have to retype the records one by one.
+ *
+ * @param options - Domain and the records which should be part of the export.
+ * @returns BIND zone file contents.
+ */
+export function createDnsZoneFileExport(options: {
+    readonly domain: string;
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+}): string {
+    const recordLines = options.records.map((record) =>
+        [
+            `${normalizeZoneFileRecordName(record.name)}.`,
+            String(CLOUDFLARE_DNS_RECORD_TTL_AUTOMATIC),
+            'IN',
+            record.type.toUpperCase(),
+            createZoneFileRecordData(record.type, record.value),
+        ].join('\t'),
+    );
+
+    return spaceTrim(
+        (block) => `
+            ; DNS records for ${options.domain} generated by the Promptbook Agents Server
+            ; Import this file at your DNS provider instead of adding every record by hand.
+
+            ${block(recordLines.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Normalizes one record name into its absolute zone-file form without the trailing dot.
+ *
+ * @param name - Fully qualified DNS record name.
+ * @returns Record name usable in a zone file.
+ */
+function normalizeZoneFileRecordName(name: string): string {
+    return name.trim().toLowerCase().replace(/\.$/, '');
+}
+
+/**
+ * Creates the zone-file record data of one DNS record.
+ *
+ * @param type - DNS record type.
+ * @param value - DNS record value as shown in the DNS manual.
+ * @returns Record data in the zone-file syntax.
+ */
+function createZoneFileRecordData(type: string, value: string): string {
+    const normalizedType = type.toUpperCase();
+    const normalizedValue = value.trim();
+
+    if (normalizedType === 'TXT') {
+        return createZoneFileTextRecordData(normalizedValue);
+    }
+
+    if (DNS_ZONE_FILE_HOSTNAME_RECORD_TYPES.has(normalizedType)) {
+        return normalizedValue.endsWith('.') ? normalizedValue : `${normalizedValue}.`;
+    }
+
+    return normalizedValue;
+}
+
+/**
+ * Quotes one `TXT` value and splits it into zone-file character strings.
+ *
+ * @param value - Raw text value, for example an SPF or DMARC policy.
+ * @returns Quoted character strings.
+ */
+function createZoneFileTextRecordData(value: string): string {
+    const unquotedValue = value.replace(/^"(.*)"$/s, '$1');
+    const textChunks = unquotedValue.match(new RegExp(`.{1,${DNS_ZONE_FILE_TEXT_CHUNK_LENGTH}}`, 'gs')) || [''];
+
+    return textChunks.map((textChunk) => `"${textChunk.replace(/"/g, '\\"')}"`).join(' ');
+}

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

@@ -0,0 +1,81 @@
+import type { DnsRecordInstruction, DnsRecordSelection } from './DnsRecordInstruction';
+
+/**
+ * Placeholder values like `<VPS_PUBLIC_IP>` have to be filled in by a human before the record can be created.
+ */
+const DNS_RECORD_PLACEHOLDER_VALUE_PATTERN = /<[^>]+>/;
+
+/**
+ * One DNS record which cannot be configured in one batch together with the other records.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type ExcludedDnsRecordInstruction = {
+    /**
+     * DNS record which has to be configured manually.
+     */
+    readonly record: DnsRecordInstruction;
+
+    /**
+     * Explanation why the record is not part of the batch.
+     */
+    readonly reason: string;
+};
+
+/**
+ * Split of the DNS records shown in one manual into records which can be configured in one batch and the rest.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export type DnsRecordBatchPlan = {
+    /**
+     * DNS records which can be exported or written to the DNS provider without any human decision.
+     */
+    readonly applicableRecords: ReadonlyArray<DnsRecordInstruction>;
+
+    /**
+     * DNS records which are intentionally left out of the batch.
+     */
+    readonly excludedRecords: ReadonlyArray<ExcludedDnsRecordInstruction>;
+};
+
+/**
+ * Resolves which of the shown DNS records can be configured in one batch.
+ *
+ * This is the single source of truth for both the zone-file export and the Cloudflare API import, so that both ways
+ * of the wizard configure exactly the same records.
+ *
+ * @param options - Records shown in the DNS manual and whether they are alternatives.
+ * @returns Records which can be batched together with the reasons for the excluded ones.
+ */
+export function resolveDnsRecordBatchPlan(options: {
+    readonly records: ReadonlyArray<DnsRecordInstruction>;
+    readonly recordSelection: DnsRecordSelection;
+}): DnsRecordBatchPlan {
+    const applicableRecords: Array<DnsRecordInstruction> = [];
+    const excludedRecords: Array<ExcludedDnsRecordInstruction> = [];
+
+    for (const record of options.records) {
+        if (DNS_RECORD_PLACEHOLDER_VALUE_PATTERN.test(record.value)) {
+            excludedRecords.push({
+                record,
+                reason: `The value \`${record.value}\` is a placeholder which has to be filled in manually.`,
+            });
+            continue;
+        }
+
+        // Note: When the records are alternatives, only the first (recommended) one may be configured, because the
+        //       other ones would conflict with it on the same hostname.
+        if (options.recordSelection === 'one' && applicableRecords.length > 0) {
+            excludedRecords.push({
+                record,
+                reason: 'Alternative of the recommended record, configure it only instead of the recommended record.',
+            });
+            continue;
+        }
+
+        applicableRecords.push(record);
+    }
+
+    return { applicableRecords, excludedRecords };
+}