@promptbook/cli 0.112.0-103 → 0.112.0-104

package/apps/agents-server/src/app/AddAgentButton.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { useRouter } from 'next/navigation';
 import { FileCard } from '../components/Homepage/FileCard';
 import { useAgentNaming } from '../components/AgentNaming/AgentNamingContext';
 import { showAlert } from '../components/AsyncDialogs/asyncDialogs';
@@ -21,15 +20,11 @@ type AddAgentButtonProps = {
  * Renders the add-agent card and creation dialog workflow.
  */
 export function AddAgentButton({ currentFolderId }: AddAgentButtonProps) {
-    const router = useRouter();
     const { formatText } = useAgentNaming();
     const { t } = useServerLanguage();
     const addButtonLabel = formatText(t('agentCreation.addButtonLabel'));
 
     const { isPreparingDialog, openNewAgentDialog, dialog } = useNewAgentDialog({
-        onCreated: ({ targetPath }) => {
-            router.push(targetPath);
-        },
         onCreateFailed: async (error) => {
             console.error('Failed to create agent:', error);
             await showAlert({

package/apps/agents-server/src/app/actions.ts

@@ -8,6 +8,9 @@ import { DEFAULT_NAME_POOL, NAME_POOL_METADATA_KEY, parseNamePool } from '../con
 import { NEW_AGENT_WIZZARD_METADATA_KEY, parseNewAgentWizardMode } from '../constants/newAgentWizard';
 import { getMetadata } from '../database/getMetadata';
 import { $provideAgentCollectionForServer } from '../tools/$provideAgentCollectionForServer';
+import { invalidateCachedActiveOrganizationSnapshots } from '../utils/agentOrganization/loadAgentOrganizationState';
+import { resolveAgentRouteTarget } from '../utils/agentRouting/resolveAgentRouteTarget';
+import { buildAgentChatHref, buildAgentProfileHref } from '../utils/agentRouting/agentRouteHrefs';
 import { type AgentVisibility, parseAgentVisibility } from '../utils/agentVisibility';
 import { authenticateUser } from '../utils/authenticateUser';
 import { createAgentWithDefaultVisibility } from '../utils/createAgentWithDefaultVisibility';
@@ -15,6 +18,16 @@ import { resolveCurrentUserIdentity } from '../utils/currentUserIdentity';
 import { isUserAdmin } from '../utils/isUserAdmin';
 import { clearSession, setSession } from '../utils/session';
 
+/**
+ * Maximum attempts used to confirm a freshly created agent route resolves before navigation starts.
+ */
+const CREATED_AGENT_ROUTE_READY_ATTEMPTS = 20;
+
+/**
+ * Delay between created-agent route-resolution retries.
+ */
+const CREATED_AGENT_ROUTE_READY_DELAY_MS = 100;
+
 /**
  * Creates a new agent from the generated boilerplate template.
  *
@@ -34,6 +47,8 @@ export async function $createAgentAction(): Promise<{ agentName: string_agent_na
     const { agentName, permanentId } = await createAgentWithDefaultVisibility(collection, agentSource, {
         userId: currentUserIdentity?.userId,
     });
+    revalidateCreatedAgentPaths(permanentId);
+    await waitForCreatedAgentRoute(permanentId);
 
     return { agentName, permanentId };
 }
@@ -63,6 +78,39 @@ export async function $getNewAgentCreationSettingsAction(): Promise<{
     };
 }
 
+/**
+ * Clears cached organization snapshots and route payloads after a new agent is created.
+ *
+ * @param permanentId - Canonical identifier of the newly created agent.
+ */
+function revalidateCreatedAgentPaths(permanentId: string_agent_permanent_id): void {
+    invalidateCachedActiveOrganizationSnapshots();
+    revalidatePath('/', 'layout');
+    revalidatePath('/');
+    revalidatePath('/agents');
+    revalidatePath('/dashboard');
+    revalidatePath(buildAgentProfileHref(permanentId));
+    revalidatePath(buildAgentChatHref(permanentId));
+}
+
+/**
+ * Waits until the new agent can be resolved by the same routing helper the chat page uses.
+ *
+ * @param permanentId - Canonical identifier of the newly created agent.
+ */
+async function waitForCreatedAgentRoute(permanentId: string_agent_permanent_id): Promise<void> {
+    for (let attempt = 0; attempt < CREATED_AGENT_ROUTE_READY_ATTEMPTS; attempt++) {
+        const routeTarget = await resolveAgentRouteTarget(permanentId, { forceRefresh: true });
+        if (routeTarget?.kind === 'local' && routeTarget.canonicalAgentId === permanentId) {
+            return;
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, CREATED_AGENT_ROUTE_READY_DELAY_MS));
+    }
+
+    throw new Error(`Created agent "${permanentId}" could not be resolved for routing immediately after creation.`);
+}
+
 /**
  * Creates a new agent using provided book content.
  *
@@ -89,6 +137,8 @@ export async function $createAgentFromBookAction(
         visibility: visibility ?? undefined,
         userId: currentUserIdentity?.userId,
     });
+    revalidateCreatedAgentPaths(permanentId);
+    await waitForCreatedAgentRoute(permanentId);
 
     return { agentName, permanentId };
 }

package/apps/agents-server/src/app/agents/[agentName]/AgentProfileChat.tsx

@@ -4,7 +4,6 @@ import { usePromise } from '@common/hooks/usePromise';
 import { Chat } from '@promptbook-local/components';
 import { RemoteAgent } from '@promptbook-local/core';
 import { string_book, type ChatMessage } from '@promptbook-local/types';
-import { useRouter } from 'next/navigation';
 import { useCallback, useMemo, useState, type MouseEvent as ReactMouseEvent } from 'react';
 import { spaceTrim } from 'spacetrim';
 import { string_agent_url, string_color } from '../../../../../../src/types/typeAliases';
@@ -24,6 +23,7 @@ import { useServerLanguage } from '../../../components/ServerLanguage/ServerLang
 import { ChatThreadLoadingSkeleton } from '../../../components/Skeleton/ChatThreadLoadingSkeleton';
 import { usePromptbookTheme } from '../../../components/ThemeMode/usePromptbookTheme';
 import type { ServerLanguageCode } from '../../../languages/ServerLanguageRegistry';
+import { buildFreshAgentChatHref } from '../../../utils/agentRouting/agentRouteHrefs';
 import { executeQuickActionButton } from '../../../utils/chat/executeQuickActionButton';
 import { resolveChatMessageValidationIssue } from '../../../utils/chat/validateChatMessageContent';
 import { createServerLanguageMoment } from '../../../utils/localization/createServerLanguageMoment';
@@ -277,7 +277,6 @@ export function AgentProfileChat({
     isHistoryEnabled = false,
     areFileAttachmentsEnabled = true,
 }: AgentProfileChatProps) {
-    const router = useRouter();
     const [isCreatingAgent, setIsCreatingAgent] = useState(false);
     const [optimisticNavigationState, setOptimisticNavigationState] = useState<OptimisticChatNavigationState | null>(null);
     const { formatText } = useAgentNaming();
@@ -409,7 +408,7 @@ export function AgentProfileChat({
             try {
                 const { permanentId } = await $createAgentFromBookAction(bookContent as string_book);
                 if (permanentId) {
-                    router.push(`/agents/${permanentId}`);
+                    window.location.assign(buildFreshAgentChatHref(permanentId));
                 }
             } catch (error) {
                 console.error('Failed to create agent:', error);
@@ -421,7 +420,7 @@ export function AgentProfileChat({
                 setIsCreatingAgent(false);
             }
         },
-        [formatText, router],
+        [formatText],
     );
     const handleFileUpload = useCallback(async (file: File) => chatFileUploadHandler(file), []);
     const fallbackInitialMessage = useMemo(() => {

package/apps/agents-server/src/app/api/health/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * Ensures the readiness route runs in the same runtime as the standalone server.
+ */
+export const runtime = 'nodejs';
+
+/**
+ * Prevents a cached response from hiding readiness failures during deployment handoff.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Lightweight readiness endpoint used by standalone VPS pm2/nginx handoffs.
+ */
+export async function GET() {
+    return NextResponse.json({ status: 'ok' });
+}

package/apps/agents-server/src/components/AgentProfile/AgentProfile.tsx

@@ -186,10 +186,7 @@ export function AgentProfile(props: AgentProfileProps) {
                                 ) : (
                                     <div className="flex h-full w-full items-center justify-center overflow-hidden p-4 md:p-8">
                                         {/* Keep built-in visuals inside a centered square stage so different avatar renderers fit the tall profile card consistently. */}
-                                        <div
-                                            className="flex h-full w-full max-h-[80%] max-w-[80%] items-center justify-center"
-                                            style={{ aspectRatio: '1 / 1' }}
-                                        >
+                                        <div className="flex aspect-square w-[80%] items-center justify-center">
                                             <AgentAvatar
                                                 agent={agent}
                                                 baseUrl={publicUrl}

package/apps/agents-server/src/components/Header/Header.tsx

@@ -9,7 +9,6 @@ import { HamburgerMenu } from '../../../../../src/book-components/_common/Hambur
 import { useMenuHoisting } from '../../../../../src/book-components/_common/MenuHoisting/MenuHoistingContext';
 import { just } from '../../../../../src/utils/organization/just';
 import { getVisibleCommitmentDefinitions } from '../../utils/getVisibleCommitmentDefinitions';
-import { pushWithHeadless, useIsHeadless } from '../_utils/headlessParam';
 import { useInstallPromptState, type AgentContextMenuRenamePayload } from '../AgentContextMenu/AgentContextMenu';
 import { useAgentNaming } from '../AgentNaming/AgentNamingContext';
 import { QrCodeModal } from '../AgentProfile/QrCodeModal';
@@ -58,11 +57,9 @@ export function Header(props: HeaderProps) {
         feedbackMode = 'stars',
         shibbolethAuthenticationStatus,
     } = props;
-
     const [isChangePasswordOpen, setIsChangePasswordOpen] = useState(false);
     const router = useRouter();
     const pathname = usePathname();
-    const isHeadless = useIsHeadless();
     const menuHoisting = useMenuHoisting();
     const mobileMenuHoisting = useMobileMenuHoisting();
     const { naming } = useAgentNaming();
@@ -73,13 +70,6 @@ export function Header(props: HeaderProps) {
         () => buildDocumentationDropdownItems(visibleDocumentationCommitments, t),
         [t, visibleDocumentationCommitments],
     );
-
-    const fallbackNavigateToHref = useCallback(
-        (href: string) => {
-            pushWithHeadless(router, href, isHeadless);
-        },
-        [isHeadless, router],
-    );
     const hoistedMobileMenuItems = mobileMenuHoisting?.menuItems || EMPTY_HOISTED_MOBILE_MENU_ITEMS;
     const {
         cancelMenuClose,
@@ -201,7 +191,6 @@ export function Header(props: HeaderProps) {
         isAdmin,
         isAuthenticated: Boolean(currentUser),
         isInstalled,
-        navigateToHref: fallbackNavigateToHref,
         namingPlural: naming.plural,
         namingSingular: naming.singular,
         onAgentRenamed: handleAgentRenamedFromHeader,

package/apps/agents-server/src/components/Header/useHeaderAgentMenus.tsx

@@ -44,7 +44,6 @@ type UseHeaderAgentMenusOptions = {
     readonly isAdmin: boolean;
     readonly isAuthenticated: boolean;
     readonly isInstalled: boolean;
-    readonly navigateToHref: (href: string) => void;
     readonly namingPlural: string;
     readonly namingSingular: string;
     readonly onAgentRenamed: (payload: AgentContextMenuRenamePayload) => void;
@@ -160,7 +159,6 @@ export function useHeaderAgentMenus({
     isAdmin,
     isAuthenticated,
     isInstalled,
-    navigateToHref,
     namingPlural,
     namingSingular,
     onAgentRenamed,
@@ -214,9 +212,6 @@ export function useHeaderAgentMenus({
         openNewAgentDialog,
         dialog: newAgentDialog,
     } = useNewAgentDialog({
-        onCreated: ({ targetPath }) => {
-            navigateToHref(targetPath);
-        },
         onCreateFailed: async (error) => {
             await showNewAgentFailure('Failed to create agent:', error, namingSingular, translate);
         },

package/apps/agents-server/src/components/NewAgentDialog/useNewAgentDialog.tsx

@@ -3,7 +3,9 @@
 import type { string_book } from '@promptbook-local/types';
 import type { ReactElement } from 'react';
 import { useCallback, useState } from 'react';
+import { appendHeadlessParam, useIsHeadless } from '../_utils/headlessParam';
 import type { AgentVisibility } from '../../utils/agentVisibility';
+import { buildFreshAgentChatHref } from '../../utils/agentRouting/agentRouteHrefs';
 import {
     $createAgentFromBookAction,
     $generateAgentBoilerplateAction,
@@ -51,9 +53,9 @@ type CreatedAgentPayload = {
  */
 type UseNewAgentDialogOptions = {
     /**
-     * Called after a new agent is created successfully.
+     * Optional callback invoked after the new agent payload is prepared and before navigation starts.
      */
-    readonly onCreated: (agent: CreatedAgentPayload) => Promise<void> | void;
+    readonly onCreated?: (agent: CreatedAgentPayload) => Promise<void> | void;
     /**
      * Optional callback invoked when creating an agent fails.
      */
@@ -120,11 +122,27 @@ function extractAgentNameFromBoilerplate(boilerplate: string_book): string {
     );
 }
 
+/**
+ * Creates the navigation payload returned after one agent is persisted.
+ *
+ * @param agentName - Persisted display name of the agent.
+ * @param permanentId - Canonical immutable identifier of the agent.
+ * @returns Shared created-agent payload used by all creation surfaces.
+ */
+function createCreatedAgentPayload(agentName: string, permanentId: string): CreatedAgentPayload {
+    return {
+        agentName,
+        permanentId,
+        targetPath: buildFreshAgentChatHref(permanentId),
+    };
+}
+
 /**
  * Provides a shared "create new agent" workflow with boilerplate loading and a book-editing dialog.
  */
 export function useNewAgentDialog(options: UseNewAgentDialogOptions): UseNewAgentDialogResult {
     const { onCreated, onCreateFailed, onPrepareFailed } = options;
+    const isHeadless = useIsHeadless();
     const [isPreparingDialog, setIsPreparingDialog] = useState(false);
     const [dialogState, setDialogState] = useState<NewAgentDialogState | null>(null);
 
@@ -132,6 +150,21 @@ export function useNewAgentDialog(options: UseNewAgentDialogOptions): UseNewAgen
         setDialogState(null);
     }, []);
 
+    /**
+     * Finalizes one successful creation by hard-navigating to the new chat route.
+     *
+     * The App Router can transiently keep the just-created dynamic route in a stale not-found
+     * state, so new-agent creation intentionally uses a full navigation once the route is ready.
+     */
+    const handleCreatedAgent = useCallback(
+        async (agent: CreatedAgentPayload) => {
+            await onCreated?.(agent);
+            setDialogState(null);
+            window.location.assign(appendHeadlessParam(agent.targetPath, isHeadless));
+        },
+        [isHeadless, onCreated],
+    );
+
     const openNewAgentDialog = useCallback(
         async (openOptions?: OpenNewAgentDialogOptions) => {
             setIsPreparingDialog(true);
@@ -200,17 +233,12 @@ export function useNewAgentDialog(options: UseNewAgentDialogOptions): UseNewAgen
                     surface: 'editor',
                     folderId: dialogState.targetFolderId,
                 });
-                await onCreated({
-                    agentName,
-                    permanentId,
-                    targetPath: `/agents/${encodeURIComponent(permanentId)}`,
-                });
-                setDialogState(null);
+                await handleCreatedAgent(createCreatedAgentPayload(agentName, permanentId));
             } catch (error) {
                 await onCreateFailed?.(error);
             }
         },
-        [dialogState, onCreateFailed, onCreated],
+        [dialogState, handleCreatedAgent, onCreateFailed],
     );
 
     const handleCreateFromWizard = useCallback(
@@ -232,17 +260,12 @@ export function useNewAgentDialog(options: UseNewAgentDialogOptions): UseNewAgen
                     knowledgeCount: request.knowledgeCount,
                 });
 
-                await onCreated({
-                    agentName,
-                    permanentId,
-                    targetPath: `/agents/${encodeURIComponent(permanentId)}`,
-                });
-                setDialogState(null);
+                await handleCreatedAgent(createCreatedAgentPayload(agentName, permanentId));
             } catch (error) {
                 await onCreateFailed?.(error);
             }
         },
-        [dialogState, onCreateFailed, onCreated],
+        [dialogState, handleCreatedAgent, onCreateFailed],
     );
 
     const handleOpenEditorFromWizard = useCallback((request: NewAgentWizardOpenEditorRequest) => {

package/apps/agents-server/src/constants/defaultAgentAvatarVisual.ts

@@ -53,7 +53,7 @@ export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUES = DEFAULT_AGENT_AVATAR_
 export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUE =
     DEFAULT_AGENT_AVATAR_VISUAL_METADATA_OPTIONS.find(
         ({ visualId }) => visualId === SHARED_DEFAULT_AGENT_AVATAR_VISUAL_ID,
-    )?.metadataValue || 'OCTOPUS3';
+    )?.metadataValue || 'OCTOPUS3D3';
 
 /**
  * Resolves one raw metadata value to a supported built-in avatar visual id.

package/apps/agents-server/src/database/migrations/2026-06-0200-default-agent-avatar-visual-octopus3d3.sql

@@ -0,0 +1,16 @@
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'DEFAULT_AGENT_AVATAR_VISUAL',
+       'OCTOPUS3D3',
+       'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN UPPER(COALESCE("value", '')) = 'OCTOPUS3' THEN 'OCTOPUS3D3'
+                  ELSE "value"
+              END,
+    "note" = 'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+    "updatedAt" = NOW()
+WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL';

package/apps/agents-server/src/middleware.ts

@@ -53,8 +53,9 @@ export const config = {
          * - favicon.ico (favicon file)
          * - robots.txt (should not block on middleware DB lookups)
          * - public folder
+         * - api/health (standalone VPS readiness probe)
          * - api/internal (worker/cron routes are authorized separately)
          */
-        '/((?!_next/static|_next/image|favicon.ico|logo-|fonts/|robots.txt|api/internal).*)',
+        '/((?!_next/static|_next/image|favicon.ico|logo-|fonts/|robots.txt|api/health|api/internal).*)',
     ],
 };

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -4,6 +4,20 @@ import { TrackedFilesStorage } from '../utils/cdn/classes/TrackedFilesStorage';
 import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
 
+/**
+ * Region expected by the bundled VersityGW S3-compatible storage.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const SELF_CONTAINED_S3_DEFAULT_REGION = 'us-east-1';
+
+/**
+ * Legacy fallback used by Cloudflare R2-style external S3 configuration.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const EXTERNAL_S3_DEFAULT_REGION = 'auto';
+
 /**
  * Cache of CDN instance
  *
@@ -40,7 +54,7 @@ function createCdnStorageForServer(): IIFilesStorageWithCdn {
             cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
             gzip: true,
             forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
-            region: process.env.CDN_REGION || 'auto',
+            region: resolveS3CompatibleStorageRegion(),
         });
     }
 
@@ -57,7 +71,7 @@ function createCdnStorageForServer(): IIFilesStorageWithCdn {
  * @private helper of `$provideCdnForServer`
  */
 function isS3CompatibleStorageSelected(): boolean {
-    const storageMode = (process.env.PTBK_FILE_STORAGE_MODE || process.env.CDN_PROVIDER || '').toLowerCase();
+    const storageMode = getS3CompatibleStorageMode();
     const isS3StorageMode =
         storageMode === 's3' || storageMode === 'external-s3' || storageMode === 'self-contained-s3';
 
@@ -68,6 +82,33 @@ function isS3CompatibleStorageSelected(): boolean {
     return !process.env.VERCEL_BLOB_READ_WRITE_TOKEN && hasS3CompatibleStorageConfiguration();
 }
 
+/**
+ * Resolves the configured S3-compatible storage mode.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function getS3CompatibleStorageMode(): string {
+    return (process.env.PTBK_FILE_STORAGE_MODE || process.env.CDN_PROVIDER || '').toLowerCase();
+}
+
+/**
+ * Resolves the S3 signing region used by AWS SDK requests.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveS3CompatibleStorageRegion(): string {
+    const configuredRegion = process.env.CDN_REGION?.trim();
+    if (configuredRegion) {
+        return configuredRegion;
+    }
+
+    if (getS3CompatibleStorageMode() === 'self-contained-s3') {
+        return SELF_CONTAINED_S3_DEFAULT_REGION;
+    }
+
+    return EXTERNAL_S3_DEFAULT_REGION;
+}
+
 /**
  * Checks whether all S3-compatible storage environment variables are present.
  *

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -56,15 +56,21 @@ type PseudoAgentRouteTarget = {
 export type AgentRouteTarget = LocalAgentRouteTarget | RemoteAgentRouteTarget | PseudoAgentRouteTarget;
 
 /**
- * Resolves any incoming `/agents/:agentId` token into a canonical target URL.
+ * Resolves any incoming `/agents/:agentId` token into a canonical target URL without memoization.
  *
  * Supported inputs include plain IDs/names, `@name`, `{name}`, `{id}`, and absolute `/agents/...` URLs.
  * Pseudo-agent tokens such as `{User}`, `{Void}`, or `{Null}` resolve to dedicated documentation pages.
  *
  * @param rawReference - Raw decoded route parameter value.
+ * @param options - Optional cache-bypass controls used by create-agent flows.
  * @returns Canonical local/remote route target or `null` when the reference cannot be resolved.
  */
-const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<AgentRouteTarget | null> => {
+async function resolveAgentRouteTargetUncached(
+    rawReference: string,
+    options?: {
+        readonly forceRefresh?: boolean;
+    },
+): Promise<AgentRouteTarget | null> {
     const parsedBookScopedAgentIdentifier = parseBookScopedAgentIdentifier(rawReference);
     if (parsedBookScopedAgentIdentifier) {
         const { publicUrl } = await $provideServer();
@@ -96,7 +102,7 @@ const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<Ag
         };
     }
 
-    const resolver = await $provideAgentReferenceResolver();
+    const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
     try {
@@ -137,15 +143,32 @@ const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<Ag
         canonicalAgentId,
         canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
     };
+}
+
+/**
+ * Memoized route-target resolver used for normal page rendering.
+ */
+const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<AgentRouteTarget | null> => {
+    return resolveAgentRouteTargetUncached(rawReference);
 });
 
 /**
  * Resolves any incoming `/agents/:agentId` token into a canonical target URL.
  *
  * @param rawReference - Raw decoded route parameter value.
+ * @param options - Optional cache-bypass controls used by create-agent flows.
  * @returns Canonical local/remote route target or `null` when the reference cannot be resolved.
  */
-export async function resolveAgentRouteTarget(rawReference: string): Promise<AgentRouteTarget | null> {
+export async function resolveAgentRouteTarget(
+    rawReference: string,
+    options?: {
+        readonly forceRefresh?: boolean;
+    },
+): Promise<AgentRouteTarget | null> {
+    if (options?.forceRefresh) {
+        return resolveAgentRouteTargetUncached(rawReference, options);
+    }
+
     return getCachedAgentRouteTarget(rawReference);
 }