@promptbook/cli 0.112.0-102 → 0.112.0-104

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

@@ -3,87 +3,125 @@ import { DigitalOceanSpaces } from '../utils/cdn/classes/DigitalOceanSpaces';
 import { TrackedFilesStorage } from '../utils/cdn/classes/TrackedFilesStorage';
 import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
-import { resolveCdnStorageProvider } from '../utils/cdn/resolveCdnStorageProvider';
 
 /**
- * Environment value that enables path-style S3 requests.
+ * Region expected by the bundled VersityGW S3-compatible storage.
  *
- * @private internal cache for `$provideCdnForServer`
+ * @private internal default for `$provideCdnForServer`
  */
-const TRUE_ENV_VALUE = 'true';
+const SELF_CONTAINED_S3_DEFAULT_REGION = 'us-east-1';
 
 /**
- * Cache of raw CDN instance.
+ * Legacy fallback used by Cloudflare R2-style external S3 configuration.
  *
- * @private internal cache for `$provideCdnForServer`
+ * @private internal default for `$provideCdnForServer`
  */
-let rawCdn: IIFilesStorageWithCdn | null = null;
+const EXTERNAL_S3_DEFAULT_REGION = 'auto';
 
 /**
- * Cache of tracked CDN instance.
+ * Cache of CDN instance
  *
  * @private internal cache for `$provideCdnForServer`
  */
-let trackedCdn: IIFilesStorageWithCdn | null = null;
+let cdn: IIFilesStorageWithCdn | null = null;
 
 /**
- * Creates a CDN storage instance from environment variables.
+ * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ */
+export function $provideCdnForServer(): IIFilesStorageWithCdn {
+    if (!cdn) {
+        const inner = createCdnStorageForServer();
+        const supabase = $provideSupabaseForServer();
+        cdn = new TrackedFilesStorage(inner, supabase);
+    }
+
+    return cdn;
+}
+
+/**
+ * Creates the configured CDN storage implementation for server-side file operations.
  *
- * @private internal factory for `$provideCdnForServer`
+ * @private helper of `$provideCdnForServer`
  */
-function createCdnForServer(): IIFilesStorageWithCdn {
-    const provider = resolveCdnStorageProvider();
-
-    switch (provider) {
-        case 's3':
-            return new DigitalOceanSpaces({
-                bucket: process.env.CDN_BUCKET!,
-                pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
-                endpoint: process.env.CDN_ENDPOINT!,
-                region: process.env.CDN_REGION || 'auto',
-                accessKeyId: process.env.CDN_ACCESS_KEY_ID!,
-                secretAccessKey: process.env.CDN_SECRET_ACCESS_KEY!,
-                cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
-                gzip: process.env.CDN_GZIP !== 'false',
-                forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === TRUE_ENV_VALUE,
-                isPublicReadAclEnabled: process.env.CDN_ENABLE_PUBLIC_READ_ACL !== 'false',
-            });
-
-        case 'vercel':
-            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!),
-            });
+function createCdnStorageForServer(): IIFilesStorageWithCdn {
+    if (isS3CompatibleStorageSelected()) {
+        return new DigitalOceanSpaces({
+            bucket: process.env.CDN_BUCKET!,
+            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
+            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!),
+            gzip: true,
+            forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
+            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!),
+    });
 }
 
 /**
- * Provides an untracked CDN storage interface for code paths that manage `File` rows themselves.
+ * Checks whether the current environment should use the S3-compatible storage implementation.
  *
- * @private internal cache for `$provideCdnForServer`
+ * @private helper of `$provideCdnForServer`
  */
