@promptbook/cli 0.113.0-4 → 0.113.0-8

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.
  *

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

@@ -0,0 +1,167 @@
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+
+/**
+ * Parsed local agent route reference.
+ */
+export type LocalAgentRouteReference = {
+    /**
+     * Matched same-instance server origin.
+     */
+    readonly localServerUrl: string;
+
+    /**
+     * Decoded route identifier after `/agents/`.
+     */
+    readonly agentIdentifier: string;
+};
+
+/**
+ * Exact local route alias for one agent URL.
+ */
+export type LocalAgentUrlReference = LocalAgentRouteReference & {
+    /**
+     * Normalized exact local agent URL.
+     */
+    readonly agentUrl: string;
+};
+
+/**
+ * Normalizes same-instance server URLs for route matching.
+ *
+ * @param localServerUrls - Raw server URLs.
+ * @returns Unique normalized origins without trailing slash.
+ */
+export function normalizeLocalServerUrls(localServerUrls: ReadonlyArray<string>): ReadonlyArray<string> {
+    return [
+        ...new Set(
+            localServerUrls
+                .map((localServerUrl) => normalizeServerUrl(localServerUrl))
+                .filter((localServerUrl) => localServerUrl.length > 0),
+        ),
+    ];
+}
+
+/**
+ * Normalizes exact local agent URL aliases for route matching.
+ *
+ * @param localAgentUrls - Raw local agent URLs.
+ * @returns Unique normalized route references.
+ */
+export function normalizeLocalAgentUrlReferences(
+    localAgentUrls: ReadonlyArray<string_agent_url>,
+): ReadonlyArray<LocalAgentUrlReference> {
+    const localAgentUrlReferences: Array<LocalAgentUrlReference> = [];
+    const seenAgentUrls = new Set<string>();
+
+    for (const localAgentUrl of localAgentUrls) {
+        const localAgentRouteReference = parseLocalAgentRouteReference(localAgentUrl);
+
+        if (!localAgentRouteReference) {
+            continue;
+        }
+
+        const normalizedAgentUrl = createLocalAgentUrl(
+            localAgentRouteReference.localServerUrl,
+            localAgentRouteReference.agentIdentifier,
+        );
+
+        if (seenAgentUrls.has(normalizedAgentUrl)) {
+            continue;
+        }
+
+        seenAgentUrls.add(normalizedAgentUrl);
+        localAgentUrlReferences.push({
+            ...localAgentRouteReference,
+            agentUrl: normalizedAgentUrl,
+        });
+    }
+
+    return localAgentUrlReferences;
+}
+
+/**
+ * Extracts a local agent identifier from a same-instance agent URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @param localServerUrls - Normalized same-instance server origins.
+ * @param localAgentUrlReferences - Exact agent URL aliases that should resolve locally.
+ * @returns Route reference or `null` when the URL belongs to another server.
+ */
+export function resolveLocalAgentRouteReference(
+    agentUrl: string_agent_url,
+    localServerUrls: ReadonlyArray<string>,
+    localAgentUrlReferences: ReadonlyArray<LocalAgentUrlReference>,
+): LocalAgentRouteReference | null {
+    const localAgentRouteReference = parseLocalAgentRouteReference(agentUrl);
+
+    if (!localAgentRouteReference) {
+        return null;
+    }
+
+    if (localServerUrls.includes(localAgentRouteReference.localServerUrl)) {
+        return localAgentRouteReference;
+    }
+
+    const normalizedAgentUrl = createLocalAgentUrl(
+        localAgentRouteReference.localServerUrl,
+        localAgentRouteReference.agentIdentifier,
+    );
+    return (
+        localAgentUrlReferences.find((localAgentUrlReference) => localAgentUrlReference.agentUrl === normalizedAgentUrl) ||
+        null
+    );
+}
+
+/**
+ * Builds one local agent profile URL.
+ *
+ * @param localServerUrl - Same-instance server origin.
+ * @param agentIdentifier - Route agent identifier.
+ * @returns Local agent URL.
+ */
+export function createLocalAgentUrl(localServerUrl: string, agentIdentifier: string): string_agent_url {
+    return `${localServerUrl.replace(/\/+$/g, '')}/agents/${encodeURIComponent(agentIdentifier)}` as string_agent_url;
+}
+
+/**
+ * Normalizes one server URL to its origin.
+ *
+ * @param serverUrl - Raw server URL.
+ * @returns Normalized origin or an empty string when invalid.
+ */
+function normalizeServerUrl(serverUrl: string): string {
+    try {
+        return new URL(serverUrl).origin.replace(/\/+$/g, '');
+    } catch {
+        return serverUrl.replace(/\/+$/g, '');
+    }
+}
+
+/**
+ * Extracts a local route reference from an agent profile URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @returns Route reference or `null` when the URL is not an agent profile route.
+ */
+function parseLocalAgentRouteReference(agentUrl: string_agent_url): LocalAgentRouteReference | null {
+    let parsedAgentUrl: URL;
+
+    try {
+        parsedAgentUrl = new URL(agentUrl);
+    } catch {
+        return null;
+    }
+
+    const localServerUrl = normalizeServerUrl(parsedAgentUrl.origin);
+    const pathSegments = parsedAgentUrl.pathname.split('/').filter(Boolean);
+    const agentIdentifier = pathSegments[0] === 'agents' ? pathSegments[1] : null;
+
+    if (!agentIdentifier) {
+        return null;
+    }
+
+    return {
+        localServerUrl,
+        agentIdentifier: decodeURIComponent(agentIdentifier),
+    };
+}

