@promptbook/cli 0.112.0-104 → 0.112.0-106

package/apps/agents-server/src/database/seedDefaultAgents.ts

@@ -0,0 +1,218 @@
+import * as dotenv from 'dotenv';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { AgentCollectionInSupabase } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase';
+import type { AgentsDatabaseSchema } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentsDatabaseSchema';
+import { $provideSupabaseForServer } from './$provideSupabaseForServer';
+import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
+import { loadDefaultAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
+
+/**
+ * Environment variable pointing to the installed Agents Server `.env` file.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
+
+/**
+ * Environment variable with an explicit default-agent source directory.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+const DEFAULT_AGENTS_DIRECTORY_ENV_NAME = 'PTBK_DEFAULT_AGENTS_DIR';
+
+/**
+ * Environment variable carrying the current Agents Server table prefix.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+const SUPABASE_TABLE_PREFIX_ENV_NAME = 'SUPABASE_TABLE_PREFIX';
+
+/**
+ * Logger surface used by the default-agent seeder.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+type SeedDefaultAgentsLogger = Pick<Console, 'error' | 'info' | 'warn'>;
+
+/**
+ * Options for installing bundled default agents into the current Agents Server database.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+export type SeedDefaultAgentsOptions = {
+    /**
+     * Optional explicit directory containing default `*.book` files.
+     */
+    readonly defaultAgentDirectory?: string | null;
+
+    /**
+     * Optional table prefix for the server namespace being seeded.
+     */
+    readonly tablePrefix?: string | null;
+
+    /**
+     * Optional logger for installer output.
+     */
+    readonly logger?: SeedDefaultAgentsLogger;
+};
+
+/**
+ * Result of one default-agent seed attempt.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+export type SeedDefaultAgentsResult = {
+    /**
+     * Number of agents already present before seeding, including soft-deleted agents.
+     */
+    readonly existingAgentCount: number;
+
+    /**
+     * Number of bundled default books found.
+     */
+    readonly sourceCount: number;
+
+    /**
+     * Number of default agents created.
+     */
+    readonly createdCount: number;
+
+    /**
+     * Names of agents created during this run.
+     */
+    readonly createdAgentNames: ReadonlyArray<string>;
+
+    /**
+     * Reason no agents were created.
+     */
+    readonly skippedReason: 'existing-agents' | 'no-default-books' | null;
+};
+
+/**
+ * Installs bundled default agents when the current server has no agents yet.
+ *
+ * @param options - Optional seed controls.
+ * @returns Seed summary.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+export async function seedDefaultAgents(options: SeedDefaultAgentsOptions = {}): Promise<SeedDefaultAgentsResult> {
+    const logger = options.logger ?? console;
+    const tablePrefix = options.tablePrefix ?? process.env[SUPABASE_TABLE_PREFIX_ENV_NAME] ?? '';
+    const collection = new AgentCollectionInSupabase(resolveAgentsDatabaseSupabaseClient(), { tablePrefix });
+    const existingAgentCount = await countExistingAgents(collection);
+
+    if (existingAgentCount > 0) {
+        logger.info(
+            `Skipping default agents because the server already has ${existingAgentCount} agent${
+                existingAgentCount === 1 ? '' : 's'
+            }.`,
+        );
+        return {
+            existingAgentCount,
+            sourceCount: 0,
+            createdCount: 0,
+            createdAgentNames: [],
+            skippedReason: 'existing-agents',
+        };
+    }
+
+    const defaultAgentBooks = await loadDefaultAgentBooks({
+        defaultAgentDirectory: options.defaultAgentDirectory ?? process.env[DEFAULT_AGENTS_DIRECTORY_ENV_NAME],
+    });
+
+    if (defaultAgentBooks.length === 0) {
+        logger.warn('Skipping default agents because no bundled *.book files were found.');
+        return {
+            existingAgentCount,
+            sourceCount: 0,
+            createdCount: 0,
+            createdAgentNames: [],
+            skippedReason: 'no-default-books',
+        };
+    }
+
+    const createdAgentNames: Array<string> = [];
+
+    for (const [index, defaultAgentBook] of defaultAgentBooks.entries()) {
+        const createdAgent = await collection.createAgent(defaultAgentBook, {
+            sortOrder: index,
+            visibility: DEFAULT_AGENT_VISIBILITY,
+        });
+        createdAgentNames.push(createdAgent.agentName);
+        logger.info(`Created default agent: ${createdAgent.agentName}`);
+    }
+
+    return {
+        existingAgentCount,
+        sourceCount: defaultAgentBooks.length,
+        createdCount: createdAgentNames.length,
+        createdAgentNames,
+        skippedReason: null,
+    };
+}
+
+/**
+ * Counts active and soft-deleted agents so repeated installer runs do not recreate defaults.
+ *
+ * @param collection - Agent collection bound to the current table prefix.
+ * @returns Number of existing active and deleted agents.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+async function countExistingAgents(collection: AgentCollectionInSupabase): Promise<number> {
+    const activeAgents = await collection.listAgents();
+    const deletedAgents = await collection.listDeletedAgents();
+
+    return activeAgents.length + deletedAgents.length;
+}
+
+/**
+ * Resolves the Supabase-shaped client for the Agent collection subset.
+ *
+ * @returns Supabase client typed for agent collection persistence.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+function resolveAgentsDatabaseSupabaseClient(): SupabaseClient<AgentsDatabaseSchema> {
+    return $provideSupabaseForServer() as unknown as SupabaseClient<AgentsDatabaseSchema>;
+}
+
+/**
+ * Loads the installed Agents Server environment before seeding.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+function loadSeedDefaultAgentsEnvironment(): void {
+    const explicitEnvFilePath = process.env[AGENTS_SERVER_ENV_FILE_ENV_NAME]?.trim();
+    if (explicitEnvFilePath) {
+        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath });
+        if (!explicitLoadResult.error) {
+            return;
+        }
+    }
+
+    dotenv.config();
+}
+
+/**
+ * Runs the standalone default-agent seed command.
+ *
+ * @private utility of standalone default-agent seeding
+ */
+async function runSeedDefaultAgentsCommand(): Promise<void> {
+    loadSeedDefaultAgentsEnvironment();
+    const result = await seedDefaultAgents();
+
+    if (result.createdCount > 0) {
+        console.info(`Installed ${result.createdCount} default agent${result.createdCount === 1 ? '' : 's'}.`);
+    }
+}
+
+if (require.main === module) {
+    runSeedDefaultAgentsCommand().catch((error) => {
+        console.error('Failed to install default agents:');
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -4,6 +4,16 @@ import { TrackedFilesStorage } from '../utils/cdn/classes/TrackedFilesStorage';
 import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
 
+/**
+ * Options controlling CDN storage construction for the current server request.
+ */
+export type ProvideCdnForServerOptions = {
+    /**
+     * Public URL used when generating file links.
+     */
+    readonly cdnPublicUrl?: URL;
+};
+
 /**
  * Region expected by the bundled VersityGW S3-compatible storage.
  *
@@ -19,20 +29,28 @@ const SELF_CONTAINED_S3_DEFAULT_REGION = 'us-east-1';
 const EXTERNAL_S3_DEFAULT_REGION = 'auto';
 
 /**
- * Cache of CDN instance
+ * Cache of CDN instances by public URL.
  *
  * @private internal cache for `$provideCdnForServer`
  */
-let cdn: IIFilesStorageWithCdn | null = null;
+const cdnByPublicUrl = new Map<string, IIFilesStorageWithCdn>();
 
 /**
  * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ *
+ * @param options - Optional request-aware CDN public URL override.
+ * @returns CDN storage interface.
  */
-export function $provideCdnForServer(): IIFilesStorageWithCdn {
+export function $provideCdnForServer(options: ProvideCdnForServerOptions = {}): IIFilesStorageWithCdn {
+    const cdnPublicUrl = options.cdnPublicUrl || resolveConfiguredCdnPublicUrl();
+    const cdnCacheKey = cdnPublicUrl.href;
+    let cdn = cdnByPublicUrl.get(cdnCacheKey);
+
     if (!cdn) {
-        const inner = createCdnStorageForServer();
+        const inner = createCdnStorageForServer(cdnPublicUrl);
         const supabase = $provideSupabaseForServer();
         cdn = new TrackedFilesStorage(inner, supabase);
+        cdnByPublicUrl.set(cdnCacheKey, cdn);
     }
 
     return cdn;
@@ -41,9 +59,10 @@ export function $provideCdnForServer(): IIFilesStorageWithCdn {
 /**
  * Creates the configured CDN storage implementation for server-side file operations.
  *
+ * @param cdnPublicUrl - Public URL used to build deterministic file links.
  * @private helper of `$provideCdnForServer`
  */
-function createCdnStorageForServer(): IIFilesStorageWithCdn {
+function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
     if (isS3CompatibleStorageSelected()) {
         return new DigitalOceanSpaces({
             bucket: process.env.CDN_BUCKET!,
@@ -51,7 +70,7 @@ function createCdnStorageForServer(): IIFilesStorageWithCdn {
             endpoint: process.env.CDN_ENDPOINT!,
             accessKeyId: process.env.CDN_ACCESS_KEY_ID!,
             secretAccessKey: process.env.CDN_SECRET_ACCESS_KEY!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+            cdnPublicUrl,
             gzip: true,
             forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
             region: resolveS3CompatibleStorageRegion(),
@@ -61,10 +80,46 @@ function createCdnStorageForServer(): IIFilesStorageWithCdn {
     return new VercelBlobStorage({
         token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
         pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
-        cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+        cdnPublicUrl,
     });
 }
 
+/**
+ * Resolves the CDN public URL from environment configuration.
+ *
+ * @returns Configured CDN public URL.
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveConfiguredCdnPublicUrl(): URL {
+    return new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!);
+}
+
+/**
+ * Resolves the public URL that should be used for CDN links for one server request.
+ *
+ * Self-contained S3 is proxied through the current server domain. The configured
+ * CDN public URL still owns the `/s3/<bucket>` path, but the origin must follow
+ * the active server so uploads are not published under the VPS raw IP address.
+ *
+ * @param serverPublicUrl - Public URL of the active server.
+ * @returns Request-aware CDN public URL.
+ */
+export function resolveCdnPublicUrlForServer(serverPublicUrl: URL): URL {
+    const configuredCdnPublicUrl = resolveConfiguredCdnPublicUrl();
+
+    if (!isSelfContainedS3StorageSelected()) {
+        return configuredCdnPublicUrl;
+    }
+
+    const cdnPublicUrl = new URL(configuredCdnPublicUrl.href);
+    cdnPublicUrl.protocol = serverPublicUrl.protocol;
+    cdnPublicUrl.host = serverPublicUrl.host;
+    cdnPublicUrl.username = '';
+    cdnPublicUrl.password = '';
+
+    return cdnPublicUrl;
+}
+
 /**
  * Checks whether the current environment should use the S3-compatible storage implementation.
  *
@@ -91,6 +146,15 @@ function getS3CompatibleStorageMode(): string {
     return (process.env.PTBK_FILE_STORAGE_MODE || process.env.CDN_PROVIDER || '').toLowerCase();
 }
 
+/**
+ * Checks whether the bundled self-contained S3 storage mode is selected.
+ *
+ * @returns `true` when self-contained S3 is selected.
+ */
+export function isSelfContainedS3StorageSelected(): boolean {
+    return getS3CompatibleStorageMode() === 'self-contained-s3';
+}
+
 /**
  * Resolves the S3 signing region used by AWS SDK requests.
  *
@@ -102,7 +166,7 @@ function resolveS3CompatibleStorageRegion(): string {
         return configuredRegion;
     }
 
-    if (getS3CompatibleStorageMode() === 'self-contained-s3') {
+    if (isSelfContainedS3StorageSelected()) {
         return SELF_CONTAINED_S3_DEFAULT_REGION;
     }
 

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

@@ -0,0 +1,103 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Options for loading bundled default agent books.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export type LoadDefaultAgentBooksOptions = {
+    /**
+     * Optional explicit directory containing `*.book` files.
+     */
+    readonly defaultAgentDirectory?: string | null;
+};
+
+/**
+ * Candidate directories where bundled default agent books can be located.
+ *
+ * The app test suite runs from `apps/agents-server`, local development usually runs from the repository root, and
+ * installer scripts can pass an explicit directory through `LoadDefaultAgentBooksOptions`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+const DEFAULT_AGENT_DIRECTORY_CANDIDATES = [
+    resolve(process.cwd(), 'agents', 'default'),
+    resolve(process.cwd(), '..', '..', 'agents', 'default'),
+    resolve(__dirname, '../../../../../agents/default'),
+] as const;
+
+/**
+ * Loads all default agent books in deterministic filename order.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Sorted default agent sources.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function loadDefaultAgentBooks(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<ReadonlyArray<string_book>> {
+    const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
+    const directoryEntries = await readdir(defaultAgentDirectory);
+    const defaultAgentFilenames = directoryEntries
+        .filter((entry) => entry.toLowerCase().endsWith('.book'))
+        .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
+
+    return Promise.all(
+        defaultAgentFilenames.map(async (filename) => {
+            const filePath = resolve(defaultAgentDirectory, filename);
+            return (await readFile(filePath, 'utf-8')) as string_book;
+        }),
+    );
+}
+
+/**
+ * Resolves the repository directory that stores default agent books.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Absolute path to `agents/default`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function resolveDefaultAgentDirectory(options: LoadDefaultAgentBooksOptions = {}): Promise<string> {
+    const directoryCandidates = [
+        ...(options.defaultAgentDirectory ? [resolve(options.defaultAgentDirectory)] : []),
+        ...DEFAULT_AGENT_DIRECTORY_CANDIDATES,
+    ];
+
+    for (const directoryCandidate of directoryCandidates) {
+        try {
+            await access(directoryCandidate);
+            return directoryCandidate;
+        } catch {
+            // Continue to the next candidate directory.
+        }
+    }
+
+    throw new DatabaseError(
+        spaceTrim(
+            (block) => `
+                Failed to locate the default Agents Server books directory.
+
+                Checked:
+                ${block(directoryCandidates.map((candidate) => `- \`${normalizePathForLogs(candidate)}\``).join('\n'))}
+            `,
+        ),
+    );
+}
+
+/**
+ * Normalizes path separators for diagnostics.
+ *
+ * @param value - Raw filesystem path.
+ * @returns Slash-normalized path.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+function normalizePathForLogs(value: string): string {
+    return value.split('\\').join('/');
+}

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

@@ -39,6 +39,15 @@ export type SpawnAgentLimits = {
     readonly rateLimitWindowMs: number;
 };
 
+/**
+ * Dedicated subset consumed by the local coding-agent runner.
+ *
+ * @private internal Agents Server type
+ */
+export type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+};
+
 /**
  * Row shape loaded from the dedicated `ServerLimit` table.
  *
@@ -250,6 +259,20 @@ export async function getSpawnAgentLimits(): Promise<SpawnAgentLimits> {
     };
 }
 
+/**
+ * Loads the local coding-agent runner retry limits.
+ *
+ * @returns Dedicated local agent runner limits.
+ *
+ * @private internal Agents Server helper
+ */
+export async function getLocalAgentRunnerLimits(): Promise<LocalAgentRunnerLimits> {
+    const limits = await getServerLimits();
+    return {
+        maxFailedAttempts: limits[SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS],
+    };
+}
+
 /**
  * Normalizes one arbitrary key/value object into the supported dedicated server-limit payload.
  *
@@ -277,7 +300,9 @@ export function normalizeServerLimitValues(rawValue: Record<string, unknown>): S
  */
 async function loadLegacyServerLimits(): Promise<Partial<Record<ServerLimitKey, unknown>>> {
     const metadata = await getMetadataMap(DEPRECATED_LIMIT_METADATA_KEYS);
-    const normalizedToolUsageLimits = normalizeToolUsageLimits(parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]));
+    const normalizedToolUsageLimits = normalizeToolUsageLimits(
+        parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]),
+    );
 
     return {
         [SERVER_LIMIT_KEYS.TIMEOUT_MAX_ACTIVE_PER_CHAT]: normalizedToolUsageLimits.timeout.maxActivePerChat,

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

@@ -1,26 +1,9 @@
-import { access, readFile, readdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import type { string_book } from '../../../../../../src/book-2.0/agent-source/string_book';
 import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
-import { DatabaseError } from '../../../../../../src/errors/DatabaseError';
 import type { Client } from 'pg';
-import { spaceTrim } from 'spacetrim';
+import { loadDefaultAgentBooks } from '../../defaultAgents/loadDefaultAgentBooks';
 import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
 import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
 
-/**
- * Candidate directories where bundled default agent books can be located.
- *
- * The app test suite runs from `apps/agents-server`, while local development usually runs from the repository root.
- *
- * @private function of createManagedServer
- */
-const DEFAULT_AGENT_DIRECTORY_CANDIDATES = [
-    resolve(process.cwd(), 'agents', 'default'),
-    resolve(process.cwd(), '..', '..', 'agents', 'default'),
-    resolve(__dirname, '../../../../../../agents/default'),
-] as const;
-
 /**
  * Loads default agent books from the repository and persists them into the newly created server.
  *
@@ -118,70 +101,3 @@ export async function seedServerDefaultAgents(
         sqlRecorder.addStatement(createInsertStatement(`${input.tablePrefix}AgentHistory`, agentHistoryInsertRecord));
     }
 }
-
-/**
- * Loads all default agent books in deterministic filename order.
- *
- * @returns Sorted default agent sources.
- *
- * @private function of `seedServerDefaultAgents`
- */
-async function loadDefaultAgentBooks(): Promise<ReadonlyArray<string_book>> {
-    const defaultAgentDirectory = await resolveDefaultAgentDirectory();
-    const directoryEntries = await readdir(defaultAgentDirectory);
-    const defaultAgentFilenames = directoryEntries
-        .filter((entry) => entry.toLowerCase().endsWith('.book'))
-        .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
-
-    return Promise.all(
-        defaultAgentFilenames.map(async (filename) => {
-            const filePath = resolve(defaultAgentDirectory, filename);
-            return (await readFile(filePath, 'utf-8')) as string_book;
-        }),
-    );
-}
-
-/**
- * Resolves the repository directory that stores default managed-server agents.
- *
- * @returns Absolute path to `agents/default`.
- *
- * @private function of `seedServerDefaultAgents`
- */
-async function resolveDefaultAgentDirectory(): Promise<string> {
-    for (const directoryCandidate of DEFAULT_AGENT_DIRECTORY_CANDIDATES) {
-        try {
-            await access(directoryCandidate);
-            return directoryCandidate;
-        } catch {
-            // Continue to the next candidate directory.
-        }
-    }
-
-    throw new DatabaseError(
-        spaceTrim(
-            (block) => `
-                Failed to locate the default Agents Server books directory.
-
-                Checked:
-                ${block(
-                    DEFAULT_AGENT_DIRECTORY_CANDIDATES.map(
-                        (candidate) => `- \`${normalizePathForLogs(candidate)}\``,
-                    ).join('\n'),
-                )}
-            `,
-        ),
-    );
-}
-
-/**
- * Normalizes path separators for diagnostics.
- *
- * @param value - Raw filesystem path.
- * @returns Slash-normalized path.
- *
- * @private function of `seedServerDefaultAgents`
- */
-function normalizePathForLogs(value: string): string {
-    return value.split('\\').join('/');
-}