@promptbook/cli 0.114.0-3 → 0.114.0-30

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

@@ -4,7 +4,6 @@ import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
 import { isVoidPseudoAgentReference } from '../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
 import { ParseError } from '../../../../src/errors/ParseError';
-import { UnexpectedError } from '../../../../src/errors/UnexpectedError';
 import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { isValidAgentUrl } from '../../../../src/utils/validators/url/isValidAgentUrl';
 import {
@@ -15,6 +14,7 @@ import {
     type AgentReferenceResolutionIssue,
     consumeAgentReferenceResolutionIssues,
 } from './agentReferenceResolver/AgentReferenceResolutionIssue';
+import { collectExplicitFromCommitments, getExplicitFromCommitmentContent } from './explicitFromCommitment';
 import { type ImportAgentOptions } from './importAgent';
 import { importAgentWithFallback } from './importAgentWithFallback';
 
@@ -103,57 +103,6 @@ function insertNotesAfterTitle(agentSource: string_book, notes: ReadonlyArray<st
     return padBook(validateBook(nextLines.join('\n')));
 }
 
-/**
- * Returns the last explicit single-line commitment content for one commitment type.
- *
- * This lightweight parser is intentionally limited to the subset needed by
- * inheritance resolution so it stays safe to bundle into the Next.js proxy path.
- *
- * @param agentSource - Raw book source.
- * @param commitmentType - Commitment keyword to search for.
- * @returns Trimmed commitment content, empty string for a blank explicit commitment, or `undefined` when absent.
- */
-function getLastSingleLineCommitmentContent(agentSource: string_book, commitmentType: 'FROM'): string | undefined {
-    const commitmentPrefix = `${commitmentType} `;
-    const lines = agentSource.split(/\r?\n/);
-    let hasSeenTitle = false;
-    let isInsideCodeBlock = false;
-    let matchedContent: string | undefined;
-
-    for (const line of lines) {
-        const trimmedLine = line.trim();
-
-        if (!hasSeenTitle) {
-            if (!trimmedLine) {
-                continue;
-            }
-
-            hasSeenTitle = true;
-            continue;
-        }
-
-        if (trimmedLine.startsWith('```')) {
-            isInsideCodeBlock = !isInsideCodeBlock;
-            continue;
-        }
-
-        if (isInsideCodeBlock) {
-            continue;
-        }
-
-        if (trimmedLine === commitmentType) {
-            matchedContent = '';
-            continue;
-        }
-
-        if (trimmedLine.startsWith(commitmentPrefix)) {
-            matchedContent = trimmedLine.slice(commitmentPrefix.length).trim();
-        }
-    }
-
-    return matchedContent;
-}
-
 /**
  * Resolves the effective `FROM` parent URL using only lightweight commitment parsing.
  *
@@ -165,7 +114,7 @@ async function resolveParentAgentUrlFromCommitments(
     rawAgentSource: string_book,
     agentReferenceResolver?: AgentReferenceResolver,
 ): Promise<string_agent_url | null | undefined> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(rawAgentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(rawAgentSource);
 
     if (explicitFromContent === undefined) {
         return undefined;
@@ -285,6 +234,11 @@ type ResolvedParentAgentContext = {
      * Unresolved compact-reference issues captured while resolving `FROM`.
      */
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
+
+    /**
+     * Whether the effective parent closed the current lineage and must be materialized as `FROM @Null`.
+     */
+    readonly isCyclicFrom: boolean;
 };
 
 /**
@@ -357,6 +311,28 @@ type ResolvedFromCommitmentLine = {
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
 };
 
+/**
+ * One cycle found while following a source-resolution lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+type ResolutionCycle = {
+    /**
+     * Normalized URL that closes the cycle.
+     */
+    readonly normalizedReferenceUrl: string_agent_url;
+
+    /**
+     * URLs visited before the repeated reference was encountered.
+     */
+    readonly lineage: ReadonlyArray<string_agent_url>;
+
+    /**
+     * Position in `lineage` where the cycle begins.
+     */
+    readonly cycleStartIndex: number;
+};
+
 /**
  * Normalizes agent URLs used for cycle detection and lineage reporting.
  *
@@ -387,6 +363,30 @@ function createResolutionLineage(options?: ResolveInheritedAgentSourceOptions):
     return [...new Set(lineage.map(normalizeAgentUrl))];
 }
 
+/**
+ * Finds a cycle that would be closed by resolving one more agent reference.
+ *
+ * @param referenceUrl - Next agent reference to resolve.
+ * @param options - Current resolution options.
+ * @returns Cycle details, or `null` when the reference is not in the current lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+function findResolutionCycle(
+    referenceUrl: string_agent_url,
+    options?: ResolveInheritedAgentSourceOptions,
+): ResolutionCycle | null {
+    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
+    const lineage = createResolutionLineage(options);
+    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+
+    if (cycleStartIndex === -1) {
+        return null;
+    }
+
+    return { normalizedReferenceUrl, lineage, cycleStartIndex };
+}
+
 /**
  * Creates the shared import context used throughout one resolution pass.
  *
@@ -415,6 +415,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
  * @param hasExplicitFromCommitment - Whether the source explicitly declared `FROM`.
  * @param adamAgentUrl - Default Adam ancestor URL.
  * @param currentAgentUrl - Canonical URL of the source being resolved.
+ * @param currentAgentAliases - Additional URLs that identify the source being resolved.
  * @param agentSource - Raw source used for unexpected diagnostics.
  * @returns Effective parent URL or `null` when inheritance is disabled.
  */