package/apps/agents-server/src/utils/localChatRunner/processLocalUserChatJob.ts

@@ -144,7 +144,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         throw new Error(`User message "${job.userMessageId}" was not found in chat "${job.chatId}".`);
     }
 
-    const threadMessages = createUserChatRunnerThreadMessages({
+    const threadMessages = await createUserChatRunnerThreadMessages({
         messages: chat.messages,
         userMessageId: job.userMessageId,
         resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,

package/apps/agents-server/src/utils/managementApi/managementApiAgents.ts

@@ -4,8 +4,10 @@ import { loadLocalOrganizationSearchDataset } from '../../search/createDefaultSe
 import { stringifyJsonForSearch } from '../../search/createDefaultServerSearchProviders/stringifyJsonForSearch';
 import { $getTableName } from '../../database/$getTableName';
 import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
 import type { OwnedAgentRow } from '../agentOwnership';
 import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provideAgentReferenceResolver';
+import { createLocalAgentSourceImporter } from '../createLocalAgentSourceImporter';
 import { getWellKnownAgentUrl } from '../getWellKnownAgentUrl';
 import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
 import { resolveStoredAgentState } from '../resolveStoredAgentState';
@@ -42,10 +44,22 @@ export type ManagementAgentListItem = {
  * @returns Resolved agent state derived from the stored unresolved source.
  */
 export async function resolveOwnedAgentDerivedState(row: OwnedAgentRow) {
+    const localServerUrl = await resolveCurrentOrInternalServerOrigin();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentReferenceResolver = await $provideAgentReferenceResolver();
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: await $provideAgentCollectionForServer(),
+        localServerUrls: [localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
+
     return resolveStoredAgentState(row, {
-        localServerUrl: await resolveCurrentOrInternalServerOrigin(),
-        adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
-        agentReferenceResolver: await $provideAgentReferenceResolver(),
+        localServerUrl,
+        adamAgentUrl,
+        agentReferenceResolver,
+        agentSourceImporter,
     });
 }
 

package/apps/agents-server/src/utils/messages/sendMessage.ts

@@ -3,6 +3,7 @@ import { EMAIL_PROVIDERS } from '../../message-providers';
 import type { MessageProvider } from '../../message-providers/interfaces/MessageProvider';
 import type { OutboundEmail } from '../../message-providers/email/_common/Email';
 import { createMessage } from './createMessage';
+import { humanizeOutboundEmail } from './humanizeOutboundEmail';
 import { sendMessageAttempt } from './sendMessageAttempt';
 
 /**
@@ -63,14 +64,15 @@ export function isSendMessageDeliveryError(error: unknown): error is SendMessage
  * Persists a message and, for outbound emails, creates send attempts until one provider succeeds.
  */
 export async function sendMessage(message: OutboundEmail, options?: SendMessageOptions): Promise<SendMessageResult> {
-    const insertedMessage = await createMessage(message);
+    const email = humanizeOutboundEmail(message);
+    const insertedMessage = await createMessage(email);
     const baseResult: SendMessageResult = {
         messageId: insertedMessage.id,
         status: 'stored-only',
         attempts: [],
     };
 
-    if (message.direction !== 'OUTBOUND' || message.channel !== 'EMAIL') {
+    if (email.direction !== 'OUTBOUND' || email.channel !== 'EMAIL') {
         return baseResult;
     }
 
@@ -88,7 +90,7 @@ export async function sendMessage(message: OutboundEmail, options?: SendMessageO
             messageId: insertedMessage.id,
             providerName,
             provider,
-            message,
+            message: email,
         });
 
         baseResult.attempts.push(attempt);

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

@@ -3,7 +3,7 @@ import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-sour
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
 import { parseAgentSource } from '../../../../src/book-2.0/agent-source/parseAgentSource';
 import { resolveTeamCapabilitiesFromAgentSource } from './agentReferenceResolver/resolveTeamCapabilitiesFromAgentSource';
-import { resolveInheritedAgentSource } from './resolveInheritedAgentSource';
+import { resolveInheritedAgentSource, type AgentSourceImporter } from './resolveInheritedAgentSource';
 
 /**
  * Options for deriving the canonical resolved agent state from an editable source.
@@ -33,6 +33,11 @@ export type ResolveAgentStateFromSourceOptions = {
      * Retry configuration used when loading imported agents from federated servers.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
 /**
@@ -112,6 +117,7 @@ export async function resolveAgentStateFromSource(
         currentAgentAliases: options.currentAgentAliases,
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration: options.federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
     const resolvedAgentProfile = parseAgentSource(resolvedAgentSource);
     const resolvedTeamCapabilities = await resolveTeamCapabilitiesFromAgentSource(