@promptbook/cli 0.112.0-135 → 0.112.0-137

package/apps/agents-server/src/components/Homepage/useAgentsListState.ts

@@ -15,6 +15,7 @@ import {
 } from './useAgentsListDragState';
 import { useAgentsListFolderPathRecovery } from './useAgentsListFolderPathRecovery';
 import { useAgentsListFolderState } from './useAgentsListFolderState';
+import { useAgentsListImportExportState } from './useAgentsListImportExportState';
 import { useAgentsListNavigationState } from './useAgentsListNavigationState';
 import { useAgentsListOrganizationActions } from './useAgentsListOrganizationActions';
 import { useAgentsListOverlayDetailsState } from './useAgentsListOverlayDetailsState';
@@ -166,6 +167,10 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         setFolders,
         synchronizeAfterMutation,
     });
+    const importExportState = useAgentsListImportExportState({
+        currentFolderId,
+        synchronizeAfterMutation,
+    });
     const agentState = useAgentsListAgentState({
         agents,
         formatText,
@@ -255,6 +260,13 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         handleDragEnd: dragState.handleDragEnd,
         handleDragOver: dragState.handleDragOver,
         handleDragStart: dragState.handleDragStart,
+        handleAgentsExport: importExportState.handleAgentsExport,
+        handleAgentsFileDragEnter: importExportState.handleAgentsFileDragEnter,
+        handleAgentsFileDragLeave: importExportState.handleAgentsFileDragLeave,
+        handleAgentsFileDragOver: importExportState.handleAgentsFileDragOver,
+        handleAgentsFileDrop: importExportState.handleAgentsFileDrop,
+        handleAgentsImportClick: importExportState.handleAgentsImportClick,
+        handleAgentsImportFileChange: importExportState.handleAgentsImportFileChange,
         handleFolderContextMenu: overlayState.handleFolderContextMenu,
         handleRenameFolder: folderState.handleRenameFolder,
         handleRequestAgentVisibilityChange: agentState.handleRequestAgentVisibilityChange,
@@ -262,6 +274,10 @@ export function useAgentsListState(props: UseAgentsListStateProps) {
         handleShowQrCode: overlayState.handleShowQrCode,
         handleSubmitFolderEdit: folderState.handleSubmitFolderEdit,
         headingTitle,
+        importFileInputRef: importExportState.importFileInputRef,
+        isAgentsExporting: importExportState.isAgentsExporting,
+        isAgentsImportDragActive: importExportState.isAgentsImportDragActive,
+        isAgentsImporting: importExportState.isAgentsImporting,
         isFolderEditSubmitting: folderState.isFolderEditSubmitting,
         navigateToFolder,
         mazeAgents,

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

@@ -1,5 +1,3 @@
-import { spaceTrim } from 'spacetrim';
-import { CORE_AGENTS_SERVER } from '../../../../servers';
 import { DEFAULT_THINKING_MESSAGES } from '../../../../src/utils/DEFAULT_THINKING_MESSAGES';
 import { ANALYTICS_METADATA_KEYS, getAnalyticsMetadataDefinition } from '../constants/analyticsMetadata';
 import {
@@ -263,25 +261,6 @@ export const metadataDefaults: ReadonlyArray<MetadataDefinition> = [
         note: 'Comma separated list of allowed IPs or CIDR ranges. If set, only clients from these IPs are allowed to access the server.',
         type: 'IP_RANGE',
     },
-    {
-        key: 'CORE_SERVER',
-        value: CORE_AGENTS_SERVER.url,
-        note: spaceTrim(`
-                Core Promptbook server URL used for agents that are used for common tasks, these agents are called well known agents:
-
-                On the core server, the following well known agents should be hosted: 
-                - \`adam\`: The default ancestor agent for new agents
-                - \`teacher\`: Agent that knows book syntax and can help with self-learning
-            
-            `),
-        type: 'TEXT',
-    },
-    {
-        key: 'IS_CORE_SERVER_HIDDEN',
-        value: 'false',
-        note: 'Hide the core federated server from homepage, navbar, search, and footer links while keeping it available for references when true.',
-        type: 'BOOLEAN',
-    },
     // <- TODO: [🆎] Allow to set well-known agent names via Metadata
 
     {

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/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;
+}