@promptbook/cli 0.112.0-103 → 0.112.0-104

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

@@ -0,0 +1,168 @@
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import type { AgentBasicInformation, AgentCollection, string_book } from '@promptbook-local/types';
+import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
+import { DEFAULT_AGENT_VISIBILITY } from '../agentVisibility';
+
+/**
+ * Installation status for one default agent book.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export type DefaultAgentInstallStatus = 'installed' | 'skipped';
+
+/**
+ * Result for one processed default agent book.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export type DefaultAgentInstallRecord = {
+    /**
+     * Source book filename.
+     */
+    readonly fileName: string;
+
+    /**
+     * Parsed canonical agent name.
+     */
+    readonly agentName: string;
+
+    /**
+     * Whether the agent was created or skipped because an active agent with the same name already exists.
+     */
+    readonly status: DefaultAgentInstallStatus;
+
+    /**
+     * Permanent id of the newly created agent, if created.
+     */
+    readonly permanentId?: string;
+};
+
+/**
+ * Aggregate default-agent installation result.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export type DefaultAgentInstallResult = {
+    /**
+     * Number of newly created agents.
+     */
+    readonly installedCount: number;
+
+    /**
+     * Number of already-present agents skipped by name.
+     */
+    readonly skippedCount: number;
+
+    /**
+     * Per-book processing records.
+     */
+    readonly records: ReadonlyArray<DefaultAgentInstallRecord>;
+};
+
+/**
+ * Options for installing default agents from a directory.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export type InstallDefaultAgentsFromDirectoryOptions = {
+    /**
+     * Agent collection used for persistence.
+     */
+    readonly collection: AgentCollection;
+
+    /**
+     * Directory containing the repository default `*.book` files.
+     */
+    readonly defaultAgentsDirectoryPath: string;
+
+    /**
+     * Optional logger for install-time progress.
+     */
+    readonly logger?: Pick<Console, 'info'>;
+};
+
+/**
+ * Lists repository default book filenames in stable install order.
+ *
+ * @param defaultAgentsDirectoryPath - Directory containing default `*.book` files.
+ * @returns Sorted book filenames.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export async function listDefaultAgentBookFileNames(defaultAgentsDirectoryPath: string): Promise<ReadonlyArray<string>> {
+    const directoryEntries = await readdir(defaultAgentsDirectoryPath, { withFileTypes: true });
+
+    return directoryEntries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.book'))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Creates default agents from repository `*.book` files, skipping already-active agents with matching names.
+ *
+ * @param options - Installation options.
+ * @returns Aggregate installation result.
+ *
+ * @private shared utility for Agents Server default-agent installation
+ */
+export async function installDefaultAgentsFromDirectory(
+    options: InstallDefaultAgentsFromDirectoryOptions,
+): Promise<DefaultAgentInstallResult> {
+    const fileNames = await listDefaultAgentBookFileNames(options.defaultAgentsDirectoryPath);
+    const existingAgentNames = new Set((await options.collection.listAgents()).map((agent) => agent.agentName));
+    const records: Array<DefaultAgentInstallRecord> = [];
+
+    for (const [index, fileName] of fileNames.entries()) {
+        const agentSource = (await readFile(join(options.defaultAgentsDirectoryPath, fileName), 'utf-8')) as string_book;
+        const parsedAgentProfile = parseAgentSource(agentSource);
+        const agentName = parsedAgentProfile.agentName;
+
+        if (existingAgentNames.has(agentName)) {
+            options.logger?.info(`[default-agents] Skipping existing agent "${agentName}" from ${fileName}.`);
+            records.push({
+                fileName,
+                agentName,
+                status: 'skipped',
+            });
+            continue;
+        }
+
+        const createdAgent = await options.collection.createAgent(agentSource, {
+            sortOrder: index + 1,
+            visibility: DEFAULT_AGENT_VISIBILITY,
+        });
+
+        existingAgentNames.add(createdAgent.agentName);
+        options.logger?.info(`[default-agents] Installed "${createdAgent.agentName}" from ${fileName}.`);
+        records.push(createInstalledDefaultAgentRecord(fileName, createdAgent));
+    }
+
+    return {
+        installedCount: records.filter((record) => record.status === 'installed').length,
+        skippedCount: records.filter((record) => record.status === 'skipped').length,
+        records,
+    };
+}
+
+/**
+ * Creates a typed result record for a newly installed default agent.
+ *
+ * @param fileName - Source book filename.
+ * @param createdAgent - Created agent profile returned by the collection.
+ * @returns Installation record.
+ *
+ * @private utility of `installDefaultAgentsFromDirectory`
+ */
+function createInstalledDefaultAgentRecord(
+    fileName: string,
+    createdAgent: AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>,
+): DefaultAgentInstallRecord {
+    return {
+        fileName,
+        agentName: createdAgent.agentName,
+        status: 'installed',
+        permanentId: createdAgent.permanentId,
+    };
+}

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

