@wix/mcp 1.0.95 → 1.0.96

package/build/dts/api-call/index.js

@@ -1,13 +1,21 @@
 import { z } from 'zod';
 import { HttpClient } from '@wix/http-client';
 import { logger } from '../infra/logger.js';
-import { handleWixAPIResponse } from '../tool-utils.js';
+import { buildErrorMessage, handleWixAPIResponse, missingSiteContext } from '../tool-utils.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { isApiUrlAllowed } from './validation.js';
 import { addUploadImageTool } from './upload-image-tool.js';
 import { CALL_WIX_SITE_API_NO_EXECUTE_LINE, CALL_WIX_SITE_API_RECONNECT_LINE, defaultToolDescriptions } from '../config/default-config.js';
 import { desc, WHY_NOT_EXECUTE_NO_EXECUTE, WHY_NOT_EXECUTE_RECONNECT } from '../config/param-descriptions.js';
 import { MAX_ALLOWED_RESPONSE_CHARS } from '../infra/response-size-limits.js';
+// ManageWixSite sends the account's credential and no site, which is right for the account
+// and for sites as objects in it, and wrong for anything inside a site. The site call goes
+// through ExecuteWixAPI where this server serves it, else through CallWixSiteAPI.
+const siteToolCall = (executeServed) => executeServed
+    ? "through ExecuteWixAPI with that site's `siteId` (`scope: \"site\"`), loading ExecuteWixAPI through your client's tool search if it isn't loaded"
+    : "through CallWixSiteAPI with that site's `siteId`";
+const manageNoSiteHint = (executeServed) => `This is a site-level API: it acts inside a site, and ManageWixSite sends no site, so the same call fails here every time. Call the same URL, method and body ${siteToolCall(executeServed)}.`;
+const manageEmpty403Hint = (executeServed) => `If this endpoint acts inside a site (its products, data, bookings, members, pages, publishing), it is site-level, and ManageWixSite sends no site: call the same URL, method and body ${siteToolCall(executeServed)}. If it acts on the account or on sites as objects in it, the account lacks the permission; don't retry.`;
 export { addUploadImageTool } from './upload-image-tool.js';
 const DEFAULT_MAX_RESPONSE_SIZE = 50000; // ~50KB cap
 /**
@@ -325,6 +333,20 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
                 if (!response) {
                     throw new Error(`Failed to call Wix Account API: ${error}`);
                 }
+                // A site-level API called here gets no site, and the generic hint sends the agent
+                // back to the docs for an endpoint that was right all along.
+                const noSite = missingSiteContext(response.status, response.data);
+                if (noSite) {
+                    throw new Error(buildErrorMessage({
+                        status: response.status,
+                        statusText: response.statusText,
+                        requestId: response.headers?.['x-wix-request-id'] ?? null,
+                        responseData: response.data,
+                        retryHint: (noSite === 'certain'
+                            ? manageNoSiteHint
+                            : manageEmpty403Hint)(!!options?.executeWixAPIServed)
+                    }));
+                }
                 return handleWixAPIResponse(response);
             }
         });

package/build/dts/api-call/upload-headless-website-files.d.ts

@@ -1,9 +1,20 @@
 import { type SiteFile } from './site-files.js';
 import { WixMcpServer } from '../wix-mcp-server.js';
+import { type StartDeployWebsiteFetchOptions } from '../docs/start-deploy-website.js';
+import type { HttpClient } from '@wix/http-client';
 import { type McpAuthenticationStrategy } from '../auth/index.js';
 export declare const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = "UploadHeadlessWebsiteFiles";
 /** The largest site zip `bundle-upload-url` presigns (headless-business-setup's MAX_BUNDLE_BYTES). */
 export declare const MAX_BUNDLE_BYTES: number;
+/**
+ * The static files a build's client folder can hold and still release. Builds of up to 2,550
+ * released and every one from 4,818 failed (headless-business-setup logs, October 2026): the
+ * deployments service's reply outgrows its 4 MiB gRPC limit well before its 5,000-file cap.
+ * Both failures reach us as a bare 500.
+ */
+export declare const MAX_RELEASE_STATIC_FILES = 2500;
+/** Code Store refuses a larger source zip (`REPOSITORY_ARCHIVE_TOO_LARGE`), and with it the release. */
+export declare const MAX_SOURCE_ZIP_BYTES: number;
 /**
  * Attribution the drop endpoint stamps on its upload BI event (`source` from
  * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
@@ -18,6 +29,10 @@ export interface UploadHeadlessWebsiteFilesOptions {
     fetchImpl?: typeof fetch;
     /** Client identity for drop attribution when the server cannot tell (the toolkit's configured name). */
     clientName?: string;
