@promptbook/cli 0.113.0-1 → 0.113.0-11

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

@@ -9,11 +9,11 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
-import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
 import { createUserChatRunnerThreadMessages } from '../userChat/userChatMessageLifecycle';
+import { runWithTaskTerminalCapture } from '../taskTerminal/runWithTaskTerminalCapture';
 import {
     createLocalUserChatJobMetadata,
     getLocalUserChatJobMetadata,
@@ -45,6 +45,15 @@ export type ProcessLocalUserChatJobResult = {
  * Processes one UserChatJob through the local message-folder runner contract.
  */
 export async function processLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessLocalUserChatJobResult> {
+    return await runWithTaskTerminalCapture(job.id, () => processLocalUserChatJobWithinTerminalCapture(job));
+}
+
+/**
+ * Processes one local job while its console output is mirrored into the task terminal log.
+ */
+async function processLocalUserChatJobWithinTerminalCapture(
+    job: UserChatJobRecord,
+): Promise<ProcessLocalUserChatJobResult> {
     try {
         if (job.status === 'COMPLETED' || job.status === 'CANCELLED') {
             return { didMutate: false, outcome: 'ignored' };
@@ -120,6 +129,15 @@ export async function processNextLocalUserChatJob(
  * Enqueues one local queued job into the current agent folder.
  */
 async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessLocalUserChatJobResult> {
+    return await runWithTaskTerminalCapture(job.id, () => enqueueLocalUserChatJobWithinTerminalCapture(job));
+}
+
+/**
+ * Enqueues one local job while its console output is mirrored into the task terminal log.
+ */
+async function enqueueLocalUserChatJobWithinTerminalCapture(
+    job: UserChatJobRecord,
+): Promise<ProcessLocalUserChatJobResult> {
     const [chat, agentSourceSnapshot] = await Promise.all([
         getUserChat({
             userId: job.userId,
@@ -144,7 +162,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,
@@ -176,10 +194,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
-            progressCard: createUserChatRunnerProgressCard({
-                runnerKind: 'local',
-                phase: 'queued_for_runner',
-            }),
+            progressCard: undefined,
         }),
     });
 

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/pagePreviewBrowserSessions.ts

@@ -0,0 +1,246 @@
+import type { Page } from 'playwright';
+import type { AdminChatTaskRecord } from './chatTasksAdmin';
+import type { UserInfo } from './getCurrentUser';
+import { appendTaskTerminalLogLine, markTaskTerminalLogFinished } from './taskTerminal/taskTerminalLog';
+
+/**
+ * Prefix for browser-preview session identifiers created by the citation preview UI.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX = 'page-preview-';
+
+/**
+ * Pattern accepted for client-created page-preview session identifiers.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN = /^page-preview-[a-z0-9-]{16,80}$/;
+
+/**
+ * Queue name used when active browser previews are surfaced in the admin task manager.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME = 'page-preview-browser';
+
+/**
+ * Agent label used by the task manager for browser-preview rows.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME = 'Browser preview';
+
+/**
+ * In-memory record for one live browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserSession = {
+    readonly id: string;
+    readonly url: string;
+    readonly userId: number;
+    readonly username: string | null;
+    readonly createdAt: string;
+    readonly startedAt: string;
+    readonly processId: number | null;
+    page: Page | null;
+    viewport: PagePreviewBrowserViewport | null;
+    updatedAt: string;
+    lastFrameAt: string | null;
+};
+
+/**
+ * Browser viewport used to convert pointer ratios into Playwright coordinates.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserViewport = {
+    readonly width: number;
+    readonly height: number;
+};
+
+/**
+ * Options used when registering one browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type RegisterPagePreviewBrowserSessionOptions = {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly user: UserInfo;
+};
+
+/**
+ * Shared in-memory browser-preview registry.
+ *
+ * The route streams are short-lived and tied to the current Node process, so a
+ * durable database row would create stale task-manager entries after restarts.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const pagePreviewBrowserSessions = new Map<string, PagePreviewBrowserSession>();
+
+/**
+ * Creates a normalized page-preview browser session id.
+ *
+ * @param requestedSessionId - Optional client-created session id.
+ * @returns Valid session id or `null` when the supplied value is invalid.
+ */
+export function normalizePagePreviewBrowserSessionId(requestedSessionId: string | null): string | null {
+    if (!requestedSessionId) {
+        return null;
+    }
+
+    const normalizedSessionId = requestedSessionId.trim().toLowerCase();
+    return PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN.test(normalizedSessionId) ? normalizedSessionId : null;
+}
+
+/**
+ * Registers or replaces one active browser preview session.
+ *
+ * @param options - Session metadata.
+ * @returns Registered session snapshot.
+ */
+export function registerPagePreviewBrowserSession(
+    options: RegisterPagePreviewBrowserSessionOptions,
+): PagePreviewBrowserSession {
+    const now = new Date().toISOString();
+    const previousSession = pagePreviewBrowserSessions.get(options.sessionId);
+    if (previousSession?.page) {
+        void previousSession.page.close().catch(() => undefined);
+    }
+
+    const session: PagePreviewBrowserSession = {
+        id: options.sessionId,
+        url: options.url,
+        userId: options.user.id ?? 0,
+        username: options.user.username,
+        createdAt: now,
+        startedAt: now,
+        updatedAt: now,
+        lastFrameAt: null,
+        processId: typeof process.pid === 'number' ? process.pid : null,
+        page: null,
+        viewport: null,
+    };
+
+    pagePreviewBrowserSessions.set(options.sessionId, session);
+    appendTaskTerminalLogLine(
+        options.sessionId,
+        `Started live browser preview of ${options.url} for user #${session.userId} (${session.username || 'unknown'}).`,
+    );
+    return session;
+}
+
+/**
+ * Attaches the Playwright page used by one live browser preview.
+ *
+ * @param sessionId - Active session id.
+ * @param page - Playwright page bound to the stream.
+ * @param viewport - Viewport used by the stream.
+ */
+export function attachPagePreviewBrowserSessionPage(
+    sessionId: string,
+    page: Page,
+    viewport: PagePreviewBrowserViewport,
+): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    session.page = page;
+    session.viewport = viewport;
+    session.updatedAt = new Date().toISOString();
+    appendTaskTerminalLogLine(
+        sessionId,
+        `Browser page attached with a ${viewport.width}x${viewport.height} viewport, streaming frames.`,
+    );
+}
+
+/**
+ * Marks that one stream frame has been delivered.
+ *
+ * @param sessionId - Active session id.
+ */
+export function markPagePreviewBrowserSessionFrame(sessionId: string): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    const now = new Date().toISOString();
+    session.lastFrameAt = now;
+    session.updatedAt = now;
+}
+
+/**
+ * Removes one browser preview session from the active registry.
+ *
+ * @param sessionId - Active session id.
+ */
+export function finishPagePreviewBrowserSession(sessionId: string): void {
+    if (pagePreviewBrowserSessions.delete(sessionId)) {
+        appendTaskTerminalLogLine(sessionId, 'Browser preview session finished.');
+        markTaskTerminalLogFinished(sessionId, { isSuccessful: true });
+    }
+}
+
+/**
+ * Returns the active browser preview session when owned by the current user.
+ *
+ * @param sessionId - Browser preview session id.
+ * @param user - Current authenticated user.
+ * @returns Session or `null` when missing or owned by a different user.
+ */
+export function findUserPagePreviewBrowserSession(
+    sessionId: string,
+    user: UserInfo,
+): PagePreviewBrowserSession | null {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return null;
+    }
+
+    if ((user.id ?? 0) !== session.userId || user.username !== session.username) {
+        return null;
+    }
+
+    return session;
+}
+
+/**
+ * Lists active browser preview sessions as admin task-manager rows.
+ *
+ * @returns Task-manager rows for streams currently attached to this process.
+ */
+export function listPagePreviewBrowserAdminTasks(): Array<AdminChatTaskRecord> {
+    return Array.from(pagePreviewBrowserSessions.values()).map((session) => ({
+        id: session.id,
+        kind: 'BROWSER_PREVIEW',
+        status: 'RUNNING',
+        createdAt: session.createdAt,
+        queuedAt: session.createdAt,
+        startedAt: session.startedAt,
+        updatedAt: session.updatedAt,
+        finishedAt: null,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: session.lastFrameAt,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: null,
+        lastErrorDetails: session.url,
+        userId: session.userId,
+        username: session.username,
+        agentPermanentId: PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX,
+        agentName: PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME,
+        chatId: session.url,
+        workerId: session.processId === null ? null : String(session.processId),
+        queueName: PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME,
+    }));
+}

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(