@promptbook/cli 0.112.0-110 → 0.112.0-112

package/esm/src/cli/cli-commands/agents-server/startAgentsServer.d.ts

@@ -29,7 +29,8 @@ export type StartAgentsServerOptions = {
  */
 export declare function startAgentsServer(options: StartAgentsServerOptions): Promise<void>;
 /**
- * Loads launch-directory `.env` values without overriding explicit process environment.
+ * Loads Agents Server runtime environment from the installed `.env` file when explicitly configured and falls back
+ * to the launch-directory `.env`.
  *
  * @private internal utility of `ptbk agents-server`
  */

package/esm/src/cli/cli-commands/agents-server/startAgentsServer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -60,6 +60,28 @@ export declare class AgentCollectionInSupabase {
      * Gets all agents in the collection
      */
     listAgents(): Promise<ReadonlyArray<AgentBasicInformation>>;
+    /**
+     * Finds one active agent profile by its human-readable name or permanent id.
+     *
+     * This keeps route-level lookups from loading the whole agent collection when only
+     * one canonical route identifier is needed.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier.
+     * @returns Matching active agent profile or `null` when not found.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    findAgentBasicInformation(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<AgentBasicInformation | null>;
+    /**
+     * Converts one database row into public agent information.
+     *
+     * @param row - Database row carrying the persisted profile snapshot.
+     * @param isVerbose - Whether profile-name mismatches should be logged.
+     * @returns Agent profile with canonical database name and permanent id.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
      */

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-109`).
+ * It follows semantic versioning (e.g., `0.112.0-111`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-110",
+    "version": "0.112.0-112",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/cli/cli-commands/agents-server/startAgentsServer.ts

@@ -107,6 +107,13 @@ const PTBK_AGENTS_SERVER_SQLITE_PATH_ENV = 'PTBK_AGENTS_SERVER_SQLITE_PATH';
  */
 const PTBK_HOSTNAME_ENV = 'PTBK_HOSTNAME';
 
+/**
+ * Explicit installed `.env` file passed by standalone VPS pm2/runtime launchers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const PTBK_AGENTS_SERVER_ENV_FILE_ENV = 'PTBK_AGENTS_SERVER_ENV_FILE';
+
 /**
  * Entropy size for the local-only token shared by the CLI pump and the Next app.
  *
@@ -355,11 +362,20 @@ async function prepareAgentsServerDevelopmentRuntime(
 }
 
 /**
- * Loads launch-directory `.env` values without overriding explicit process environment.
+ * Loads Agents Server runtime environment from the installed `.env` file when explicitly configured and falls back
+ * to the launch-directory `.env`.
  *
  * @private internal utility of `ptbk agents-server`
  */
 export function loadAgentsServerProjectEnvironment(launchWorkingDirectory: string): void {
+    const explicitEnvFilePath = process.env[PTBK_AGENTS_SERVER_ENV_FILE_ENV]?.trim();
+    if (explicitEnvFilePath) {
+        const explicitLoadResult = dotenv.config({ path: explicitEnvFilePath, override: true });
+        if (!explicitLoadResult.error) {
+            return;
+        }
+    }
+
     dotenv.config({ path: join(launchWorkingDirectory, AGENTS_SERVER_PROJECT_ENV_FILE_NAME) });
 }
 
@@ -398,7 +414,12 @@ function startNextServer(options: {
         options.logStreams.runner,
         `Starting the Agents Server Next process in ${nextRuntimeModeLabel} mode.`,
     );
-    const nextArguments = [options.nextCliPath, options.options.nextRuntimeMode, '--port', String(options.options.port)];
+    const nextArguments = [
+        options.nextCliPath,
+        options.options.nextRuntimeMode,
+        '--port',
+        String(options.options.port),
+    ];
     const hostname = options.childEnvironment[PTBK_HOSTNAME_ENV]?.trim();
 
     if (hostname) {

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.ts

@@ -49,6 +49,19 @@ function normalizeHistoryVersionName(versionName: string | null | undefined): st
     return normalizedVersionName.length > 0 ? normalizedVersionName : null;
 }
 
+/**
+ * Builds a Supabase `.or()` filter for agent name or permanent id lookups.
+ *
+ * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+ * @returns `.or()` filter string safe to pass to Supabase.
+ *
+ * @private internal helper of `AgentCollectionInSupabase`
+ */
+function buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId: string): string {
+    const encodedAgentIdentifier = encodeURIComponent(agentNameOrPermanentId);
+    return `agentName.eq.${encodedAgentIdentifier},permanentId.eq.${encodedAgentIdentifier}`;
+}
+
 /**
  * One saved Agent history row without the full source payload.
  */
@@ -69,6 +82,16 @@ type AgentHistorySnapshot = AgentHistoryMetadata & {
     readonly agentSource: string;
 };
 
+/**
+ * Minimal database row used to build public agent information.
+ *
+ * @private internal type of `AgentCollectionInSupabase`
+ */
+type AgentBasicInformationRow = Pick<
+    AgentsDatabaseSchema['public']['Tables']['Agent']['Row'],
+    'agentName' | 'agentProfile' | 'permanentId'
+>;
+
 /**
  * Agent collection stored in a Supabase table.
  *
@@ -127,24 +150,78 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
             console.info(`Found ${selectResult.data.length} agents in directory`);
         }
 
-        return selectResult.data.map(({ agentName, agentProfile, permanentId }) => {
-            if (isVerbose && (agentProfile as AgentBasicInformation).agentName !== agentName) {
-                console.warn(
-                    spaceTrim(`
+        return selectResult.data.map((row) => this.mapAgentBasicInformationRow(row, isVerbose));
+    }
+
+    /**
+     * Finds one active agent profile by its human-readable name or permanent id.
+     *
+     * This keeps route-level lookups from loading the whole agent collection when only
+     * one canonical route identifier is needed.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier.
+     * @returns Matching active agent profile or `null` when not found.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    public async findAgentBasicInformation(
+        agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
+    ): Promise<AgentBasicInformation | null> {
+        const { isVerbose = DEFAULT_IS_VERBOSE } = this.options || {};
+        const selectResult = await this.supabaseClient
+            .from(this.getTableName('Agent'))
+            .select('agentName,agentProfile,permanentId')
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
+            .is('deletedAt', null)
+            .order('createdAt', { ascending: true })
+            .limit(1);
+
+        if (selectResult.error) {
+            throw new DatabaseError(
+                spaceTrim(
+                    (block) => `
+
+                        Error fetching agent "${agentNameOrPermanentId}" from Supabase:
+
+                        ${block(selectResult.error.message)}
+                    `,
+                ),
+            );
+        }
+
+        const row = selectResult.data?.[0];
+        return row ? this.mapAgentBasicInformationRow(row, isVerbose) : null;
+    }
+
+    /**
+     * Converts one database row into public agent information.
+     *
+     * @param row - Database row carrying the persisted profile snapshot.
+     * @param isVerbose - Whether profile-name mismatches should be logged.
+     * @returns Agent profile with canonical database name and permanent id.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private mapAgentBasicInformationRow(
+        { agentName, agentProfile, permanentId }: AgentBasicInformationRow,
+        isVerbose: boolean,
+    ): AgentBasicInformation {
+        if (isVerbose && (agentProfile as AgentBasicInformation).agentName !== agentName) {
+            console.warn(
+                spaceTrim(`
                         Agent name mismatch for agent "${agentName}". Using name from database.
 
                         agentName: "${agentName}"
                         agentProfile.agentName: "${(agentProfile as AgentBasicInformation).agentName}"
                     `),
-                );
-            }
+            );
+        }
 
-            return {
-                ...(agentProfile as AgentBasicInformation),
-                agentName,
-                permanentId: permanentId || (agentProfile as AgentBasicInformation).permanentId,
-            };
-        });
+        return {
+            ...(agentProfile as AgentBasicInformation),
+            agentName,
+            permanentId: permanentId || (agentProfile as AgentBasicInformation).permanentId,
+        };
     }
 
     /**
@@ -156,7 +233,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const selectResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('permanentId')
-            .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);
 
@@ -175,7 +252,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const selectResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('agentSource')
-            .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
             .is('deletedAt', null)
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);