@promptbook/cli 0.113.0-4 → 0.113.0-6

package/apps/agents-server/src/app/agents/[agentName]/api/book/route.ts

@@ -8,6 +8,7 @@ import {
 import { loadFederatedAgentImportConfiguration } from '@/src/utils/federatedAgentImportConfiguration';
 import { getCurrentUser } from '@/src/utils/getCurrentUser';
 import { getWellKnownAgentUrl } from '@/src/utils/getWellKnownAgentUrl';
+import { createLocalAgentSourceImporter } from '@/src/utils/createLocalAgentSourceImporter';
 import { resolveInheritedAgentSource } from '@/src/utils/resolveInheritedAgentSource';
 import { padBook, validateBook } from '@promptbook-local/core';
 import type { string_agent_url } from '@promptbook-local/types';
@@ -96,13 +97,24 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         const agentSource = resolvedAgentContext.unresolvedAgentSource;
         const agentReferenceResolver = resolvedAgentContext.scopedAgentReferenceResolver;
         const federatedAgentImportConfiguration = await loadFederatedAgentImportConfiguration();
+        const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+        const localServerUrl = new URL(request.url).origin;
+        const agentSourceImporter = createLocalAgentSourceImporter({
+            collection,
+            localServerUrls: [localServerUrl],
+            localAgentUrls: [adamAgentUrl],
+            adamAgentUrl,
+            fallbackResolver: baseAgentReferenceResolver,
+            federatedAgentImportConfiguration,
+        });
         const effectiveAgentSource = await resolveInheritedAgentSource(agentSource, {
-            adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+            adamAgentUrl,
             recursionLevel,
             currentAgentUrl: resolvedAgentContext.canonicalAgentUrl,
             inheritancePath: inheritancePath as Array<string_agent_url>,
             agentReferenceResolver,
             federatedAgentImportConfiguration,
+            agentSourceImporter,
         });
         const etag = `W/"${computeHash(effectiveAgentSource)}"`;
 

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

@@ -2,7 +2,9 @@ import { $getTableName } from '../../database/$getTableName';
 import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../../database/schema';
 import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
 import { $provideAgentReferenceResolver } from '../../utils/agentReferenceResolver/$provideAgentReferenceResolver';
+import { createLocalAgentSourceImporter } from '../../utils/createLocalAgentSourceImporter';
 import { getWellKnownAgentUrl } from '../../utils/getWellKnownAgentUrl';
 import { resolveCurrentOrInternalServerOrigin } from '../../utils/resolveCurrentOrInternalServerOrigin';
 import { resolveStoredAgentStates } from '../../utils/resolveStoredAgentState';
@@ -85,12 +87,21 @@ export async function loadLocalOrganizationSearchDataset(options: {
     const folders = (folderResult.data || []) as AgentFolderSearchRow[];
     const localServerUrl = await resolveCurrentOrInternalServerOrigin();
     const agentReferenceResolver = await $provideAgentReferenceResolver();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: await $provideAgentCollectionForServer(),
+        localServerUrls: [localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
     const resolvedAgents = await resolveStoredAgentStates(
         (agentResult.data || []) as Array<Pick<AgentSearchRow, 'id' | 'agentName' | 'permanentId' | 'agentSource' | 'folderId' | 'visibility'>>,
         {
             localServerUrl,
-            adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+            adamAgentUrl,
             agentReferenceResolver,
+            agentSourceImporter,
         },
     );
     const agents = resolvedAgents.map((agent) => ({

package/apps/agents-server/src/utils/agentOrganization/loadAgentOrganizationState.ts

@@ -2,7 +2,9 @@ import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-so
 import { $getTableName } from '../../database/$getTableName';
 import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../../database/schema';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
 import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provideAgentReferenceResolver';
+import { createLocalAgentSourceImporter } from '../createLocalAgentSourceImporter';
 import { getCurrentUser } from '../getCurrentUser';
 import { getWellKnownAgentUrl } from '../getWellKnownAgentUrl';
 import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
@@ -187,14 +189,24 @@ async function loadResolvedOrganizationSnapshot(options: {
 
     const localServerUrl = await resolveCurrentOrInternalServerOrigin();
     const agentReferenceResolver = await $provideAgentReferenceResolver();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const collection = await $provideAgentCollectionForServer();
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection,
+        localServerUrls: [localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
     const resolvedAgents = await resolveStoredAgentStates(
         (agentResult.data || []) as Array<
             Pick<AgentRow, 'agentName' | 'agentSource' | 'permanentId' | 'visibility' | 'folderId' | 'sortOrder'>
         >,
         {
             localServerUrl,
-            adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+            adamAgentUrl,
             agentReferenceResolver,
+            agentSourceImporter,
         },
     );
     const agents = resolvedAgents.map((agent) =>

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

@@ -0,0 +1,159 @@
+import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
+import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
+import { DEFAULT_MAX_RECURSION } from '../../../../src/config';
+import { NotFoundError } from '../../../../src/errors/NotFoundError';
+import { ParseError } from '../../../../src/errors/ParseError';
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
+import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
+import {
+    resolveBookScopedAgentContext,
+    type ResolvedBookScopedAgentContext,
+} from './agentReferenceResolver/bookScopedAgentReferences';
+import {
+    createLocalAgentUrl,
+    normalizeLocalAgentUrlReferences,
+    normalizeLocalServerUrls,
+    resolveLocalAgentRouteReference,
+} from './localAgentRouteReferences';
+import { createMissingImportedAgentFallback } from './createMissingImportedAgentFallback';
+import {
+    resolveInheritedAgentSource,
+    type AgentSourceImporter,
+} from './resolveInheritedAgentSource';
+
+/**
+ * Dependencies needed for importing same-instance agent sources without HTTP.
+ */
+export type CreateLocalAgentSourceImporterOptions = {
+    /**
+     * Collection used to load local regular and book-scoped agent sources.
+     */
+    readonly collection: Pick<AgentCollection, 'getAgentPermanentId' | 'getAgentSource'>;
+
+    /**
+     * Server origins that should be treated as this Agents Server instance.
+     */
+    readonly localServerUrls: ReadonlyArray<string>;
+
+    /**
+     * Exact agent URLs that should be treated as local even when their origin is not in `localServerUrls`.
+     */
+    readonly localAgentUrls?: ReadonlyArray<string_agent_url>;
+
+    /**
+     * Adam agent URL used for implicit default inheritance.
+     */
+    readonly adamAgentUrl: string_agent_url;
+
+    /**
+     * Resolver used for compact references that are not book-scoped.
+     */
+    readonly fallbackResolver?: AgentReferenceResolver;
+
+    /**
+     * Retry configuration used when nested imports leave the local server.
+     */
+    readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+};
+
+/**
+ * Creates an importer that loads same-instance agent URLs directly from the collection.
+ *
+ * @param options - Same-instance import dependencies.
+ * @returns Importer suitable for `resolveInheritedAgentSource`.
+ */
+export function createLocalAgentSourceImporter(options: CreateLocalAgentSourceImporterOptions): AgentSourceImporter {
+    const localServerUrls = normalizeLocalServerUrls(options.localServerUrls);
+    const localAgentUrlReferences = normalizeLocalAgentUrlReferences(options.localAgentUrls || []);
+    const localAgentSourceImporter: AgentSourceImporter = async (agentUrl, context) => {
+        const localRouteReference = resolveLocalAgentRouteReference(agentUrl, localServerUrls, localAgentUrlReferences);
+
+        if (!localRouteReference) {
+            return null;
+        }
+
+        const nextRecursionLevel = (context.importAgentOptions.recursionLevel || 0) + 1;
+        assertRecursionLevel(nextRecursionLevel, agentUrl);
+
+        let resolvedAgentContext: ResolvedBookScopedAgentContext;
+
+        try {
+            resolvedAgentContext = await resolveBookScopedAgentContext({
+                collection: options.collection,
+                agentIdentifier: localRouteReference.agentIdentifier,
+                localServerUrl: localRouteReference.localServerUrl,
+                fallbackResolver: options.fallbackResolver,
+            });
+        } catch (error) {
+            if (error instanceof NotFoundError) {
+                return createMissingImportedAgentFallback(agentUrl, 1, error);
+            }
+
+            throw error;
+        }
+
+        return resolveInheritedAgentSource(resolvedAgentContext.unresolvedAgentSource, {
+            adamAgentUrl: options.adamAgentUrl,
+            recursionLevel: nextRecursionLevel,
+            inheritancePath: context.importAgentOptions.inheritancePath,
+            currentAgentUrl: resolvedAgentContext.canonicalAgentUrl,
+            currentAgentAliases: createCurrentAgentAliases(resolvedAgentContext, localServerUrls),
+            agentReferenceResolver: resolvedAgentContext.scopedAgentReferenceResolver,
+            federatedAgentImportConfiguration:
+                options.federatedAgentImportConfiguration || context.federatedAgentImportConfiguration,
+            agentSourceImporter: localAgentSourceImporter,
+        });
+    };
+
+    return localAgentSourceImporter;
+}
+
+/**
+ * Throws when direct local importing would exceed the configured recursion limit.
+ *
+ * @param recursionLevel - Next recursion level.
+ * @param agentUrl - Local agent URL being imported.
+ */
+function assertRecursionLevel(recursionLevel: number, agentUrl: string_agent_url): void {
+    if (recursionLevel <= DEFAULT_MAX_RECURSION) {
+        return;
+    }
+
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Recursion depth ${recursionLevel} exceeds maximum allowed ${DEFAULT_MAX_RECURSION} while importing local agent:
+
+                ${block(agentUrl)}
+            `,
+        ),
+    );
+}
+
+/**
+ * Builds cycle-detection aliases for every same-instance origin.
+ *
+ * @param resolvedAgentContext - Resolved local/book-scoped agent context.
+ * @param localServerUrls - Same-instance server origins.
+ * @returns Unique local URL aliases for the imported agent.
+ */
+function createCurrentAgentAliases(
+    resolvedAgentContext: ResolvedBookScopedAgentContext,
+    localServerUrls: ReadonlyArray<string>,
+): Array<string_agent_url> {
+    const agentIdentifiers = [
+        resolvedAgentContext.canonicalAgentIdentifier,
+        resolvedAgentContext.requestedAgentIdentifier,
+        resolvedAgentContext.resolvedAgentName,
+    ].filter((agentIdentifier, index, agentIdentifierList) => agentIdentifierList.indexOf(agentIdentifier) === index);
+    const agentAliases = new Set<string>(resolvedAgentContext.currentAgentAliases);
+
+    for (const localServerUrl of localServerUrls) {
+        for (const agentIdentifier of agentIdentifiers) {
+            agentAliases.add(createLocalAgentUrl(localServerUrl, agentIdentifier));
+        }
+    }
+
+    return [...agentAliases] as Array<string_agent_url>;
+}

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

@@ -0,0 +1,60 @@
+import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
+import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
+import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
+
+/**
+ * Collapses one thrown error into a single-line message suitable for `NOTE` commitments.
+ *
+ * @param agentUrl - Canonical imported agent URL.
+ * @param error - Unknown error raised while loading the imported agent.
+ * @returns Human-readable single-line failure reason.
+ *
+ * @private internal helper for imported-agent fallback books
+ */
+function normalizeImportFailureMessage(agentUrl: string_agent_url, error: unknown): string {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const normalizedMessage = rawMessage.replace(/\s+/g, ' ').trim();
+    const prefix = `Failed to import agent from "${agentUrl}"`;
+
+    if (normalizedMessage.startsWith(prefix)) {
+        const suffix = normalizedMessage.slice(prefix.length).trim();
+        if (suffix.length > 0) {
+            return suffix.replace(/^[-:,\s]+/, '').trim() || 'unknown error';
+        }
+    }
+
+    return normalizedMessage || 'unknown error';
+}
+
+/**
+ * Creates the ad-hoc fallback source returned when a referenced agent stays unavailable.
+ *
+ * @param agentUrl - Canonical imported agent URL.
+ * @param attempts - Total number of attempts that were used.
+ * @param error - Final error raised by the failed import attempts.
+ * @returns Valid fallback book source.
+ *
+ * @private internal helper for imported-agent fallback books
+ */
+export function createMissingImportedAgentFallback(
+    agentUrl: string_agent_url,
+    attempts: number,
+    error: unknown,
+): string_book {
+    const failureMessage = normalizeImportFailureMessage(agentUrl, error);
+
+    return padBook(
+        validateBook(
+            spaceTrim(
+                `
+                    Not found agent
+
+                    NOTE This agent was supposed to be imported from ${agentUrl}, but it can not be loaded after ${attempts} attempts because of ${failureMessage}
+                    CLOSED
+                `,
+            ),
+        ),
+    );
+}

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

@@ -1,13 +1,30 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
-import type { AgentBasicInformation, string_book } from '../../../../src/_packages/types.index';
+import type {
+    AgentBasicInformation,
+    string_agent_permanent_id,
+    string_agent_url,
+    string_book,
+} from '../../../../src/_packages/types.index';
+import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
 import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
+import { DEFAULT_MAX_RECURSION } from '../../../../src/config';
+import { NotFoundError } from '../../../../src/errors/NotFoundError';
+import { ParseError } from '../../../../src/errors/ParseError';
+import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { normalizeDomainForMatching } from '../../../../src/utils/validators/url/normalizeDomainForMatching';
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
 import { createServerAgentReferenceResolver } from './agentReferenceResolver/createServerAgentReferenceResolver';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getFederatedServers } from './getFederatedServers';
 import { getWellKnownAgentUrl } from './getWellKnownAgentUrl';
-import { resolveInheritedAgentSource } from './resolveInheritedAgentSource';
+import {
+    createLocalAgentUrl,
+    normalizeLocalAgentUrlReferences,
+    normalizeLocalServerUrls,
+    resolveLocalAgentRouteReference,
+} from './localAgentRouteReferences';
+import { createMissingImportedAgentFallback } from './createMissingImportedAgentFallback';
+import { resolveInheritedAgentSource, type AgentSourceImporter } from './resolveInheritedAgentSource';
 import { createServerPublicUrl, type ServerRecord } from './serverRegistry';
 
 /**
@@ -111,11 +128,6 @@ type CustomDomainAgentRow = {
     readonly agentSource: string;
 };
 
-/**
- * Minimal agent identity row used to initialize compact-reference resolution.
- */
-type CustomDomainAgentReferenceRow = Pick<CustomDomainAgentRow, 'agentName' | 'permanentId'>;
-
 /**
  * Minimal resolved metadata needed for custom-domain matching.
  */
@@ -127,7 +139,20 @@ type ResolvedCustomDomainMetadata = Pick<AgentBasicInformation, 'links' | 'meta'
  * @param agents - Stored server-owned agents.
  * @returns Lightweight collection compatible with the resolver initialization step.
  */
-function createResolverAgentCollection(agents: ReadonlyArray<CustomDomainAgentReferenceRow>): AgentCollection {
+function createResolverAgentCollection(agents: ReadonlyArray<CustomDomainAgentRow>): AgentCollection {
+    const resolveAgent = (agentNameOrPermanentId: string): CustomDomainAgentRow => {
+        const agent = agents.find(
+            (candidate) =>
+                candidate.agentName === agentNameOrPermanentId || candidate.permanentId === agentNameOrPermanentId,
+        );
+
+        if (!agent) {
+            throw new NotFoundError(`Agent with name or id "${agentNameOrPermanentId}" not found`);
+        }
+
+        return agent;
+    };
+
     return {
         async listAgents() {
             return agents.map(
@@ -147,6 +172,13 @@ function createResolverAgentCollection(agents: ReadonlyArray<CustomDomainAgentRe
                     } satisfies AgentBasicInformation),
             );
         },
+        async getAgentPermanentId(agentNameOrPermanentId: string) {
+            const agent = resolveAgent(agentNameOrPermanentId);
+            return (agent.permanentId || agent.agentName) as string_agent_permanent_id;
+        },
+        async getAgentSource(agentNameOrPermanentId: string) {
+            return resolveAgent(agentNameOrPermanentId).agentSource as string_book;
+        },
     } as unknown as AgentCollection;
 }
 
@@ -181,6 +213,108 @@ function createCanonicalLocalAgentUrl(agent: CustomDomainAgentRow, localServerUr
     return `${localServerUrl.replace(/\/+$/g, '')}/agents/${encodeURIComponent(canonicalAgentIdentifier)}`;
 }
 
+/**
+ * Creates an Edge-safe local importer for custom-domain metadata resolution.
+ *
+ * @param options - Local collection and inheritance dependencies.
+ * @returns Local source importer for route-level agent URLs.
+ */
+function createCustomDomainLocalAgentSourceImporter(options: {
+    readonly collection: Pick<AgentCollection, 'getAgentPermanentId' | 'getAgentSource'>;
+    readonly localServerUrl: string;
+    readonly adamAgentUrl: string_agent_url;
+    readonly agentReferenceResolver: AgentReferenceResolver;
+    readonly federatedAgentImportConfiguration: FederatedAgentImportConfiguration;
+}): AgentSourceImporter {
+    const localServerUrls = normalizeLocalServerUrls([options.localServerUrl]);
+    const localAgentUrlReferences = normalizeLocalAgentUrlReferences([options.adamAgentUrl]);
+    const agentSourceImporter: AgentSourceImporter = async (agentUrl, context) => {
+        const localRouteReference = resolveLocalAgentRouteReference(agentUrl, localServerUrls, localAgentUrlReferences);
+
+        if (!localRouteReference) {
+            return null;
+        }
+
+        const nextRecursionLevel = (context.importAgentOptions.recursionLevel || 0) + 1;
+        assertCustomDomainLocalImportRecursionLevel(nextRecursionLevel, agentUrl);
+
+        let agentPermanentId: string_agent_permanent_id;
+        let unresolvedAgentSource: string_book;
+
+        try {
+            agentPermanentId = await options.collection.getAgentPermanentId(localRouteReference.agentIdentifier);
+            unresolvedAgentSource = await options.collection.getAgentSource(agentPermanentId);
+        } catch (error) {
+            if (error instanceof NotFoundError) {
+                return createMissingImportedAgentFallback(agentUrl, 1, error);
+            }
+
+            throw error;
+        }
+
+        const resolvedAgentName = readAgentSourceTitle(unresolvedAgentSource) || localRouteReference.agentIdentifier;
+        const canonicalAgentUrl = createLocalAgentUrl(localRouteReference.localServerUrl, agentPermanentId);
+
+        return resolveInheritedAgentSource(unresolvedAgentSource, {
+            adamAgentUrl: options.adamAgentUrl,
+            recursionLevel: nextRecursionLevel,
+            inheritancePath: context.importAgentOptions.inheritancePath,
+            currentAgentUrl: canonicalAgentUrl,
+            currentAgentAliases: [
+                canonicalAgentUrl,
+                createLocalAgentUrl(localRouteReference.localServerUrl, localRouteReference.agentIdentifier),
+                createLocalAgentUrl(localRouteReference.localServerUrl, resolvedAgentName),
+            ].filter((value, index, values): value is string_agent_url => values.indexOf(value) === index),
+            agentReferenceResolver: options.agentReferenceResolver,
+            federatedAgentImportConfiguration:
+                options.federatedAgentImportConfiguration || context.federatedAgentImportConfiguration,
+            agentSourceImporter,
+        });
+    };
+
+    return agentSourceImporter;
+}
+
+/**
+ * Reads the first non-empty title line from one book source.
+ *
+ * @param agentSource - Agent book source.
+ * @returns Title or `null` when the source has no title line.
+ */
+function readAgentSourceTitle(agentSource: string_book): string | null {
+    for (const line of agentSource.split(/\r?\n/)) {
+        const title = line.trim();
+
+        if (title) {
+            return title;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Throws when direct local importing would exceed the configured recursion limit.
+ *
+ * @param recursionLevel - Next recursion level.
+ * @param agentUrl - Local agent URL being imported.
+ */
+function assertCustomDomainLocalImportRecursionLevel(recursionLevel: number, agentUrl: string_agent_url): void {
+    if (recursionLevel <= DEFAULT_MAX_RECURSION) {
+        return;
+    }
+
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Recursion depth ${recursionLevel} exceeds maximum allowed ${DEFAULT_MAX_RECURSION} while importing local custom-domain agent:
+
+                ${block(agentUrl)}
+            `,
+        ),
+    );
+}
+
 /**
  * Parses only the resolved custom-domain metadata used by proxy routing.
  *
@@ -254,6 +388,7 @@ async function resolveCustomDomainMetadataForAgent(
         readonly adamAgentUrl: string;
         readonly agentReferenceResolver: Awaited<ReturnType<typeof createServerAgentReferenceResolver>>;
         readonly federatedAgentImportConfiguration: FederatedAgentImportConfiguration;
+        readonly agentSourceImporter: AgentSourceImporter;
     },
 ): Promise<ResolvedCustomDomainMetadata> {
     const resolvedAgentSource = await resolveInheritedAgentSource(agent.agentSource as string_book, {
@@ -261,6 +396,7 @@ async function resolveCustomDomainMetadataForAgent(
         currentAgentUrl: createCanonicalLocalAgentUrl(agent, options.localServerUrl),
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration: options.federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
 
     return parseResolvedCustomDomainMetadata(resolvedAgentSource);
@@ -309,7 +445,7 @@ export async function resolveCustomDomainAgent(
 
             const { data: resolverReferenceAgents, error: resolverReferenceError } = await supabase
                 .from(tableName)
-                .select('agentName, permanentId')
+                .select('agentName, permanentId, agentSource')
                 .is('deletedAt', null);
 
             if (resolverReferenceError || !Array.isArray(resolverReferenceAgents)) {
@@ -317,13 +453,21 @@ export async function resolveCustomDomainAgent(
             }
 
             const localServerUrl = createServerPublicUrl(server.domain).href;
+            const agentCollection = createResolverAgentCollection(
+                resolverReferenceAgents as Array<CustomDomainAgentRow>,
+            );
             const agentReferenceResolver = await createServerAgentReferenceResolver({
-                agentCollection: createResolverAgentCollection(
-                    resolverReferenceAgents as Array<CustomDomainAgentReferenceRow>,
-                ),
+                agentCollection,
                 localServerUrl,
                 federatedServers,
             });
+            const agentSourceImporter = createCustomDomainLocalAgentSourceImporter({
+                collection: agentCollection,
+                localServerUrl,
+                adamAgentUrl,
+                agentReferenceResolver,
+                federatedAgentImportConfiguration,
+            });
 
             let matchedAgent: CustomDomainAgentRow | undefined;
 
@@ -333,6 +477,7 @@ export async function resolveCustomDomainAgent(
                     adamAgentUrl,
                     agentReferenceResolver,
                     federatedAgentImportConfiguration,
+                    agentSourceImporter,
                 });
 
                 if (matchesResolvedCustomDomain(resolvedMetadata, candidates)) {

package/apps/agents-server/src/utils/externalChatRunner/processExternalUserChatJob.ts

@@ -153,7 +153,7 @@ async function enqueueExternalUserChatJob(job: UserChatJobRecord): Promise<Proce
         return { didMutate: false, outcome: 'waiting' };
     }
 
-    const threadMessages = createUserChatRunnerThreadMessages({
+    const threadMessages = await createUserChatRunnerThreadMessages({
         messages: chat.messages,
         userMessageId: job.userMessageId,
         resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,

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

@@ -1,12 +1,10 @@
-import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
-import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
 import type { string_agent_url } from '../../../../src/types/typeAliases';
 import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
-import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import {
     DEFAULT_FEDERATED_AGENT_IMPORT_CONFIGURATION,
     type FederatedAgentImportConfiguration,
 } from '../constants/federatedAgentImport';
+import { createMissingImportedAgentFallback } from './createMissingImportedAgentFallback';
 import { retryWithBackoff } from './retryWithBackoff';
 import { importAgent, type ImportAgentOptions } from './importAgent';
 
@@ -40,61 +38,6 @@ const cachedFailedImportedAgentFallbackByKey = new Map<string, FailedImportedAge
  */
 const pendingImportedAgentFallbackByKey = new Map<string, Promise<string_book>>();
 
-/**
- * Collapses one thrown error into a single-line message suitable for `NOTE` commitments.
- *
- * @param agentUrl - Canonical imported agent URL.
- * @param error - Unknown error raised while loading the imported agent.
- * @returns Human-readable single-line failure reason.
- *
- * @private internal helper for imported-agent fallback books
- */
-function normalizeImportFailureMessage(agentUrl: string_agent_url, error: unknown): string {
-    const rawMessage = error instanceof Error ? error.message : String(error);
-    const normalizedMessage = rawMessage.replace(/\s+/g, ' ').trim();
-    const prefix = `Failed to import agent from "${agentUrl}"`;
-
-    if (normalizedMessage.startsWith(prefix)) {
-        const suffix = normalizedMessage.slice(prefix.length).trim();
-        if (suffix.length > 0) {
-            return suffix.replace(/^[-:,\s]+/, '').trim() || 'unknown error';
-        }
-    }
-
-    return normalizedMessage || 'unknown error';
-}
-
-/**
- * Creates the ad-hoc fallback source returned when a federated imported agent stays unavailable.
- *
- * @param agentUrl - Canonical imported agent URL.
- * @param attempts - Total number of attempts that were used.
- * @param error - Final error raised by the failed import attempts.
- * @returns Valid fallback book source.
- *
- * @private internal helper for imported-agent fallback books
- */
-function createMissingImportedAgentFallback(
-    agentUrl: string_agent_url,
-    attempts: number,
-    error: unknown,
-): string_book {
-    const failureMessage = normalizeImportFailureMessage(agentUrl, error);
-
-    return padBook(
-        validateBook(
-            spaceTrim(
-                `
-                    Not found agent
-
-                    NOTE This agent was supposed to be imported from ${agentUrl}, but it can not be loaded after ${attempts} attempts because of ${failureMessage}
-                    CLOSED
-                `,
-            ),
-        ),
-    );
-}
-
 /**
  * Builds the stable cache key used for import-with-fallback memoization.
  *