-export function $provideUntrackedCdnForServer(): IIFilesStorageWithCdn {
-    if (!rawCdn) {
-        rawCdn = createCdnForServer();
+function isS3CompatibleStorageSelected(): boolean {
+    const storageMode = getS3CompatibleStorageMode();
+    const isS3StorageMode =
+        storageMode === 's3' || storageMode === 'external-s3' || storageMode === 'self-contained-s3';
+
+    if (isS3StorageMode) {
+        return hasS3CompatibleStorageConfiguration();
     }
 
-    return rawCdn;
+    return !process.env.VERCEL_BLOB_READ_WRITE_TOKEN && hasS3CompatibleStorageConfiguration();
 }
 
 /**
- * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ * Resolves the configured S3-compatible storage mode.
  *
- * @private internal cache for `$provideCdnForServer`
+ * @private helper of `$provideCdnForServer`
  */
-export function $provideCdnForServer(): IIFilesStorageWithCdn {
-    if (!trackedCdn) {
-        const inner = $provideUntrackedCdnForServer();
-        const supabase = $provideSupabaseForServer();
-        trackedCdn = new TrackedFilesStorage(inner, supabase);
+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;
     }
 
-    return trackedCdn;
+    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.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function hasS3CompatibleStorageConfiguration(): boolean {
+    return Boolean(
+        process.env.CDN_BUCKET &&
+            process.env.CDN_ENDPOINT &&
+            process.env.CDN_ACCESS_KEY_ID &&
+            process.env.CDN_SECRET_ACCESS_KEY &&
+            process.env.NEXT_PUBLIC_CDN_PUBLIC_URL,
+    );
 }
 
 // TODO: [🏓] Unite `xxxForServer` and `xxxForNode` naming

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/cdn/classes/DigitalOceanSpaces.ts

@@ -12,45 +12,16 @@ type IDigitalOceanSpacesConfig = {
     readonly bucket: string;
     readonly pathPrefix: string;
     readonly endpoint: string;
-    readonly region?: string;
     readonly accessKeyId: string;
     readonly secretAccessKey: string;
     readonly cdnPublicUrl: URL;
     readonly gzip: boolean;
     readonly forcePathStyle?: boolean;
-    readonly isPublicReadAclEnabled?: boolean;
+    readonly region?: string;
 
     // TODO: [⛳️] Probbably prefix should be in this config not on the consumer side
 };
 
-/**
- * Resolves the S3 endpoint URL, preserving explicit `http` endpoints for local MinIO.
- *
- * @private internal helper for DigitalOceanSpaces.
- */
-function resolveS3Endpoint(endpoint: string): string {
-    if (/^https?:\/\//i.test(endpoint)) {
-        return endpoint;
-    }
-
-    return `https://${endpoint}`;
-}
-
-/**
- * Returns a URL object whose pathname ends with `/`.
- *
- * @private internal helper for DigitalOceanSpaces.
- */
-function ensureTrailingSlashUrl(url: URL): URL {
-    const normalizedUrl = new URL(url.href);
-
-    if (!normalizedUrl.pathname.endsWith('/')) {
-        normalizedUrl.pathname = `${normalizedUrl.pathname}/`;
-    }
-
-    return normalizedUrl;
-}
-
 /**
  * Class implementing digital ocean spaces.
  */
@@ -64,7 +35,7 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     public constructor(private readonly config: IDigitalOceanSpacesConfig) {
         this.s3 = new S3Client({
             region: config.region || 'auto',
-            endpoint: resolveS3Endpoint(config.endpoint),
+            endpoint: normalizeS3Endpoint(config.endpoint),
             forcePathStyle: config.forcePathStyle,
             credentials: {
                 accessKeyId: config.accessKeyId,
@@ -74,13 +45,13 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     }
 
     public getItemUrl(key: string): URL {
-        return new URL(this.getStorageKey(key), ensureTrailingSlashUrl(this.cdnPublicUrl));
+        return new URL(this.config.pathPrefix + '/' + key, this.cdnPublicUrl);
     }
 
     public async getItem(key: string): Promise<IFile | null> {
         const parameters = {
             Bucket: this.config.bucket,
-            Key: this.getStorageKey(key),
+            Key: this.config.pathPrefix + '/' + key,
         };
 
         try {
@@ -136,12 +107,12 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
         const uploadResult = await this.s3.send(
             new PutObjectCommand({
                 Bucket: this.config.bucket,
-                Key: this.getStorageKey(key),
+                Key: this.config.pathPrefix + '/' + key,
                 ContentType: processedFile.type,
                 ...putObjectRequestAdditional,
                 Body: processedFile.data,
                 // TODO: Public read access / just private to extending class
-                ...(this.config.isPublicReadAclEnabled === false ? {} : { ACL: 'public-read' }),
+                ACL: 'public-read',
             }),
         );
 
@@ -149,22 +120,19 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
             throw new Error(`Upload result does not contain ETag`);
         }
     }
+}
 
-    /**
-     * Builds the final object key used in the S3 bucket.
-     *
-     * @private internal helper for DigitalOceanSpaces.
-     */
-    private getStorageKey(key: string): string {
-        const normalizedKey = key.replace(/^\/+/g, '');
-        const normalizedPathPrefix = this.config.pathPrefix.replace(/^\/+|\/+$/g, '');
-
-        if (!normalizedPathPrefix) {
-            return normalizedKey;
-        }
-
-        return `${normalizedPathPrefix}/${normalizedKey}`;
+/**
+ * Normalizes endpoint values from legacy host-only configuration and full S3 URLs.
+ *
+ * @private helper of `DigitalOceanSpaces`
+ */
+function normalizeS3Endpoint(endpoint: string): string {
+    if (/^https?:\/\//i.test(endpoint)) {
+        return endpoint;
     }
+
+    return `https://${endpoint}`;
 }
 
 // TODO: Implement Read-only mode

package/apps/agents-server/src/utils/cdn/classes/TrackedFilesStorage.ts

@@ -37,17 +37,20 @@ export class TrackedFilesStorage implements IIFilesStorageWithCdn {
 
         try {
             const { userId, purpose } = file;
-            const storageUrl = this.getItemUrl(key).href;
+            const cdnUrl = this.getItemUrl(key).href;
+            const securityResult =
+                file.securityResult as AgentsServerDatabase['public']['Tables']['File']['Insert']['securityResult'];
 
             await this.supabase.from(await $getTableName('File')).insert({
                 userId: userId || null,
                 fileName: key,
                 fileSize: file.fileSize ?? file.data.length,
                 fileType: file.type,
-                storageUrl,
+                storageUrl: cdnUrl,
                 shortUrl: null,
                 purpose: purpose || 'UNKNOWN',
                 status: 'COMPLETED',
+                securityResult: securityResult || null,
             });
         } catch (error) {
             console.error('Failed to track upload:', error);

package/apps/agents-server/src/utils/cdn/interfaces/IFilesStorage.ts

@@ -25,6 +25,11 @@ export type IFile = {
      * Note: This is optional, if not provided, the size of the buffer is used
      */
     fileSize?: number;
+
+    /**
+     * Optional file security result collected before the file is tracked.
+     */
+    securityResult?: Record<string, unknown>;
 };
 
 /**