@@ -423,6 +424,7 @@ function determineParentAgentUrl(
     hasExplicitFromCommitment: boolean,
     adamAgentUrl: string_agent_url,
     currentAgentUrl?: string_agent_url,
+    currentAgentAliases?: ReadonlyArray<string_agent_url>,
     agentSource?: string_book,
 ): string_agent_url | null {
     if (isValidAgentUrl(resolvedParentAgentUrl)) {
@@ -434,9 +436,14 @@ function determineParentAgentUrl(
     }
 
     if (resolvedParentAgentUrl === undefined || resolvedParentAgentUrl === null) {
-        return currentAgentUrl && normalizeAgentUrl(currentAgentUrl) === normalizeAgentUrl(adamAgentUrl)
-            ? null
-            : adamAgentUrl;
+        const currentAgentUrls = [currentAgentUrl, ...(currentAgentAliases || [])].filter(
+            (agentUrl): agentUrl is string_agent_url => Boolean(agentUrl),
+        );
+        const isCurrentAgentAdam = currentAgentUrls.some(
+            (agentUrl) => normalizeAgentUrl(agentUrl) === normalizeAgentUrl(adamAgentUrl),
+        );
+
+        return isCurrentAgentAdam ? null : adamAgentUrl;
     }
 
     throw new ParseError(
@@ -496,7 +503,7 @@ async function resolveParentAgentContext(
     agentSource: string_book,
     context: AgentImportContext,
 ): Promise<ResolvedParentAgentContext> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(agentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(agentSource);
     const hasExplicitFromCommitment = explicitFromContent !== undefined;
     const resolvedParentAgentUrl = await resolveParentAgentUrlFromCommitments(
         agentSource,
@@ -510,14 +517,21 @@ async function resolveParentAgentContext(
         hasExplicitFromCommitment,
         context.adamAgentUrl,
         context.resolutionOptions?.currentAgentUrl,
+        context.resolutionOptions?.currentAgentAliases,
         agentSource,
     );
-    const parentAgentSourceCorpus = parentAgentUrl ? await importAgentCorpus(parentAgentUrl, 'FROM', context) : null;
+    const isCyclicFrom = Boolean(parentAgentUrl && findResolutionCycle(parentAgentUrl, context.resolutionOptions));
+    const effectiveParentAgentUrl = isCyclicFrom ? null : parentAgentUrl;
+    const parentAgentSourceCorpus = effectiveParentAgentUrl
+        ? await importAgentCorpus(effectiveParentAgentUrl, 'FROM', context)
+        : null;
 
     return {
-        parentAgentUrl,
+        // A parent that closes the current lineage has the same runtime effect as `FROM @Null`.
+        parentAgentUrl: effectiveParentAgentUrl,
         parentAgentSourceCorpus,
         fromResolutionIssues,
+        isCyclicFrom,
     };
 }
 
@@ -591,36 +605,18 @@ async function resolveImportCommitmentLine(line: string, context: AgentImportCon
 }
 
 /**
- * Resolves one explicit `FROM ...` line into inherited content or fallback NOTE lines.
+ * Resolves the effective `FROM ...` line into inherited content or fallback NOTE lines.
  *
  * @param line - Current source line.
- * @param agentSource - Full source used for duplicate-`FROM` diagnostics.
- * @param isFromResolved - Whether a previous `FROM ...` line was already handled.
  * @param parentContext - Effective parent state computed earlier in the resolution.
  * @returns Output lines and remaining `FROM` issues.
  */
 function resolveFromCommitmentLine(
     line: string,
-    agentSource: string_book,
-    isFromResolved: boolean,
     parentContext: ResolvedParentAgentContext,
 ): ResolvedFromCommitmentLine {
-    if (isFromResolved) {
-        throw new UnexpectedError(
-            spaceTrim(
-                (block) => `
-                    Multiple \`FROM\` commitments found in agent source:
-
-                    \`\`\`book
-                    ${block(agentSource)}
-                    \`\`\`
-                `,
-            ),
-        );
-    }
-
     if (parentContext.parentAgentUrl === null) {
-        const agentSourceChunks = [line];
+        const agentSourceChunks = [parentContext.isCyclicFrom ? 'FROM @Null' : line];
 
         if (parentContext.fromResolutionIssues.length > 0) {
             appendResolutionIssueNotes(agentSourceChunks, parentContext.fromResolutionIssues);
@@ -654,6 +650,23 @@ function resolveFromCommitmentLine(
     };
 }
 
+/**
+ * Finds the `FROM` lines that a later `FROM` takes precedence over.
+ *
+ * A book is allowed to repeat `FROM`; the last one wins, so every earlier one is dropped instead of being resolved.
+ * The Book editor warns about this while the author is still writing the book.
+ *
+ * @param explicitFromCommitments - Explicit parent declarations found in source order.
+ * @returns Zero-based indexes of every overridden `FROM` line, empty when at most one `FROM` is present.
+ */
+function collectOverriddenFromLineIndexes(
+    explicitFromCommitments: ReadonlyArray<{ readonly lineIndex: number }>,
+): ReadonlySet<number> {
+    return new Set(
+        explicitFromCommitments.slice(0, -1).map((explicitFromCommitment) => explicitFromCommitment.lineIndex),
+    );
+}
+
 /**
  * Rewrites the source body line by line while delegating each branching step to a focused helper.
  *
@@ -669,26 +682,31 @@ async function resolveAgentSourceBuild(
 ): Promise<ResolvedAgentSourceBuild> {
     const agentSourceChunks = spaceTrim(agentSource).split(/\r?\n/);
     const resolvedAgentSourceChunks: Array<string> = [];
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSourceChunks);
+    const effectiveFromCommitment = explicitFromCommitments[explicitFromCommitments.length - 1];
+    const overriddenFromLineIndexes = collectOverriddenFromLineIndexes(explicitFromCommitments);
     let isFromResolved = false;
     let fromResolutionIssues = parentContext.fromResolutionIssues;
     // <- TODO: [🈲] Simple and encapsulated way to split book into commitments
 
-    for (const line of agentSourceChunks) {
+    for (let lineIndex = 0; lineIndex < agentSourceChunks.length; lineIndex++) {
+        const line = agentSourceChunks[lineIndex] || '';
+
+        // Note: A repeated `FROM` is overridden by the last one, so the outdated line is dropped from the resolved source.
+        if (overriddenFromLineIndexes.has(lineIndex)) {
+            continue;
+        }
+
         if (line.trim().startsWith('IMPORT ')) {
             resolvedAgentSourceChunks.push(...(await resolveImportCommitmentLine(line, context)));
             continue;
         }
 
-        if (line.trim().startsWith('FROM ')) {
-            const resolvedFromCommitment = resolveFromCommitmentLine(
-                line,
-                agentSource,
-                isFromResolved,
-                {
-                    ...parentContext,
-                    fromResolutionIssues,
-                },
-            );
+        if (effectiveFromCommitment?.lineIndex === lineIndex) {
+            const resolvedFromCommitment = resolveFromCommitmentLine(line, {
+                ...parentContext,
+                fromResolutionIssues,
+            });
 
             resolvedAgentSourceChunks.push(...resolvedFromCommitment.agentSourceChunks);
             fromResolutionIssues = resolvedFromCommitment.fromResolutionIssues;
@@ -779,15 +797,16 @@ function assertNoResolutionCycle(
     commitmentType: 'FROM' | 'IMPORT',
     options?: ResolveInheritedAgentSourceOptions,
 ): void {
-    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
-    const lineage = createResolutionLineage(options);
-    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+    const resolutionCycle = findResolutionCycle(referenceUrl, options);
 
-    if (cycleStartIndex === -1) {
+    if (!resolutionCycle) {
         return;
     }
 
-    const cycleChain = [...lineage.slice(cycleStartIndex), normalizedReferenceUrl]
+    const cycleChain = [
+        ...resolutionCycle.lineage.slice(resolutionCycle.cycleStartIndex),
+        resolutionCycle.normalizedReferenceUrl,
+    ]
         .map((visitedUrl) => `- \`${visitedUrl}\``)
         .join('\n');
 

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

@@ -4,7 +4,7 @@ import {
 } from './userWallet';
 
 /**
- * Resolves SMTP credential payload for USE EMAIL from wallet records.
+ * Resolves SMTP credential payload for agent email from wallet records.
  */
 export async function resolveUseEmailSmtpCredential(
     options: ResolveUseEmailSmtpCredentialOptions,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/insertManagedServerRegistryRow.ts

@@ -22,11 +22,11 @@ export async function insertManagedServerRegistryRow(
     sqlRecorder: SqlRecorder,
 ): Promise<ServerRecord> {
     const insertRegistryResult = await client.query<Record<string, unknown>>(
-        `
+        spaceTrim(`
             INSERT INTO "${SERVER_REGISTRY_TABLE_NAME}" ("name", "environment", "domain", "tablePrefix")
             VALUES ($1, $2, $3, $4)
             RETURNING "id", "name", "environment", "domain", "tablePrefix", "createdAt", "updatedAt"
-        `,
+        `),
         [input.name, input.environment, input.domain, input.tablePrefix],
     );
 

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerCoreAgents.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import type { Client } from 'pg';
 import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
 import { DEFAULT_AGENT_VISIBILITY } from '../../agentVisibility';
@@ -40,7 +41,7 @@ export async function seedServerCoreAgents(
         );
 
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${agentTableIdentifier} (
                     "agentName",
                     "createdAt",
@@ -56,7 +57,7 @@ export async function seedServerCoreAgents(
                     "visibility"
                 )
                 VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8, $9::jsonb, $10, $11, $12)
-            `,
+            `),
             [
                 agentInsertRecord.agentName,
                 agentInsertRecord.createdAt,
@@ -84,7 +85,7 @@ export async function seedServerCoreAgents(
         );
 
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${agentHistoryTableIdentifier} (
                     "createdAt",
                     "agentName",
@@ -96,7 +97,7 @@ export async function seedServerCoreAgents(
                     "versionName"
                 )
                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-            `,
+            `),
             [
                 agentHistoryInsertRecord.createdAt,
                 agentHistoryInsertRecord.agentName,
@@ -130,7 +131,7 @@ async function insertCoreFolder(
     const agentFolderTableIdentifier = quoteIdentifier(`${input.tablePrefix}AgentFolder`);
     const createdAt = new Date().toISOString();
     const insertResult = await client.query<{ id: number }>(
-        `
+        spaceTrim(`
             INSERT INTO ${agentFolderTableIdentifier} (
                 "name",
                 "parentId",
@@ -142,7 +143,7 @@ async function insertCoreFolder(
             )
             VALUES ($1, NULL, $2, NULL, NULL, $3, NULL)
             RETURNING "id"
-        `,
+        `),
         [CORE_AGENT_DIRECTORY_NAME, 0, createdAt],
     );
 

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerDefaultAgents.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
 import type { Client } from 'pg';
 import { DEFAULT_AGENT_VISIBILITY } from '../../agentVisibility';
@@ -34,7 +35,7 @@ export async function seedServerDefaultAgents(
         );
 
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${agentTableIdentifier} (
                     "agentName",
                     "createdAt",
@@ -50,7 +51,7 @@ export async function seedServerDefaultAgents(
                     "visibility"
                 )
                 VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8, $9::jsonb, $10, $11, $12)
-            `,
+            `),
             [
                 agentInsertRecord.agentName,
                 agentInsertRecord.createdAt,
@@ -78,7 +79,7 @@ export async function seedServerDefaultAgents(
         );
 
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${agentHistoryTableIdentifier} (
                     "createdAt",
                     "agentName",
@@ -90,7 +91,7 @@ export async function seedServerDefaultAgents(
                     "versionName"
                 )
                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-            `,
+            `),
             [
                 agentHistoryInsertRecord.createdAt,
                 agentHistoryInsertRecord.agentName,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerMetadata.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { Client } from 'pg';
 import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
 import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
@@ -20,10 +21,10 @@ export async function seedServerMetadata(
 
     for (const metadataEntry of input.metadataEntries) {
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${metadataTableIdentifier} ("key", "value", "note", "createdAt", "updatedAt")
                 VALUES ($1, $2, $3, now(), now())
-            `,
+            `),
             [metadataEntry.key, metadataEntry.value, metadataEntry.note],
         );
 

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerUsers.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { Client } from 'pg';
 import { hashPassword } from '../../auth';
 import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
@@ -23,10 +24,10 @@ export async function seedServerUsers(
         const passwordHash = await hashPassword(user.password);
 
         await client.query(
-            `
+            spaceTrim(`
                 INSERT INTO ${userTableIdentifier} ("username", "passwordHash", "isAdmin", "createdAt", "updatedAt")
                 VALUES ($1, $2, $3, now(), now())
-            `,
+            `),
             [user.username, passwordHash, user.isAdmin],
         );
 

package/apps/agents-server/src/utils/serverManagement/deleteManagedServer.ts

@@ -47,12 +47,12 @@ export async function deleteManagedServer(options: {
         }
 
         const remainingRows = await client.query<Record<string, unknown>>(
-            `
+            spaceTrim(`
                 SELECT "id", "name", "environment", "domain", "tablePrefix", "createdAt", "updatedAt"
                 FROM "${SERVER_REGISTRY_TABLE_NAME}"
                 ORDER BY "name" ASC
                 LIMIT 1
-            `,
+            `),
         );
 
         await client.query('COMMIT');

package/apps/agents-server/src/utils/serverManagement/getManagedServerById.ts

@@ -1,7 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 import { NotFoundError } from '../../../../../src/errors/NotFoundError';
 import type { ServerRecord } from '../serverRegistry';
-import { listRegisteredServersUsingServiceRole } from '../serverRegistry';
+import { listRegisteredServersUsingServiceRole } from '../serverRegistryNode';
 import { SERVER_REGISTRY_TABLE_NAME } from './SERVER_REGISTRY_TABLE_NAME';
 
 /**

package/apps/agents-server/src/utils/serverManagement/listManagedServers.ts

@@ -1,5 +1,5 @@
 import type { ServerRecord } from '../serverRegistry';
-import { listRegisteredServersUsingServiceRole } from '../serverRegistry';
+import { listRegisteredServersUsingServiceRole } from '../serverRegistryNode';
 
 /**
  * Loads all registered servers directly from the shared registry cache.

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

@@ -140,21 +140,6 @@ export async function listRegisteredServersUsingServiceRole(options?: {
 }): Promise<Array<ServerRecord>> {
     const environmentServers = listEnvironmentRegisteredServers();
 
-    if (isAgentsServerSqliteMode()) {
-        if (isEdgeRuntime()) {
-            // Note: The Edge middleware cannot open SQLite files. It only needs the domain list
-            //       for host matching and never queries server tables in SQLite mode, so the
-            //       environment-derived rows are sufficient there.
-            return environmentServers;
-        }
-
-        // Note: In standalone SQLite mode the VPS registry database is the source of truth.
-        //       Every server row carries its own unique table prefix selecting the isolated
-        //       per-server database file, so servers cannot leak data into each other.
-        const { listStandaloneRegisteredServers } = await import('../database/sqlite/standaloneServerRegistryStore');
-        return listStandaloneRegisteredServers();
-    }
-
     const shouldReuseCache =
         !options?.forceRefresh &&
         cachedServerRegistry !== null &&
@@ -217,15 +202,6 @@ export function listEnvironmentRegisteredServers(): Array<ServerRecord> {
     }));
 }
 
-/**
- * Checks whether the current code runs inside the Next.js Edge runtime.
- *
- * @returns `true` when running in the Edge runtime (for example in middleware).
- */
-function isEdgeRuntime(): boolean {
-    return process.env.NEXT_RUNTIME === 'edge';
-}
-
 /**
  * Finds one registered server by incoming host header.
  *

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

@@ -0,0 +1,27 @@
+import { isAgentsServerSqliteMode } from '../database/agentsServerDatabaseMode';
+import { listStandaloneRegisteredServers } from '../database/sqlite/standaloneServerRegistryStore';
+import {
+    listRegisteredServersUsingServiceRole as listSupabaseRegisteredServersUsingServiceRole,
+    type ServerRecord,
+} from './serverRegistry';
+
+/**
+ * Loads registered servers for a Node.js request or background task.
+ *
+ * The standalone SQLite registry is deliberately imported only by this Node.js-only
+ * module. Edge middleware must use environment-derived server rows instead, because
+ * importing SQLite code makes Next.js compile native database dependencies into its
+ * Edge bundle.
+ *
+ * @param options - Cache controls for the Supabase registry lookup.
+ * @returns Registered servers ordered by name.
+ */
+export async function listRegisteredServersUsingServiceRole(options?: {
+    readonly forceRefresh?: boolean;
+}): Promise<Array<ServerRecord>> {
+    if (isAgentsServerSqliteMode()) {
+        return listStandaloneRegisteredServers();
+    }
+
+    return listSupabaseRegisteredServersUsingServiceRole(options);
+}

package/apps/agents-server/src/utils/stalwart/createEmailDnsRecordsSection.ts

@@ -0,0 +1,53 @@
+import type { DnsRecordsSection } from '../dnsRecords/DnsRecordsSection';
+import { createEmailDnsInstructions } from './createEmailDnsInstructions';
+
+/**
+ * Creates the DNS section which makes agent email deliverable for one Agents Server domain.
+ *
+ * The DKIM records are intentionally not part of this section, because their public keys are generated by Stalwart
+ * and have to be copied from its authoritative zone on `/admin/email-server`.
+ *
+ * @param options - Email domain, public VPS IP address, and the current mail DNS state.
+ * @returns Email section.
+ *
+ * @private shared by the Agents Server DNS instruction views
+ */
+export function createEmailDnsRecordsSection(options: {
+    /**
+     * Domain which sends and receives the agent email.
+     */
+    readonly domain: string;
+
+    /**
+     * Public VPS IP address, when known by the server.
+     */
+    readonly publicIpAddress: string | null | undefined;
+
+    /**
+     * Current DNS verification state of the mail records, when it is known.
+     */
+    readonly statusSummary?: string | null;
+
+    /**
+     * Whether the mail records currently need attention.
+     */
+    readonly isDnsIssue?: boolean;
+}): DnsRecordsSection {
+    return {
+        id: 'email',
+        title: `Email for ${options.domain}`,
+        description: options.publicIpAddress
+            ? `Makes agent email deliverable. The A records use the detected public address of this VPS.`
+            : `Makes agent email deliverable. Replace <VPS_PUBLIC_IP> with the public address of this VPS.`,
+        variants: [
+            {
+                id: 'email',
+                label: 'Email',
+                recordSelection: 'all',
+                records: createEmailDnsInstructions(options.domain, options.publicIpAddress),
+            },
+        ],
+        statusSummary: options.statusSummary ?? null,
+        isDnsIssue: options.isDnsIssue,
+    };
+}