+    /** Where the headless guide is read from (the docs tools' portal, repo and commit overrides). */
+    guide?: StartDeployWebsiteFetchOptions;
+    /** Test seam: the headless guide's text, in place of the fetch. */
+    guideFetch?: (httpClient: HttpClient | undefined) => Promise<string | undefined>;
 }
 export declare const UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS: {
     readonly files: "The site files as text, so file bytes never pass through a code string. Sections delimited by a line `=== FILE: <path> ===` (text, raw) or `=== FILE: <path> base64 ===` (binary, base64); `<path>` is relative to the site root; a static site must include `index.html`. Use base64 for small binaries (icons, logos, fonts); large images/video belong behind a URL in the HTML, not in the bundle. Optional when `attachments` carries the files. A Wix Astro build (`.wix/build-metadata.json` and `dist/` as `astro build` with the Wix hosting adapter wrote them, zipped from the project root) needs no `index.html`: it is released to the site's Wix hosting instead of dropped, and the project's other files in the upload are stored as its source when the site's repository accepts it.";
@@ -39,6 +54,8 @@ export interface DropResult {
     uploadId?: string;
     files: string[];
 }
+/** The headless guide, inline, after a static drop: the same page StartHeadlessBuild returns. */
+export declare function formatInlineGuide(guide: string | undefined): string;
 export declare function formatDropResult(r: DropResult): string;
 /** One presigned PUT: where the zip goes and the headers the storage requires on it. */
 interface PresignedPut {
@@ -87,13 +104,25 @@ export declare function formatBundleReleaseResult(siteId: string, r: BundleRelea
  * uploaded as files the same call again (the tool asks for new URLs itself).
  */
 export type BundleRetry = 'prepare' | 'resend';
+/**
+ * The permission every owner route (drop, the upload URL, the release, the files helpers)
+ * checks on the caller for the site. A 403 naming it is about the login, not the upload: the
+ * connected Wix account is not the one that owns the site, or its role there is too low.
+ */
+export declare const SITE_ACCESS_PERMISSION = "OAUTH_APP.APP_CREATE";
+/**
+ * A 403 for the site itself, as the agent should act on it; null for any other error.
+ * `stagedKey` is the uploadKey of a build already PUT when the refusal came from the
+ * release: that upload is kept, and counts against the site's unreleased uploads.
+ */
+export declare function describeSiteAccessDenied(err: unknown, siteId?: string, stagedKey?: string): string | null;
 /** The bundle-upload-url route's errors, as the agent should act on them. */
-export declare function describeBundleUploadUrlError(err: unknown): string;
+export declare function describeBundleUploadUrlError(err: unknown, siteId?: string): string;
 /** The deployment label the service keeps is 200 characters; longer notes are cut, not refused. */
 export declare const RELEASE_NOTES_MAX_CHARS = 200;
 export declare function releaseNotesForService(notes: string): string;
 /** The release-bundle route's errors, as the agent should act on them. */
-export declare function describeBundleReleaseError(err: unknown, uploadKey: string, retry?: BundleRetry): string;
+export declare function describeBundleReleaseError(err: unknown, uploadKey: string, retry?: BundleRetry, siteId?: string): string;
 /**
  * A build that came as files, released over the bundle routes: an upload URL for the
  * site zip's size, the zip PUT there, the source zip PUT to the repository's URL when

package/build/dts/api-call/upload-headless-website-files.js

@@ -33,6 +33,8 @@ import { buildSourceFiles, findHeadlessBuild, withoutEmptyStatics } from './head
 import { fileParamNote } from '../config/file-params.js';
 import { WIX_BUSINESS_FEATURES } from '../site-widget-tools/constants.js';
 import { NO_PERSONAL_DATA } from '../docs/start-deploy-website.js';
+import { HEADLESS_GUIDE_URL } from '../docs/start-headless-build.js';
+import { fetchArticleContent } from '../docs/fetch-article.js';
 import { logger } from '../infra/logger.js';
 import { redactPersonalData } from '../infra/redact-personal-data.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
@@ -43,6 +45,15 @@ export const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = 'UploadHeadlessWebsiteFil
 const HEADLESS_BUSINESS = 'https://www.wixapis.com/headless-business-setup/v1/headless-business';
 /** The largest site zip `bundle-upload-url` presigns (headless-business-setup's MAX_BUNDLE_BYTES). */
 export const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+/**
+ * The static files a build's client folder can hold and still release. Builds of up to 2,550
+ * released and every one from 4,818 failed (headless-business-setup logs, October 2026): the
+ * deployments service's reply outgrows its 4 MiB gRPC limit well before its 5,000-file cap.
+ * Both failures reach us as a bare 500.
+ */
+export const MAX_RELEASE_STATIC_FILES = 2_500;
+/** Code Store refuses a larger source zip (`REPOSITORY_ARCHIVE_TOO_LARGE`), and with it the release. */
+export const MAX_SOURCE_ZIP_BYTES = 64 * 1024 * 1024;
 /**
  * Attribution the drop endpoint stamps on its upload BI event (`source` from
  * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
@@ -75,6 +86,19 @@ export const UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS = {
 // The wix-manage skill's recipes, which the success reply points to for what comes next.
 const UPLOAD_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md';
 const DOMAIN_RECIPE_SKILL_URL = 'https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md';
+/** The headless guide, inline, after a static drop: the same page StartHeadlessBuild returns. */
+export function formatInlineGuide(guide) {
+    if (!guide || !guide.trim())
+        return '';
+    return [
+        '',
+        '---',
+        '',
+        `Wix's headless guide, the build of a site that needs Wix business features (also at https://www.wix.com/headless/skill.md):`,
+        '',
+        guide.trim()
+    ].join('\n');
+}
 export function formatDropResult(r) {
     const shown = r.files.slice(0, 60);
     return [
@@ -87,7 +111,7 @@ export function formatDropResult(r) {
         `Give the user both links, each on its own line and named for what it is: the live site, and the site's dashboard. Then offer a custom domain, bought through Wix or one they already own (${DOMAIN_RECIPE_SKILL_URL}).`,
         '',
         `- To change this site later: "Change it later" in ${UPLOAD_RECIPE_SKILL_URL}, with this metaSiteId (${r.metaSiteId}). The same site every time, never a new one.`,
-        `- Wix business features (${WIX_BUSINESS_FEATURES}): call StartHeadlessBuild with startingPoint "an existing Wix Headless site"; this site is one.`
+        `- When the site needs Wix business features (${WIX_BUSINESS_FEATURES}), a drop of static pages is not its build: a full Wix Headless site has those features run by Wix and its pages reading from them. That build is Wix's headless guide, https://www.wix.com/headless/skill.md (what StartHeadlessBuild returns; call it with startingPoint "an existing Wix Headless site", this site is one): it installs the solution on this site, seeds its content through the API, and puts up pages that fetch it, uploaded here again. A site with no business features is done.`
     ].join('\n');
 }
 /** The curl that PUTs a zip to its presigned URL, with the headers the route returned. */
@@ -115,7 +139,7 @@ export function formatPrepareResult(siteId, urls, size, given = {}) {
     const lines = [
         `Upload URLs ready for site ${siteId}.${expiry} Two steps, then call this tool again.`,
         '',
-        `1. ${BUILD_ZIP_CONTENTS} Upload the zip you measured${size ? ` (${size} bytes)` : ''}; the URL takes a body of exactly that length, so a zip changed since needs a new prepare with its size:`,
+        `1. ${BUILD_ZIP_CONTENTS} Its client folder (\`dist/client\`) holds at most ${MAX_RELEASE_STATIC_FILES} files (\`find dist/client -type f | wc -l\`); a larger build fails the release. Upload the zip you measured${size ? ` (${size} bytes)` : ''}; the URL takes a body of exactly that length, so a zip changed since needs a new prepare with its size:`,
         `   ${curlPut('build.zip', urls, zipHeaders)}`
     ];
     // The agent's own revision wins: it is the one its project started from. Given, it is echoed
@@ -127,7 +151,7 @@ export function formatPrepareResult(siteId, urls, size, given = {}) {
         secondCall.sourceUploadId = s.uploadId;
         if (!secondCall.expectedHeadRevisionId && s.headRevisionId)
             secondCall.expectedHeadRevisionId = s.headRevisionId;
-        lines.push('', `2. ${SOURCE_ZIP_CONTENTS} Upload it:`, `   ${curlPut('source.zip', s, { 'content-type': 'application/zip' })}`, ...(s.expiresAt && s.expiresAt !== urls.expiresAt
+        lines.push('', `2. ${SOURCE_ZIP_CONTENTS} At most 64 MiB (\`wc -c < source.zip\`): a larger one fails the whole release. Leave large media and generated files out of it; if it is still larger, skip this upload and leave \`sourceUploadId\` out of the second call, and the site is released without its source. Upload it:`, `   ${curlPut('source.zip', s, { 'content-type': 'application/zip' })}`, ...(s.expiresAt && s.expiresAt !== urls.expiresAt
             ? [`   This URL expires at ${s.expiresAt}.`]
             : []), ...(s.headRevisionId
             ? [
@@ -141,6 +165,11 @@ export function formatPrepareResult(siteId, urls, size, given = {}) {
     if (given.releaseNotes)
         secondCall.releaseNotes = releaseNotesForService(given.releaseNotes);
     lines.push('', `3. Call UploadHeadlessWebsiteFiles again with ${JSON.stringify(secondCall)} (plus \`calledStartDeployWebsite\`, \`agentIdentity\`, \`reason\`). No \`files\` or \`attachments\` on that call.`);
+    if (secondCall.sourceUploadId) {
+        const withoutSource = { ...secondCall };
+        delete withoutSource.sourceUploadId;
+        lines.push(`   If you skipped the source upload in step 2, call with ${JSON.stringify(withoutSource)} instead: a \`sourceUploadId\` whose zip was never uploaded fails the release.`);
+    }
     return lines.join('\n');
 }
 /** The release-bundle reply, for both the two-call form and a build uploaded as files. */
@@ -161,11 +190,37 @@ const startOver = (retry) => retry === 'prepare'
     ? "call with `prepare: true` and the zip's `size` again, upload the zips to the new URLs, and release with the new `uploadKey`"
     : 'call this tool again with the same files';
 const apiBody = (err) => err.response.data ? ` (${err.response.data.slice(0, 300)})` : '';
+/**
+ * The permission every owner route (drop, the upload URL, the release, the files helpers)
+ * checks on the caller for the site. A 403 naming it is about the login, not the upload: the
+ * connected Wix account is not the one that owns the site, or its role there is too low.
+ */
+export const SITE_ACCESS_PERMISSION = 'OAUTH_APP.APP_CREATE';
+/**
+ * A 403 for the site itself, as the agent should act on it; null for any other error.
+ * `stagedKey` is the uploadKey of a build already PUT when the refusal came from the
+ * release: that upload is kept, and counts against the site's unreleased uploads.
+ */
+export function describeSiteAccessDenied(err, siteId, stagedKey) {
+    if (!(err instanceof WixFetchError) ||
+        err.status !== 403 ||
+        !err.response.data.includes(SITE_ACCESS_PERMISSION)) {
+        return null;
+    }
+    const site = siteId ? `site ${siteId}` : 'this site';
+    const outcome = stagedKey
+        ? `Nothing was released; the build you uploaded is still staged under uploadKey ${stagedKey} and counts against the site's unreleased uploads, so do not call \`prepare\` again and do not send the files again. The same call fails the same way until the login changes; once connected as the owning account, release that staged upload by calling with \`uploadKey: "${stagedKey}"\` before preparing a new one.`
+        : 'Nothing was uploaded, and the same call fails the same way, so do not retry and do not stage another upload.';
+    return `The connected Wix login has no rights on ${site}: Wix refused it the \`${SITE_ACCESS_PERMISSION}\` permission there. That means the site belongs to another Wix account, or this login's role on the owning account is too low (a Basic Team Member cannot upload). ${outcome} Ask the user which Wix account owns the site. Reconnecting Wix helps only if they pick that account, as its owner or an admin, at the consent screen; otherwise the owner has to give this login a higher role on the account, or move the site to it.${apiBody(err)}`;
+}
 /** The bundle-upload-url route's errors, as the agent should act on them. */
-export function describeBundleUploadUrlError(err) {
+export function describeBundleUploadUrlError(err, siteId) {
     if (!(err instanceof WixFetchError)) {
         return err instanceof Error ? err.message : String(err);
     }
+    const denied = describeSiteAccessDenied(err, siteId);
+    if (denied)
+        return denied;
     const body = apiBody(err);
     switch (err.status) {
         case 400:
@@ -198,17 +253,33 @@ export function releaseNotesForService(notes) {
             .trimEnd()}…`;
 }
 /** The release-bundle route's errors, as the agent should act on them. */
-export function describeBundleReleaseError(err, uploadKey, retry = 'prepare') {
+export function describeBundleReleaseError(err, uploadKey, retry = 'prepare', siteId) {
     if (!(err instanceof WixFetchError)) {
         return err instanceof Error ? err.message : String(err);
     }
+    const denied = describeSiteAccessDenied(err, siteId, uploadKey);
+    if (denied)
+        return denied;
     const body = apiBody(err);
     const code = err.response.data ?? '';
+    const sameCall = `calling with \`uploadKey: "${uploadKey}"\`${retry === 'resend' ? ' (plus the `expectedHeadRevisionId` and `releaseNotes` you passed, if any; the source is stored with the next release)' : ' and the same ids and `releaseNotes`'}`;
+    // A staged zip is deleted once its release succeeds, and the source it stored moves the
+    // repository's head: after a dropped connection, a 404 or a 409 on the same key is the first
+    // release having gone through.
+    const afterDrop = 'If an earlier call with this `uploadKey` ended in a dropped connection, that release went through: the site is live with this build, so do not upload it again.';
+    // The gateway lost the connection or timed out (its own body, not the service's JSON) while
+    // the release ran on. The service usually completes it.
+    if (err.status >= 502 &&
+        err.status <= 504 &&
+        !code.includes('RELEASE_NOT_HELD') &&
+        !code.includes('{')) {
+        return `The connection to Wix dropped while the release ran (HTTP ${err.status}); the release most likely went through. Do not call \`prepare\` again and do not send the files again. Wait two minutes, then check once by ${sameCall}: an answer that nothing is staged for this key, or that the repository moved, means the first release went through and the site is live. Any other answer is about the release itself.${body}`;
+    }
     switch (err.status) {
         case 404:
-            return `Nothing uploaded for uploadKey ${uploadKey}: the build zip was not PUT to its URL, or the URL expired. To try again, ${startOver(retry)}.${body}`;
+            return `Nothing uploaded for uploadKey ${uploadKey}: the build zip was not PUT to its URL, the URL expired, or a release of it already went through (a staged zip is deleted once released). ${afterDrop} Otherwise, to try again, ${startOver(retry)}.${body}`;
         case 409:
-            return `The project's source repository moved since the upload URLs were made; nothing was released. ${retry === 'prepare' ? "Call with `prepare: true` and the zip's `size` again, re-upload the source zip to the new URL, and release with the new `uploadKey`, `sourceUploadId` and `expectedHeadRevisionId`." : 'Download the project again from the repository, carry your change over, and upload with `expectedHeadRevisionId` set to the revision you downloaded.'}${body}`;
+            return `The project's source repository moved since the upload URLs were made; nothing was released by this call. ${afterDrop} Otherwise: ${retry === 'prepare' ? "call with `prepare: true` and the zip's `size` again, re-upload the source zip to the new URL, and release with the new `uploadKey`, `sourceUploadId` and `expectedHeadRevisionId`." : 'download the project again from the repository, carry your change over, and upload with `expectedHeadRevisionId` set to the revision you downloaded.'}${body}`;
         case 403:
             return `Wix refused to deploy this build onto the site's project; nothing was released, and the same call will be refused again. Do not call \`prepare\` again. Tell the user the release is blocked on Wix's side and give them the request id from the error.${body}`;
         case 413:
@@ -230,13 +301,18 @@ export function describeBundleReleaseError(err, uploadKey, retry = 'prepare') {
             return `The uploaded zip was not accepted. Zip \`dist/\` and \`.wix/build-metadata.json\` from the project root after \`astro build\` with the Wix hosting adapter, then ${startOver(retry)}. A static site goes in \`files\` or \`attachments\` instead, or is dropped as the StartDeployWebsite recipe shows.${body}`;
         default:
             if (err.status >= 500) {
-                const what = err.status === 503
+                const what = code.includes('RELEASE_NOT_HELD')
                     ? 'The release could not hold its upload'
                     : `Wix's release step failed on its side (HTTP ${err.status})`;
+                // The two-call form's zips are the agent's own, so they can be over the limits the
+                // service reports only as a 500; the one-call form's upload is capped below them.
+                const limits = retry === 'prepare' && !code.includes('RELEASE_NOT_HELD')
+                    ? ` A build over Wix's limits fails here with no reason given: more than ${MAX_RELEASE_STATIC_FILES} files in its client folder (\`find dist/client -type f | wc -l\`), or a source zip over 64 MiB (\`wc -c < source.zip\`). If either is over, a retry fails the same way: make the build or the source zip smaller, then call with \`prepare: true\` again.`
+                    : '';
                 // Both forms retry the staged upload itself: the two-call form with its uploadKey, the
                 // one-call form by switching to that key instead of sending the files again, which would
                 // stage another upload. One retry, then the user hears the request id.
-                return `${what}; nothing was released. The staged upload is kept under uploadKey ${uploadKey}, so do not call \`prepare\` again and do not send the files again: every upload staged and not released counts against the site, which refuses new ones after a few. Retry once, after a minute, by calling with \`uploadKey: "${uploadKey}"\`${retry === 'resend' ? ' (plus the `expectedHeadRevisionId` and `releaseNotes` you passed, if any; the source is stored with the next release)' : ' and the same ids and `releaseNotes`'}. If that fails too, stop and tell the user the release is blocked on Wix's side, with the request id from the error.${body}`;
+                return `${what}; nothing was released.${limits} The staged upload is kept under uploadKey ${uploadKey}, so do not call \`prepare\` again${limits ? ' for the same zips' : ''} and do not send the files again: every upload staged and not released counts against the site, which refuses new ones after a few. Retry once, after a minute, by ${sameCall}. If that fails too, stop and tell the user the release is blocked on Wix's side, with the request id from the error.${body}`;
             }
             return err.message;
     }
@@ -358,6 +434,12 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
         server.clientName?.() ??
         server.server?.getClientVersion?.()?.name;
     const fetchImpl = options.fetchImpl ?? ((u, i) => fetch(u, i));
+    const guideFetch = options.guideFetch ??
+        (async (httpClient) => {
+            if (!httpClient)
+                return undefined;
+            return fetchArticleContent(httpClient, HEADLESS_GUIDE_URL, 'article', true, options.guide?.skillsPortalUrl, options.guide?.repo, options.guide?.commitHash);
+        });
     const d = UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS;
     const registered = server.tool(UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME, toolDescriptions?.[UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME] ??
         defaultToolDescriptions.UploadHeadlessWebsiteFiles, {
@@ -474,8 +556,8 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                 rethrowIfUnauthorized(err);
                 await authStrategy.enforceValidWixToken?.(err);
                 return errorResult(uploadKey
-                    ? describeBundleReleaseError(err, uploadKey)
-                    : describeBundleUploadUrlError(err));
+                    ? describeBundleReleaseError(err, uploadKey, 'prepare', siteId)
+                    : describeBundleUploadUrlError(err, siteId));
             }
         }
         if (!files?.trim() && !(attachments && attachments.length)) {
@@ -571,8 +653,8 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                 rethrowIfUnauthorized(err);
                 await authStrategy.enforceValidWixToken?.(err);
                 return errorResult(stagedKey
-                    ? describeBundleReleaseError(err, stagedKey, 'resend')
-                    : describeBundleUploadUrlError(err));
+                    ? describeBundleReleaseError(err, stagedKey, 'resend', siteId)
+                    : describeBundleUploadUrlError(err, siteId));
             }
         }
         // 2. Account auth (outside the try so UnauthorizedError reaches the wrapper).
@@ -590,6 +672,15 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                 siteId: metaSiteId,
                 upload: { path: 'drop', files: siteFiles.length }
             });
+            // The headless guide rides along, inline: a static drop is not the build of a site
+            // that needs Wix business features, and the agent that stops here has read nothing else.
+            let guide;
+            try {
+                guide = await guideFetch(extra?.httpClient);
+            }
+            catch (e) {
+                logger.log(`[UploadHeadlessWebsiteFiles] guide fetch failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
             return {
                 content: [
                     {
@@ -602,7 +693,8 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
                         }) +
                             (releaseNotes
                                 ? '\n\nRelease notes are kept for a Wix Astro build only; a static drop has none, so yours were not stored.'
-                                : '')
+                                : '') +
+                            formatInlineGuide(guide)
                     }
                 ]
             };
@@ -612,7 +704,7 @@ export function addUploadHeadlessWebsiteFilesTool(server, options) {
             logger.log(`[UploadHeadlessWebsiteFiles] Error: ${message}`);
             rethrowIfUnauthorized(err);
             await authStrategy.enforceValidWixToken?.(err);
-            return errorResult(message);
+            return errorResult(describeSiteAccessDenied(err, siteId) ?? message);
         }
     });
     // ChatGPT resolves `attachments` into download URLs only for params listed

package/build/dts/code-mode/attachments.d.ts

@@ -1,11 +1,13 @@
 /**
- * ChatGPT file attachments for ExecuteWixAPI (`openai/fileParams`).
+ * Chat file attachments for ExecuteWixAPI (`openai/fileParams`).
  *
  * ChatGPT resolves a file the user attached — or one the model wrote in its
  * own sandbox — into `{ download_url, file_id, file_name?, mime_type? }` for a
- * param the tool lists under `_meta["openai/fileParams"]`. The bytes never go
- * through the model. We fetch each `download_url` host-side and hand the
- * runtime ready-made base64 file entries, the same shape the `files` bundle
+ * param the tool lists under `_meta["openai/fileParams"]`. For ExecuteWixAPI the
+ * Wix AI Assistant (Aria) does the same by swapping an `attachment://<id>`
+ * reference in the tool args for a signed URL on its own Wix storage. The
+ * bytes never go through the model. We fetch each `download_url` host-side and
+ * hand the runtime ready-made base64 file entries, the same shape the `files` bundle
  * parses into, so `files`, `wix.multipart()` and `wix.unzip()` are unchanged.
  *
  * This is additive: clients without the extension never populate the param
@@ -24,7 +26,8 @@ export interface AttachmentFile {
     encoding: 'base64';
 }
 export declare const MAX_ATTACHMENTS_BYTES: number;
-export declare function isAllowedAttachmentHost(hostname: string): boolean;
+export declare const WIX_AI_ASSISTANT_ATTACHMENT_HOSTS: ReadonlySet<string>;
+export declare function isAllowedAttachmentHost(hostname: string, extraHosts?: ReadonlySet<string>): boolean;
 export declare class AttachmentError extends Error {
 }
 /**
@@ -33,5 +36,5 @@ export declare class AttachmentError extends Error {
  * (ChatGPT passed a sandbox path or a bare id instead of a URL), a host we
  * don't trust, a failed download, or more bytes than MAX_ATTACHMENTS_BYTES.
  */
-export declare function resolveAttachments(attachments: unknown, fetchImpl?: typeof fetch): Promise<AttachmentFile[]>;
+export declare function resolveAttachments(attachments: unknown, fetchImpl?: typeof fetch, extraHosts?: ReadonlySet<string>): Promise<AttachmentFile[]>;
 //# sourceMappingURL=attachments.d.ts.map

package/build/dts/code-mode/attachments.js

@@ -1,11 +1,13 @@
 /**
- * ChatGPT file attachments for ExecuteWixAPI (`openai/fileParams`).
+ * Chat file attachments for ExecuteWixAPI (`openai/fileParams`).
  *
  * ChatGPT resolves a file the user attached — or one the model wrote in its
  * own sandbox — into `{ download_url, file_id, file_name?, mime_type? }` for a
- * param the tool lists under `_meta["openai/fileParams"]`. The bytes never go
- * through the model. We fetch each `download_url` host-side and hand the
- * runtime ready-made base64 file entries, the same shape the `files` bundle
+ * param the tool lists under `_meta["openai/fileParams"]`. For ExecuteWixAPI the
+ * Wix AI Assistant (Aria) does the same by swapping an `attachment://<id>`
+ * reference in the tool args for a signed URL on its own Wix storage. The
+ * bytes never go through the model. We fetch each `download_url` host-side and
+ * hand the runtime ready-made base64 file entries, the same shape the `files` bundle
  * parses into, so `files`, `wix.multipart()` and `wix.unzip()` are unchanged.
  *
  * This is additive: clients without the extension never populate the param
@@ -26,7 +28,7 @@ const MAX_REDIRECTS = 4;
 // - Azure blob accounts behind them, one per OpenAI region.
 //   `blob.core.windows.net` is a shared namespace, so these are exact — a
 //   prefix could be registered by anyone. A new region shows up as an
-//   "is not a ChatGPT file host" error in BI; add it here.
+//   "is not a chat attachment host" error in BI; add it here.
 const OAI_USERCONTENT_HOST = /^[a-z0-9-]+\.oaiusercontent\.com$/;
 const OAI_BLOB_ACCOUNTS = new Set([
     'australiaeast',
@@ -55,18 +57,23 @@ const OAI_BLOB_ACCOUNTS = new Set([
     'westus2',
     'westus3'
 ].map((region) => `oaisdmntpr${region}.blob.core.windows.net`));
-export function isAllowedAttachmentHost(hostname) {
+export const WIX_AI_ASSISTANT_ATTACHMENT_HOSTS = new Set([
+    'wixmp-a85a29aaf55baa3e5171a82d.wixmp.com'
+]);
+export function isAllowedAttachmentHost(hostname, extraHosts) {
     const h = hostname.toLowerCase();
-    return OAI_USERCONTENT_HOST.test(h) || OAI_BLOB_ACCOUNTS.has(h);
+    return (OAI_USERCONTENT_HOST.test(h) ||
+        OAI_BLOB_ACCOUNTS.has(h) ||
+        !!extraHosts?.has(h));
 }
 /** https, default port, allowed host — applied to the first URL and every redirect. */
-function checkAttachmentUrl(url) {
+function checkAttachmentUrl(url, extraHosts) {
     if (url.protocol !== 'https:')
         return 'is not an https URL';
     if (url.port)
         return 'uses a non-default port';
-    if (!isAllowedAttachmentHost(url.hostname)) {
-        return `host "${url.hostname}" is not a ChatGPT file host`;
+    if (!isAllowedAttachmentHost(url.hostname, extraHosts)) {
+        return `host "${url.hostname}" is not a chat attachment host`;
     }
     return undefined;
 }
@@ -98,7 +105,7 @@ function toBase64(bytes) {
  * GET with manual redirects: every hop must pass checkAttachmentUrl, so an
  * allowed host cannot bounce the server to an arbitrary or internal one.
  */
-async function fetchAllowed(start, fetchImpl, label) {
+async function fetchAllowed(start, fetchImpl, label, extraHosts) {
     let url = start;
     for (let hop = 0;; hop++) {
         const res = await fetchImpl(url.toString(), { redirect: 'manual' });
@@ -117,7 +124,7 @@ async function fetchAllowed(start, fetchImpl, label) {
         catch {
             throw new AttachmentError(`${label}: redirect to an invalid URL.`);
         }
-        const problem = checkAttachmentUrl(next);
+        const problem = checkAttachmentUrl(next, extraHosts);
         if (problem) {
             throw new AttachmentError(`${label}: the download redirected to a URL that ${problem}; refused.`);
         }
@@ -166,7 +173,7 @@ async function readWithin(res, budget, overBudget) {
  * (ChatGPT passed a sandbox path or a bare id instead of a URL), a host we
  * don't trust, a failed download, or more bytes than MAX_ATTACHMENTS_BYTES.
  */
-export async function resolveAttachments(attachments, fetchImpl = fetch) {
+export async function resolveAttachments(attachments, fetchImpl = fetch, extraHosts) {
     if (!Array.isArray(attachments) || attachments.length === 0)
         return [];
     const items = [];
@@ -185,9 +192,9 @@ export async function resolveAttachments(attachments, fetchImpl = fetch) {
         if (!a || !url) {
             throw new AttachmentError(`attachments[${i}] was not resolved to a download URL (got ${JSON.stringify(typeof raw === 'string' ? raw : ((a && a.download_url) ?? raw))}). \`attachments\` works only in ChatGPT, which swaps each file for a download URL before the call reaches Wix. Here it arrived as written, and Wix cannot read a path on your machine, so retrying the same value fails the same way. Upload another way. With a shell that reaches the internet, send the file from there (for a site, the StartDeployWebsite recipe's curl drop). Otherwise leave \`attachments\` out and put the files in \`files\`: text as is, and a binary as a \`=== FILE: <path> base64 ===\` entry only when it is a few KB (an icon, a logo), since a larger base64 payload does not survive your own output. A larger image goes in by public URL or through the user (the Media Manager).`);
         }
-        const problem = checkAttachmentUrl(url);
+        const problem = checkAttachmentUrl(url, extraHosts);
         if (problem) {
-            throw new AttachmentError(`attachments[${i}].download_url ${problem}. Only platform-resolved attachments are accepted here; for any other URL fetch it in \`code\` via wix.request or put the bytes in the \`files\` bundle.`);
+            throw new AttachmentError(`attachments[${i}].download_url ${problem}. \`attachments\` takes only files the chat platform attached and resolved; leave it out. For a file at a URL, import it in \`code\` with \`POST https://www.wixapis.com/site-media/v1/files/import\` and \`{ url }\` (Wix fetches it); for a small file you have as text, use the \`files\` bundle.`);
         }
         items.push({ a, url });
     });
@@ -198,7 +205,7 @@ export async function resolveAttachments(attachments, fetchImpl = fetch) {
         const label = `attachments[${i}] (${path})`;
         let res;
         try {
-            res = await fetchAllowed(url, fetchImpl, label);
+            res = await fetchAllowed(url, fetchImpl, label, extraHosts);
         }
         catch (e) {
             if (e instanceof AttachmentError)

package/build/dts/code-mode/index.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AttachmentError, resolveAttachments } from './attachments.js';
+import { AttachmentError, WIX_AI_ASSISTANT_ATTACHMENT_HOSTS, resolveAttachments } from './attachments.js';
 import { fileParamNote } from '../config/file-params.js';
 import { logger } from '../infra/logger.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
@@ -328,7 +328,7 @@ function addExecuteTool(server, options) {
         // an agent-facing error, not a server failure.
         let attachmentFiles = [];
         try {
-            attachmentFiles = await resolveAttachments(attachments);
+            attachmentFiles = await resolveAttachments(attachments, undefined, WIX_AI_ASSISTANT_ATTACHMENT_HOSTS);
         }
         catch (e) {
             if (e instanceof AttachmentError)

package/build/dts/config/default-config.d.ts

@@ -41,7 +41,7 @@ export declare const HELP_CENTER_IS_FOR_PEOPLE = "The Help Center is written for
  * Each tool named here carries a comment pointing back to this text. A change to any of them (a
  * name, what it is for, a new site-creation tool) updates this text and that list with it.
  */
-export declare const SERVER_INSTRUCTIONS = "Wix: build and manage Wix sites. A new site is written in code and uploaded: StartDeployWebsite returns the upload guide; StartHeadlessBuild returns the headless guide, for a site that needs Wix business features (forms, a store, bookings, a CMS, members, payments). WixSiteBuilder or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. For anything else, except ListWixSites and UploadImageToWixSite, call WixREADME first.";
+export declare const SERVER_INSTRUCTIONS = "Wix: build and manage Wix sites. A new site is written in code and uploaded: StartDeployWebsite returns the upload guide; StartHeadlessBuild returns the headless guide, for a site that needs Wix business features (forms, a store, bookings, a CMS, members, payments). WixHarmonyEditorBuild or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. Call WixREADME first, except ListWixSites, UploadImageToWixSite, GetSuggestedDomains.";
 /** The tools SERVER_INSTRUCTIONS names. */
 export declare const SERVER_INSTRUCTIONS_TOOLS: string[];
 export declare const SITE_CREATION_COPY: {