@promptbook/cli 0.112.0-103 → 0.112.0-105

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

@@ -5,20 +5,52 @@ import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
 
 /**
- * Cache of CDN instance
+ * Options controlling CDN storage construction for the current server request.
+ */
+export type ProvideCdnForServerOptions = {
+    /**
+     * Public URL used when generating file links.
+     */
+    readonly cdnPublicUrl?: URL;
+};
+
+/**
+ * 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 instances by public URL.
  *
  * @private internal cache for `$provideCdnForServer`
  */
-let cdn: IIFilesStorageWithCdn | null = null;
+const cdnByPublicUrl = new Map<string, IIFilesStorageWithCdn>();
 
 /**
  * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ *
+ * @param options - Optional request-aware CDN public URL override.
+ * @returns CDN storage interface.
  */
-export function $provideCdnForServer(): IIFilesStorageWithCdn {
+export function $provideCdnForServer(options: ProvideCdnForServerOptions = {}): IIFilesStorageWithCdn {
+    const cdnPublicUrl = options.cdnPublicUrl || resolveConfiguredCdnPublicUrl();
+    const cdnCacheKey = cdnPublicUrl.href;
+    let cdn = cdnByPublicUrl.get(cdnCacheKey);
+
     if (!cdn) {
-        const inner = createCdnStorageForServer();
+        const inner = createCdnStorageForServer(cdnPublicUrl);
         const supabase = $provideSupabaseForServer();
         cdn = new TrackedFilesStorage(inner, supabase);
+        cdnByPublicUrl.set(cdnCacheKey, cdn);
     }
 
     return cdn;
@@ -27,9 +59,10 @@ export function $provideCdnForServer(): IIFilesStorageWithCdn {
 /**
  * Creates the configured CDN storage implementation for server-side file operations.
  *
+ * @param cdnPublicUrl - Public URL used to build deterministic file links.
  * @private helper of `$provideCdnForServer`
  */
-function createCdnStorageForServer(): IIFilesStorageWithCdn {
+function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
     if (isS3CompatibleStorageSelected()) {
         return new DigitalOceanSpaces({
             bucket: process.env.CDN_BUCKET!,
@@ -37,27 +70,63 @@ function createCdnStorageForServer(): IIFilesStorageWithCdn {
             endpoint: process.env.CDN_ENDPOINT!,
             accessKeyId: process.env.CDN_ACCESS_KEY_ID!,
             secretAccessKey: process.env.CDN_SECRET_ACCESS_KEY!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+            cdnPublicUrl,
             gzip: true,
             forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
-            region: process.env.CDN_REGION || 'auto',
+            region: resolveS3CompatibleStorageRegion(),
         });
     }
 
     return new VercelBlobStorage({
         token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
         pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
-        cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+        cdnPublicUrl,
     });
 }
 
+/**
+ * Resolves the CDN public URL from environment configuration.
+ *
+ * @returns Configured CDN public URL.
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveConfiguredCdnPublicUrl(): URL {
+    return new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!);
+}
+
+/**
+ * Resolves the public URL that should be used for CDN links for one server request.
+ *
+ * Self-contained S3 is proxied through the current server domain. The configured
+ * CDN public URL still owns the `/s3/<bucket>` path, but the origin must follow
+ * the active server so uploads are not published under the VPS raw IP address.
+ *
+ * @param serverPublicUrl - Public URL of the active server.
+ * @returns Request-aware CDN public URL.
+ */
+export function resolveCdnPublicUrlForServer(serverPublicUrl: URL): URL {
+    const configuredCdnPublicUrl = resolveConfiguredCdnPublicUrl();
+
+    if (!isSelfContainedS3StorageSelected()) {
+        return configuredCdnPublicUrl;
+    }
+
+    const cdnPublicUrl = new URL(configuredCdnPublicUrl.href);
+    cdnPublicUrl.protocol = serverPublicUrl.protocol;
+    cdnPublicUrl.host = serverPublicUrl.host;
+    cdnPublicUrl.username = '';
+    cdnPublicUrl.password = '';
+
+    return cdnPublicUrl;
+}
+
 /**
  * Checks whether the current environment should use the S3-compatible storage implementation.
  *
  * @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 +137,42 @@ 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();
+}
+
+/**
+ * Checks whether the bundled self-contained S3 storage mode is selected.
+ *
+ * @returns `true` when self-contained S3 is selected.
+ */
+export function isSelfContainedS3StorageSelected(): boolean {
+    return getS3CompatibleStorageMode() === 'self-contained-s3';
+}
+
+/**
+ * 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 (isSelfContainedS3StorageSelected()) {
+        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);
 }
 

package/apps/agents-server/src/utils/defaultAgents/loadDefaultAgentBooks.ts

@@ -0,0 +1,103 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Options for loading bundled default agent books.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export type LoadDefaultAgentBooksOptions = {
+    /**
+     * Optional explicit directory containing `*.book` files.
+     */
+    readonly defaultAgentDirectory?: string | null;
+};
+
+/**
+ * Candidate directories where bundled default agent books can be located.
+ *
+ * The app test suite runs from `apps/agents-server`, local development usually runs from the repository root, and
+ * installer scripts can pass an explicit directory through `LoadDefaultAgentBooksOptions`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+const DEFAULT_AGENT_DIRECTORY_CANDIDATES = [
+    resolve(process.cwd(), 'agents', 'default'),
+    resolve(process.cwd(), '..', '..', 'agents', 'default'),
+    resolve(__dirname, '../../../../../agents/default'),
+] as const;
+
+/**
+ * Loads all default agent books in deterministic filename order.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Sorted default agent sources.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function loadDefaultAgentBooks(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<ReadonlyArray<string_book>> {
+    const defaultAgentDirectory = await resolveDefaultAgentDirectory(options);
+    const directoryEntries = await readdir(defaultAgentDirectory);
+    const defaultAgentFilenames = directoryEntries
+        .filter((entry) => entry.toLowerCase().endsWith('.book'))
+        .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
+
+    return Promise.all(
+        defaultAgentFilenames.map(async (filename) => {
+            const filePath = resolve(defaultAgentDirectory, filename);
+            return (await readFile(filePath, 'utf-8')) as string_book;
+        }),
+    );
+}
+
+/**
+ * Resolves the repository directory that stores default agent books.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Absolute path to `agents/default`.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+export async function resolveDefaultAgentDirectory(options: LoadDefaultAgentBooksOptions = {}): Promise<string> {
+    const directoryCandidates = [
+        ...(options.defaultAgentDirectory ? [resolve(options.defaultAgentDirectory)] : []),
+        ...DEFAULT_AGENT_DIRECTORY_CANDIDATES,
+    ];
+
+    for (const directoryCandidate of directoryCandidates) {
+        try {
+            await access(directoryCandidate);
+            return directoryCandidate;
+        } catch {
+            // Continue to the next candidate directory.
+        }
+    }
+
+    throw new DatabaseError(
+        spaceTrim(
+            (block) => `
+                Failed to locate the default Agents Server books directory.
+
+                Checked:
+                ${block(directoryCandidates.map((candidate) => `- \`${normalizePathForLogs(candidate)}\``).join('\n'))}
+            `,
+        ),
+    );
+}
+
+/**
+ * Normalizes path separators for diagnostics.
+ *
+ * @param value - Raw filesystem path.
+ * @returns Slash-normalized path.
+ *
+ * @private utility of Agents Server default-agent seeding
+ */
+function normalizePathForLogs(value: string): string {
+    return value.split('\\').join('/');
+}

package/apps/agents-server/src/utils/knowledge/createInlineKnowledgeSourceUploader.ts

@@ -1,8 +1,15 @@
-import { $provideCdnForServer } from '@/src/tools/$provideCdnForServer';
+import {
+    $provideCdnForServer,
+    isSelfContainedS3StorageSelected,
+    resolveCdnPublicUrlForServer,
+} from '@/src/tools/$provideCdnForServer';
+import { $provideServer } from '@/src/tools/$provideServer';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
 import { InlineKnowledgeSourceUploader } from '../../../../../src/utils/knowledge/inlineKnowledgeSource';
 import type { string_knowledge_source_link } from '../../../../../src/types/typeAliases';
 import { getSafeCdnPath } from '../cdn/utils/getSafeCdnPath';
 import { getUserFileCdnKey } from '../cdn/utils/getUserFileCdnKey';
+import { resolveFileUploadAvailability } from '../upload/fileUploadAvailability';
 
 /**
  * Options for create inline knowledge uploader.
@@ -23,18 +30,30 @@ const uploadCache = new Map<string, Promise<string_knowledge_source_link>>();
 export function createInlineKnowledgeSourceUploader(
     options: CreateInlineKnowledgeUploaderOptions = {},
 ): InlineKnowledgeSourceUploader {
-    const cdn = $provideCdnForServer();
     const { purpose = 'KNOWLEDGE', userId } = options;
 
     return async (source) => {
+        const providedServer = await $provideServer();
+        const fileUploadAvailability = resolveFileUploadAvailability({
+            serverId: providedServer.id,
+            serverPublicUrl: providedServer.publicUrl,
+            isSelfContainedS3StorageSelected: isSelfContainedS3StorageSelected(),
+        });
+        if (!fileUploadAvailability.isUploadAvailable) {
+            throw new NotAllowed(fileUploadAvailability.message || 'File uploads are not available for this server.');
+        }
+
+        const cdnPublicUrl = resolveCdnPublicUrlForServer(providedServer.publicUrl);
+        const cdn = $provideCdnForServer({ cdnPublicUrl });
         const rawKey = getUserFileCdnKey(source.buffer, source.filename);
         const safeKey = getSafeCdnPath({
             pathname: rawKey,
             pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX,
         });
+        const uploadCacheKey = `${providedServer.tablePrefix}:${cdnPublicUrl.href}:${safeKey}`;
 
-        if (uploadCache.has(safeKey)) {
-            return uploadCache.get(safeKey)!;
+        if (uploadCache.has(uploadCacheKey)) {
+            return uploadCache.get(uploadCacheKey)!;
         }
 
         const promise: Promise<string_knowledge_source_link> = (async () => {
@@ -48,7 +67,7 @@ export function createInlineKnowledgeSourceUploader(
             return cdn.getItemUrl(safeKey).href;
         })();
 
-        uploadCache.set(safeKey, promise);
+        uploadCache.set(uploadCacheKey, promise);
         return promise;
     };
 }

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

@@ -39,6 +39,15 @@ export type SpawnAgentLimits = {
     readonly rateLimitWindowMs: number;
 };
 
+/**
+ * Dedicated subset consumed by the local coding-agent runner.
+ *
+ * @private internal Agents Server type
+ */
+export type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+};
+
 /**
  * Row shape loaded from the dedicated `ServerLimit` table.
  *
@@ -250,6 +259,20 @@ export async function getSpawnAgentLimits(): Promise<SpawnAgentLimits> {
     };
 }
 
+/**
+ * Loads the local coding-agent runner retry limits.
+ *
+ * @returns Dedicated local agent runner limits.
+ *
+ * @private internal Agents Server helper
+ */
+export async function getLocalAgentRunnerLimits(): Promise<LocalAgentRunnerLimits> {
+    const limits = await getServerLimits();
+    return {
+        maxFailedAttempts: limits[SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS],
+    };
+}
+
 /**
  * Normalizes one arbitrary key/value object into the supported dedicated server-limit payload.
  *
@@ -277,7 +300,9 @@ export function normalizeServerLimitValues(rawValue: Record<string, unknown>): S
  */
 async function loadLegacyServerLimits(): Promise<Partial<Record<ServerLimitKey, unknown>>> {
     const metadata = await getMetadataMap(DEPRECATED_LIMIT_METADATA_KEYS);
-    const normalizedToolUsageLimits = normalizeToolUsageLimits(parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]));
+    const normalizedToolUsageLimits = normalizeToolUsageLimits(
+        parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]),
+    );
 
     return {
         [SERVER_LIMIT_KEYS.TIMEOUT_MAX_ACTIVE_PER_CHAT]: normalizedToolUsageLimits.timeout.maxActivePerChat,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerDefaultAgents.ts

@@ -1,26 +1,9 @@
-import { access, readFile, readdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import type { string_book } from '../../../../../../src/book-2.0/agent-source/string_book';
 import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
-import { DatabaseError } from '../../../../../../src/errors/DatabaseError';
 import type { Client } from 'pg';
-import { spaceTrim } from 'spacetrim';
+import { loadDefaultAgentBooks } from '../../defaultAgents/loadDefaultAgentBooks';
 import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
 import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
 
-/**
- * Candidate directories where bundled default agent books can be located.
- *
- * The app test suite runs from `apps/agents-server`, while local development usually runs from the repository root.
- *
- * @private function of createManagedServer
- */
-const DEFAULT_AGENT_DIRECTORY_CANDIDATES = [
-    resolve(process.cwd(), 'agents', 'default'),
-    resolve(process.cwd(), '..', '..', 'agents', 'default'),
-    resolve(__dirname, '../../../../../../agents/default'),
-] as const;
-
 /**
  * Loads default agent books from the repository and persists them into the newly created server.
  *
@@ -118,70 +101,3 @@ export async function seedServerDefaultAgents(
         sqlRecorder.addStatement(createInsertStatement(`${input.tablePrefix}AgentHistory`, agentHistoryInsertRecord));
     }
 }
-
-/**
- * Loads all default agent books in deterministic filename order.
- *
- * @returns Sorted default agent sources.
- *
- * @private function of `seedServerDefaultAgents`
- */
-async function loadDefaultAgentBooks(): Promise<ReadonlyArray<string_book>> {
-    const defaultAgentDirectory = await resolveDefaultAgentDirectory();
-    const directoryEntries = await readdir(defaultAgentDirectory);
-    const defaultAgentFilenames = directoryEntries
-        .filter((entry) => entry.toLowerCase().endsWith('.book'))
-        .sort((leftFilename, rightFilename) => leftFilename.localeCompare(rightFilename));
-
-    return Promise.all(
-        defaultAgentFilenames.map(async (filename) => {
-            const filePath = resolve(defaultAgentDirectory, filename);
-            return (await readFile(filePath, 'utf-8')) as string_book;
-        }),
-    );
-}
-
-/**
- * Resolves the repository directory that stores default managed-server agents.
- *
- * @returns Absolute path to `agents/default`.
- *
- * @private function of `seedServerDefaultAgents`
- */
-async function resolveDefaultAgentDirectory(): Promise<string> {
-    for (const directoryCandidate of DEFAULT_AGENT_DIRECTORY_CANDIDATES) {
-        try {
-            await access(directoryCandidate);
-            return directoryCandidate;
-        } catch {
-            // Continue to the next candidate directory.
-        }
-    }
-
-    throw new DatabaseError(
-        spaceTrim(
-            (block) => `
-                Failed to locate the default Agents Server books directory.
-
-                Checked:
-                ${block(
-                    DEFAULT_AGENT_DIRECTORY_CANDIDATES.map(
-                        (candidate) => `- \`${normalizePathForLogs(candidate)}\``,
-                    ).join('\n'),
-                )}
-            `,
-        ),
-    );
-}
-
-/**
- * Normalizes path separators for diagnostics.
- *
- * @param value - Raw filesystem path.
- * @returns Slash-normalized path.
- *
- * @private function of `seedServerDefaultAgents`
- */
-function normalizePathForLogs(value: string): string {
-    return value.split('\\').join('/');
-}

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

@@ -2,9 +2,14 @@ import { $getTableName } from '@/src/database/$getTableName';
 import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
 import type { Json } from '@/src/database/schema';
 import { FILE_SECURITY_CHECKERS } from '@/src/file-security-checkers';
-import { $provideCdnForServer } from '@/src/tools/$provideCdnForServer';
+import {
+    $provideCdnForServer,
+    isSelfContainedS3StorageSelected,
+    resolveCdnPublicUrlForServer,
+} from '@/src/tools/$provideCdnForServer';
 import { $provideServer } from '@/src/tools/$provideServer';
 import { getUserFileCdnKey } from '@/src/utils/cdn/utils/getUserFileCdnKey';
+import { resolveFileUploadAvailability } from '@/src/utils/upload/fileUploadAvailability';
 import { validateMimeType } from '@/src/utils/validators/validateMimeType';
 import { normalizeChatAttachments } from '@promptbook-local/core';
 import type { TODO_any } from '@promptbook-local/types';
@@ -231,7 +236,20 @@ async function createShareTargetAttachment(file: File, maxFileUploadBytes: numbe
 
     const mimeType = resolveShareTargetMimeType(file.type);
     const blobPath = getUserFileCdnKey(buffer, normalizedFilename);
-    const cdn = $provideCdnForServer();
+    const providedServer = await $provideServer();
+    const fileUploadAvailability = resolveFileUploadAvailability({
+        serverId: providedServer.id,
+        serverPublicUrl: providedServer.publicUrl,
+        isSelfContainedS3StorageSelected: isSelfContainedS3StorageSelected(),
+    });
+
+    if (!fileUploadAvailability.isUploadAvailable) {
+        throw new NotAllowed(fileUploadAvailability.message || 'File uploads are not available for this server.');
+    }
+
+    const cdn = $provideCdnForServer({
+        cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
+    });
     const storageUrl = cdn.getItemUrl(blobPath).href;
 
     await cdn.setItem(blobPath, {

package/apps/agents-server/src/utils/upload/fileUploadAvailability.ts

@@ -0,0 +1,91 @@
+/**
+ * Message shown when self-contained file uploads cannot safely choose a serving domain.
+ */
+export const FILE_UPLOAD_REQUIRES_SERVER_DOMAIN_MESSAGE =
+    'Create the first server/domain before uploading files. Uploaded files are served from the current server domain, and raw-IP bootstrap access does not have one yet.';
+
+/**
+ * Browser-safe upload availability state.
+ */
+export type FileUploadAvailability = {
+    /**
+     * Whether file uploads may be accepted for the current request.
+     */
+    readonly isUploadAvailable: boolean;
+
+    /**
+     * User-facing reason shown when uploads are unavailable.
+     */
+    readonly message: string | null;
+};
+
+/**
+ * Inputs used to resolve whether uploads are allowed for the current server.
+ */
+export type ResolveFileUploadAvailabilityOptions = {
+    /**
+     * Current server id, or `null` before a request is matched to a server/domain.
+     */
+    readonly serverId: number | null;
+
+    /**
+     * Public URL resolved for the current request.
+     */
+    readonly serverPublicUrl: URL;
+
+    /**
+     * Whether the deployment is using the bundled self-contained S3 storage.
+     */
+    readonly isSelfContainedS3StorageSelected: boolean;
+};
+
+/**
+ * Default upload availability used when no server-side context is available.
+ */
+export const AVAILABLE_FILE_UPLOAD: FileUploadAvailability = {
+    isUploadAvailable: true,
+    message: null,
+};
+
+/**
+ * Resolves whether file uploads can be accepted for the current request.
+ *
+ * Self-contained S3 publishes files through the current server domain. While the
+ * standalone VPS is still being accessed as a bootstrap/default server, there is
+ * no server-specific domain to publish under, so uploads must be disabled.
+ *
+ * @param options - Current server and storage mode.
+ * @returns Browser-safe upload availability state.
+ */
+export function resolveFileUploadAvailability(
+    options: ResolveFileUploadAvailabilityOptions,
+): FileUploadAvailability {
+    if (!options.isSelfContainedS3StorageSelected) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    if (options.serverId !== null) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    if (isLocalDevelopmentUrl(options.serverPublicUrl)) {
+        return AVAILABLE_FILE_UPLOAD;
+    }
+
+    return {
+        isUploadAvailable: false,
+        message: FILE_UPLOAD_REQUIRES_SERVER_DOMAIN_MESSAGE,
+    };
+}
+
+/**
+ * Checks whether a server URL points to local development.
+ *
+ * @param serverPublicUrl - Public URL resolved for the current request.
+ * @returns `true` for localhost and loopback hosts.
+ */
+function isLocalDevelopmentUrl(serverPublicUrl: URL): boolean {
+    const hostname = serverPublicUrl.hostname.toLowerCase();
+
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}