@@ -0,0 +1,139 @@
+import * as dotenv from 'dotenv';
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+import { AgentCollectionInSupabase } from '../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase';
+import type { AgentCollection } from '../../../../../src/collection/agent-collection/AgentCollection';
+import { isAgentsServerSqliteMode } from '../../database/agentsServerDatabaseMode';
+import { $provideLocalSqliteSupabase } from '../../database/sqlite/$provideLocalSqliteSupabase';
+import { installDefaultAgentsFromDirectory } from './defaultAgents';
+
+/**
+ * Environment variable pointing to the installed Agents Server `.env` file.
+ *
+ * @private install-time default-agent utility
+ */
+const AGENTS_SERVER_ENV_FILE_ENV_NAME = 'PTBK_AGENTS_SERVER_ENV_FILE';
+
+/**
+ * Environment variable pointing to the repository `agents/default` directory.
+ *
+ * @private install-time default-agent utility
+ */
+const DEFAULT_AGENTS_DIRECTORY_ENV_NAME = 'PTBK_DEFAULT_AGENTS_DIR';
+
+/**
+ * Environment variable containing the current server table prefix.
+ *
+ * @private install-time default-agent utility
+ */
+const SUPABASE_TABLE_PREFIX_ENV_NAME = 'SUPABASE_TABLE_PREFIX';
+
+/**
+ * Public Supabase URL environment variable.
+ *
+ * @private install-time default-agent utility
+ */
+const NEXT_PUBLIC_SUPABASE_URL_ENV_NAME = 'NEXT_PUBLIC_SUPABASE_URL';
+
+/**
+ * Supabase service role key environment variable.
+ *
+ * @private install-time default-agent utility
+ */
+const SUPABASE_SERVICE_ROLE_KEY_ENV_NAME = 'SUPABASE_SERVICE_ROLE_KEY';
+
+/**
+ * Public Supabase anon key environment variable used as a fallback when service role is unavailable.
+ *
+ * @private install-time default-agent utility
+ */
+const NEXT_PUBLIC_SUPABASE_ANON_KEY_ENV_NAME = 'NEXT_PUBLIC_SUPABASE_ANON_KEY';
+
+/**
+ * Loads the installed Agents Server environment for the detached installer script.
+ *
+ * @private install-time default-agent utility
+ */
+function loadDefaultAgentInstallEnvironment(): 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();
+}
+
+/**
+ * Creates the install-time agent collection using the same database backend as the server.
+ *
+ * @returns Agent collection bound to the configured table prefix.
+ *
+ * @private install-time default-agent utility
+ */
+function createDefaultAgentInstallCollection(): AgentCollection {
+    return new AgentCollectionInSupabase(createDefaultAgentInstallSupabaseClient(), {
+        tablePrefix: process.env[SUPABASE_TABLE_PREFIX_ENV_NAME] || '',
+    });
+}
+
+/**
+ * Creates the Supabase-shaped client used by the install-time agent collection.
+ *
+ * @returns Supabase or local SQLite client.
+ *
+ * @private install-time default-agent utility
+ */
+function createDefaultAgentInstallSupabaseClient(): SupabaseClient {
+    if (isAgentsServerSqliteMode()) {
+        return $provideLocalSqliteSupabase();
+    }
+
+    const supabaseUrl = process.env[NEXT_PUBLIC_SUPABASE_URL_ENV_NAME];
+    const supabaseKey =
+        process.env[SUPABASE_SERVICE_ROLE_KEY_ENV_NAME] || process.env[NEXT_PUBLIC_SUPABASE_ANON_KEY_ENV_NAME];
+
+    if (!supabaseUrl || !supabaseKey) {
+        throw new Error(
+            `Missing \`${NEXT_PUBLIC_SUPABASE_URL_ENV_NAME}\` and \`${SUPABASE_SERVICE_ROLE_KEY_ENV_NAME}\` for Supabase default-agent installation.`,
+        );
+    }
+
+    return createClient(supabaseUrl, supabaseKey, {
+        auth: {
+            autoRefreshToken: false,
+            persistSession: false,
+        },
+    });
+}
+
+/**
+ * Runs the default-agent install command.
+ *
+ * @private install-time default-agent utility
+ */
+async function installDefaultAgents(): Promise<void> {
+    loadDefaultAgentInstallEnvironment();
+
+    const defaultAgentsDirectoryPath = process.env[DEFAULT_AGENTS_DIRECTORY_ENV_NAME]?.trim();
+    if (!defaultAgentsDirectoryPath) {
+        throw new Error(`Missing \`${DEFAULT_AGENTS_DIRECTORY_ENV_NAME}\` environment variable.`);
+    }
+
+    const result = await installDefaultAgentsFromDirectory({
+        collection: createDefaultAgentInstallCollection(),
+        defaultAgentsDirectoryPath,
+        logger: console,
+    });
+
+    console.info(
+        `[default-agents] Finished. Installed ${result.installedCount}, skipped ${result.skippedCount}.`,
+    );
+}
+
+installDefaultAgents().catch((error) => {
+    console.error('[default-agents] Failed to install default agents.');
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});