@promptbook/cli 0.112.0-134 → 0.112.0-136

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

@@ -0,0 +1,235 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { spaceTrim } from 'spacetrim';
+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 { parseAgentSource } from '../../../../src/book-2.0/agent-source/parseAgentSource';
+import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
+import { DatabaseError } from '../../../../src/errors/DatabaseError';
+import { CORE_AGENT_DIRECTORY_NAME, loadCoreAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
+import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
+import { $getTableName } from './$getTableName';
+import { $provideSupabaseForServer } from './$provideSupabaseForServer';
+
+/**
+ * Logger surface used by the core-agent seeder.
+ *
+ * @private utility of `.core` folder seeding
+ */
+type SeedCoreAgentsLogger = Pick<Console, 'error' | 'info' | 'warn'>;
+
+/**
+ * Options for ensuring the bundled `.core` folder and core agents exist.
+ *
+ * @private utility of `.core` folder seeding
+ */
+export type SeedCoreAgentsOptions = {
+    /**
+     * 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?: SeedCoreAgentsLogger;
+};
+
+/**
+ * Result of one `.core` agents seed attempt.
+ *
+ * @private utility of `.core` folder seeding
+ */
+export type SeedCoreAgentsResult = {
+    /**
+     * Identifier of the `.core` folder, or `null` when no books were available and the folder was not created.
+     */
+    readonly coreFolderId: number | null;
+
+    /**
+     * Names of agents that were created during this run.
+     */
+    readonly createdAgentNames: ReadonlyArray<string>;
+};
+
+/**
+ * Ensures the `.core` folder and well-known core agents are present in the current server database.
+ *
+ * - Creates the `.core` folder when it is missing.
+ * - Creates each bundled `.core/*.book` agent when it is missing from the database.
+ * - Reuses the same persistence mechanism used by the default agent seeder.
+ *
+ * @param options - Optional seed controls.
+ * @returns Seed summary including the resolved `.core` folder id.
+ *
+ * @private utility of `.core` folder seeding
+ */
+export async function seedCoreAgents(options: SeedCoreAgentsOptions = {}): Promise<SeedCoreAgentsResult> {
+    const logger = options.logger ?? console;
+    const tablePrefix = options.tablePrefix ?? process.env.SUPABASE_TABLE_PREFIX ?? '';
+    const collection = new AgentCollectionInSupabase(resolveAgentsDatabaseSupabaseClient(), { tablePrefix });
+
+    const coreAgentBooks = await loadCoreAgentBooks({
+        defaultAgentDirectory: options.defaultAgentDirectory,
+    });
+
+    if (coreAgentBooks.length === 0) {
+        logger.warn(
+            spaceTrim(`
+                Skipping \`.core\` agents because no bundled \`.core/*.book\` files were found.
+            `),
+        );
+
+        return { coreFolderId: null, createdAgentNames: [] };
+    }
+
+    const coreFolderId = await ensureCoreFolderExists();
+    const existingAgentNames = await loadExistingActiveAgentNames();
+    const createdAgentNames: Array<string> = [];
+
+    for (const [index, coreAgentBook] of coreAgentBooks.entries()) {
+        const agentName = parseCoreAgentName(coreAgentBook);
+
+        if (existingAgentNames.has(agentName)) {
+            continue;
+        }
+
+        const createdAgent = await collection.createAgent(coreAgentBook, {
+            folderId: coreFolderId,
+            sortOrder: index,
+            visibility: DEFAULT_AGENT_VISIBILITY,
+        });
+        createdAgentNames.push(createdAgent.agentName);
+        logger.info(`Created \`.core\` agent: ${createdAgent.agentName}`);
+    }
+
+    return { coreFolderId, createdAgentNames };
+}
+
+/**
+ * Reads the agent name from one bundled `.core` book source.
+ *
+ * @param coreAgentBook - Raw `.core` agent book source.
+ * @returns Persisted agent name parsed from the book.
+ *
+ * @private utility of `.core` folder seeding
+ */
+function parseCoreAgentName(coreAgentBook: string_book): string {
+    return parseAgentSource(coreAgentBook).agentName;
+}
+
+/**
+ * Reads the set of active agent names already persisted on the current server.
+ *
+ * @returns Set of active agent names indexed for quick lookups.
+ *
+ * @private utility of `.core` folder seeding
+ */
+async function loadExistingActiveAgentNames(): Promise<Set<string>> {
+    const supabase = $provideSupabaseForServer();
+    const agentTableName = await $getTableName('Agent');
+    const selectResult = await supabase
+        .from(agentTableName)
+        .select('agentName')
+        .is('deletedAt', null);
+
+    if (selectResult.error) {
+        throw new DatabaseError(
+            spaceTrim(
+                (block) => `
+                    Failed to read active agents before seeding \`.core\` agents:
+
+                    ${block(selectResult.error.message)}
+                `,
+            ),
+        );
+    }
+
+    const existingAgentNames = new Set<string>();
+    for (const row of (selectResult.data || []) as Array<{ agentName: string }>) {
+        existingAgentNames.add(row.agentName);
+    }
+    return existingAgentNames;
+}
+
+/**
+ * Ensures the `.core` folder exists at the root and returns its identifier.
+ *
+ * @returns Persisted `.core` folder identifier.
+ *
+ * @private utility of `.core` folder seeding
+ */
+async function ensureCoreFolderExists(): Promise<number> {
+    const supabase = $provideSupabaseForServer();
+    const folderTableName = await $getTableName('AgentFolder');
+
+    const existingFolderResult = await supabase
+        .from(folderTableName)
+        .select('id')
+        .eq('name', CORE_AGENT_DIRECTORY_NAME)
+        .is('parentId', null)
+        .is('deletedAt', null)
+        .maybeSingle();
+
+    if (existingFolderResult.error) {
+        throw new DatabaseError(
+            spaceTrim(
+                (block) => `
+                    Failed to read the \`${CORE_AGENT_DIRECTORY_NAME}\` folder before seeding core agents:
+
+                    ${block(existingFolderResult.error.message)}
+                `,
+            ),
+        );
+    }
+
+    if (existingFolderResult.data) {
+        return (existingFolderResult.data as { id: number }).id;
+    }
+
+    const insertFolderResult = await supabase
+        .from(folderTableName)
+        .insert({
+            name: CORE_AGENT_DIRECTORY_NAME,
+            parentId: null,
+            sortOrder: 0,
+            icon: null,
+            color: null,
+            createdAt: new Date().toISOString(),
+            updatedAt: null,
+        } as never)
+        .select('id')
+        .maybeSingle();
+
+    if (insertFolderResult.error || !insertFolderResult.data) {
+        throw new DatabaseError(
+            spaceTrim(
+                (block) => `
+                    Failed to create the \`${CORE_AGENT_DIRECTORY_NAME}\` folder while seeding core agents:
+
+                    ${block(
+                        insertFolderResult.error?.message ||
+                            `The database did not return the created \`${CORE_AGENT_DIRECTORY_NAME}\` folder.`,
+                    )}
+                `,
+            ),
+        );
+    }
+
+    return (insertFolderResult.data as { id: number }).id;
+}
+
+/**
+ * Resolves the Supabase-shaped client for the Agent collection subset.
+ *
+ * @returns Supabase client typed for agent collection persistence.
+ *
+ * @private utility of `.core` folder seeding
+ */
+function resolveAgentsDatabaseSupabaseClient(): SupabaseClient<AgentsDatabaseSchema> {
+    return $provideSupabaseForServer() as unknown as SupabaseClient<AgentsDatabaseSchema>;
+}

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

@@ -5,6 +5,7 @@ import { $provideSupabaseForServer } from './$provideSupabaseForServer';
 import { DEFAULT_AGENT_VISIBILITY } from '../utils/agentVisibility';
 import { loadDefaultAgentBooks } from '../utils/defaultAgents/loadDefaultAgentBooks';
 import { loadAgentsServerEnvFile } from './loadAgentsServerEnvFile';
+import { seedCoreAgents } from './seedCoreAgents';
 
 /**
  * Environment variable with an explicit default-agent source directory.
@@ -93,6 +94,36 @@ export async function seedDefaultAgents(options: SeedDefaultAgentsOptions = {}):
     const logger = options.logger ?? console;
     const tablePrefix = options.tablePrefix ?? process.env[SUPABASE_TABLE_PREFIX_ENV_NAME] ?? '';
     const collection = new AgentCollectionInSupabase(resolveAgentsDatabaseSupabaseClient(), { tablePrefix });
+    const defaultAgentDirectory = options.defaultAgentDirectory ?? process.env[DEFAULT_AGENTS_DIRECTORY_ENV_NAME];
+
+    const result = await seedDefaultAgentBooks(collection, { defaultAgentDirectory, logger });
+
+    await seedCoreAgents({
+        defaultAgentDirectory,
+        tablePrefix,
+        logger,
+    });
+
+    return result;
+}
+
+/**
+ * Inserts the bundled top-level default agent books when the server is empty.
+ *
+ * @param collection - Agent collection bound to the current table prefix.
+ * @param options - Seeding context shared with `seedDefaultAgents`.
+ * @returns Seed summary for default agents only (core agents are tracked separately).
+ *
+ * @private utility of standalone default-agent seeding
+ */
+async function seedDefaultAgentBooks(
+    collection: AgentCollectionInSupabase,
+    options: {
+        readonly defaultAgentDirectory: string | undefined;
+        readonly logger: SeedDefaultAgentsLogger;
+    },
+): Promise<SeedDefaultAgentsResult> {
+    const { defaultAgentDirectory, logger } = options;
     const existingAgentCount = await countExistingAgents(collection);
 
     if (existingAgentCount > 0) {
@@ -111,7 +142,7 @@ export async function seedDefaultAgents(options: SeedDefaultAgentsOptions = {}):
     }
 
     const defaultAgentBooks = await loadDefaultAgentBooks({
-        defaultAgentDirectory: options.defaultAgentDirectory ?? process.env[DEFAULT_AGENTS_DIRECTORY_ENV_NAME],
+        defaultAgentDirectory,
     });
 
     if (defaultAgentBooks.length === 0) {

package/apps/agents-server/src/search/createDefaultServerSearchProviders/createFederatedAgentsSearchProvider.ts

@@ -30,7 +30,7 @@ export function createFederatedAgentsSearchProvider(): ServerSearchProvider {
 
             let federatedServers: string[] = [];
             try {
-                federatedServers = await getFederatedServers({ excludeHiddenCoreServer: true });
+                federatedServers = await getFederatedServers();
             } catch (error) {
                 console.error('[search] Failed to load federated servers:', error);
                 return [];

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

@@ -36,7 +36,7 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
     */
 
     const supabase = $provideSupabaseForServer();
-    const { publicUrl, tablePrefix } = await $provideServer();
+    const { tablePrefix } = await $provideServer();
     const cachedAgentCollection = agentCollectionsByTablePrefix.get(tablePrefix);
 
     if (cachedAgentCollection) {
@@ -50,16 +50,9 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
 
     agentCollectionsByTablePrefix.set(tablePrefix, providedCollection);
 
-    const [{ attachAgentPreparationScheduling }, { scheduleDefaultFederatedAgentsSync }] = await Promise.all([
-        import('../utils/attachAgentPreparationScheduling'),
-        import('../utils/defaultFederatedAgents/scheduleDefaultFederatedAgentsSync'),
-    ]);
+    const { attachAgentPreparationScheduling } = await import('../utils/attachAgentPreparationScheduling');
 
     attachAgentPreparationScheduling(providedCollection, { tablePrefix });
-    scheduleDefaultFederatedAgentsSync({
-        tablePrefix,
-        localServerUrl: publicUrl.href,
-    });
 
     return providedCollection;
 }

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

@@ -69,9 +69,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     const tableName = await $getTableName('Agent');
     const { data, error } = await supabase
         .from(tableName)
-        .select(
-            'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId',
-        )
+        .select(OWNED_AGENT_ROW_COLUMNS)
         .eq('userId', userId as never)
         .or(buildAgentNameOrIdFilter(identifier))
         .limit(10);
@@ -80,7 +78,58 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
         throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
     }
 
-    const rows = (data || []) as unknown as OwnedAgentRow[];
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'for this owner');
+}
+
+/**
+ * Loads one agent by permanent id or agent name without an owner restriction.
+ *
+ * Owner-aware callers should use {@link findOwnedAgentByIdentifier}; this helper is reserved for administrative
+ * overrides where the caller has been independently authorized to read or mutate any agent.
+ *
+ * @param identifier - Permanent id or agent name.
+ * @returns Matching agent row or `null` when nothing matches.
+ */
+export async function findAgentByIdentifier(identifier: string): Promise<OwnedAgentRow | null> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(OWNED_AGENT_ROW_COLUMNS)
+        .or(buildAgentNameOrIdFilter(identifier))
+        .limit(10);
+
+    if (error) {
+        throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
+    }
+
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'across agents');
+}
+
+/**
+ * Database columns selected for every agent row exposed by ownership-aware helpers.
+ */
+const OWNED_AGENT_ROW_COLUMNS =
+    'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId';
+
+/**
+ * Disambiguates a list of agent rows that all matched the same identifier.
+ *
+ * Resolution order:
+ * 1. Exact `permanentId` match — always preferred because permanent ids are unique.
+ * 2. Single `agentName` match — preserves the legacy lookup by human-readable name.
+ * 3. Single remaining row — accepts the only candidate found.
+ *
+ * @param rows - Candidate agent rows returned by Supabase.
+ * @param identifier - Identifier that was searched.
+ * @param ambiguityScope - Human-readable scope used in the ambiguity error message.
+ * @returns Best-matching row or `null` when no candidate matches.
+ */
+function pickAgentRowByIdentifier(
+    rows: OwnedAgentRow[],
+    identifier: string,
+    ambiguityScope: string,
+): OwnedAgentRow | null {
     if (rows.length === 0) {
         return null;
     }
@@ -100,7 +149,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     }
 
     throw new Error(
-        `Agent identifier "${identifier}" is ambiguous for this owner. Use the stable \`permanentId\` returned by the API.`,
+        `Agent identifier "${identifier}" is ambiguous ${ambiguityScope}. Use the stable \`permanentId\` returned by the API.`,
     );
 }
 

package/apps/agents-server/src/utils/agentsTransfer/createAgentsExportZipStream.ts

@@ -0,0 +1,68 @@
+import JSZip from 'jszip';
+import { getMetadata } from '../../database/getMetadata';
+import { appendBooksBackupEntriesToZip, type BooksBackupZipStream } from '../backup/createBooksBackupZipStream';
+
+/**
+ * Metadata key used for the human-readable server name.
+ */
+const SERVER_NAME_METADATA_KEY = 'SERVER_NAME';
+
+/**
+ * Filename suffix used for agents-only exports.
+ */
+const AGENTS_EXPORT_FILENAME_SUFFIX = '.agents.zip';
+
+/**
+ * Fallback server filename stem when metadata does not provide a usable name.
+ */
+const DEFAULT_AGENTS_EXPORT_FILENAME_STEM = 'promptbook-agents-server';
+
+/**
+ * Pattern matching non-alphanumeric filename slug separators.
+ */
+const FILENAME_SLUG_SEPARATOR_PATTERN = /[^a-z0-9]+/g;
+
+/**
+ * Pattern matching leading or trailing filename slug separators.
+ */
+const FILENAME_SLUG_EDGE_SEPARATOR_PATTERN = /^-+|-+$/g;
+
+/**
+ * Builds a ZIP stream containing only agent books organized by folder structure.
+ *
+ * @returns Download filename and stream payload.
+ */
+export async function createAgentsExportZipStream(): Promise<BooksBackupZipStream> {
+    const serverName = await getMetadata(SERVER_NAME_METADATA_KEY);
+    const zip = new JSZip();
+
+    await appendBooksBackupEntriesToZip(zip, '');
+
+    const stream = zip.generateNodeStream({
+        streamFiles: true,
+        compression: 'DEFLATE',
+        compressionOptions: { level: 6 },
+    });
+
+    return {
+        filename: `${createAgentsExportFilenameStem(serverName)}${AGENTS_EXPORT_FILENAME_SUFFIX}`,
+        stream,
+    };
+}
+
+/**
+ * Creates a safe lowercase filename stem from server metadata.
+ *
+ * @param serverName - Raw server name from metadata.
+ * @returns Filename stem for the agents export.
+ */
+export function createAgentsExportFilenameStem(serverName: string | null | undefined): string {
+    const normalizedServerName = typeof serverName === 'string' ? serverName.trim().toLowerCase() : '';
+    const filenameStem = normalizedServerName
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(FILENAME_SLUG_SEPARATOR_PATTERN, '-')
+        .replace(FILENAME_SLUG_EDGE_SEPARATOR_PATTERN, '');
+
+    return filenameStem || DEFAULT_AGENTS_EXPORT_FILENAME_STEM;
+}