@wix/mcp 1.0.93 → 1.0.94

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

@@ -84,10 +84,13 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
                 reason: z.string().describe(d.reason),
                 sourceDocUrl: z.string().describe(d.sourceDocUrl)
             };
-        })(), getHints('CallWixSiteAPI', {
+        })(), 
+        // openWorldHint true: a free-form URL into the whole Wix REST surface is an
+        // open-ended target, even though auth is bounded to the user's account.
+        getHints('CallWixSiteAPI', {
             readOnlyHint: false,
             destructiveHint: true,
-            openWorldHint: false
+            openWorldHint: true
         }), async ({ url, body, method, siteId, reason, sourceDocUrl }, { httpClient, setToolBiParams }) => {
             logger.log(`[CallWixSiteAPI] siteId=${siteId}, method=${method}, url=${url}, sourceDocUrl=${sourceDocUrl}, reason="${reason}", body=${JSON.stringify(body)}`);
             const requestHeaders = {
@@ -255,7 +258,7 @@ export function addApiCallTool(server, strategy, allowedTools = ['CallWixSiteAPI
         })(), getHints('ManageWixSite', {
             readOnlyHint: false,
             destructiveHint: true,
-            openWorldHint: false
+            openWorldHint: true
         }), async ({ url, body, method, reason }, { httpClient, setToolBiParams }) => {
             logger.log(`Calling Wix Account level API: ${url}, reason="${reason}", body: ${JSON.stringify(body)}`);
             const { isAllowed, error: urlError } = isApiUrlAllowed(url);

package/build/dts/api-call/site-files.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Site files for UploadHeadlessWebsiteFiles, handled directly in the tool (no sandbox):
+ * the `=== FILE: … ===` text bundle, zip extraction, site-shape checks and the
+ * multipart body for the drop endpoint. Same formats the code-mode runtime
+ * accepts, so an agent can switch between ExecuteWixAPI and this tool freely.
+ */
+export interface SiteFile {
+    path: string;
+    bytes: Uint8Array;
+}
+export declare const MAX_FILES_BUNDLE_CHARS = 4000000;
+export declare const MAX_UNZIP_BYTES: number;
+export declare const MAX_SITE_FILES = 2000;
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Parse the `=== FILE: <path> ===` / `=== FILE: <path> base64 ===` bundle into bytes. */
+export declare function parseFileBundle(bundle: string | undefined): SiteFile[];
+/** Unzip (stored + deflate entries) into raw bytes. Validates the EOCD and the declared sizes. */
+export declare function unzip(z: Uint8Array): Promise<SiteFile[]>;
+export declare const isZip: (f: SiteFile) => boolean;
+/**
+ * Turn the raw inputs into the file set to drop: unpack zips, drop junk, strip a
+ * single wrapping folder, require a root index.html. Throws an agent-facing error.
+ */
+export declare function normalizeSiteFiles(input: SiteFile[]): Promise<SiteFile[]>;
+export declare function guessContentType(path: string): string;
+/** The drop endpoint's body: one `files` part per file, the path as the filename. */
+export declare function buildFormData(files: SiteFile[]): FormData;
+//# sourceMappingURL=site-files.d.ts.map

package/build/dts/api-call/site-files.js

@@ -0,0 +1,194 @@
+/**
+ * Site files for UploadHeadlessWebsiteFiles, handled directly in the tool (no sandbox):
+ * the `=== FILE: … ===` text bundle, zip extraction, site-shape checks and the
+ * multipart body for the drop endpoint. Same formats the code-mode runtime
+ * accepts, so an agent can switch between ExecuteWixAPI and this tool freely.
+ */
+// Keep the bundle to text + small base64 assets; large media belongs behind a URL.
+export const MAX_FILES_BUNDLE_CHARS = 4_000_000;
+// A dropped site is capped at 20 MB; anything expanding near this is a bomb.
+export const MAX_UNZIP_BYTES = 64 * 1024 * 1024;
+export const MAX_SITE_FILES = 2_000;
+const textEncoder = new TextEncoder();
+export function base64ToBytes(b64) {
+    const clean = b64.replace(/^data:[^,]*,/, '').replace(/\s+/g, '');
+    return Uint8Array.from(atob(clean), (c) => c.charCodeAt(0));
+}
+/** Parse the `=== FILE: <path> ===` / `=== FILE: <path> base64 ===` bundle into bytes. */
+export function parseFileBundle(bundle) {
+    if (!bundle || !bundle.trim())
+        return [];
+    if (bundle.length > MAX_FILES_BUNDLE_CHARS) {
+        throw new Error(`files bundle is too large (${bundle.length} chars; max ${MAX_FILES_BUNDLE_CHARS}). Keep it to text and small base64 assets; pass larger files through attachments or reference media by URL.`);
+    }
+    const delimiter = /^=== FILE: (.+?)(?: (base64))? ===[ \t]*$/gm;
+    const matches = [...bundle.matchAll(delimiter)];
+    if (matches.length === 0) {
+        throw new Error('files bundle has no `=== FILE: <path> ===` sections. Start each file with that line (add ` base64` before the closing === for binary content).');
+    }
+    return matches.map((match, i) => {
+        const path = match[1].trim();
+        const start = (match.index ?? 0) + match[0].length;
+        const end = i + 1 < matches.length
+            ? (matches[i + 1].index ?? bundle.length)
+            : bundle.length;
+        const content = bundle
+            .slice(start, end)
+            .replace(/^\r?\n/, '')
+            .replace(/\r?\n$/, '');
+        return {
+            path,
+            bytes: match[2] === 'base64'
+                ? base64ToBytes(content)
+                : textEncoder.encode(content)
+        };
+    });
+}
+/** Unzip (stored + deflate entries) into raw bytes. Validates the EOCD and the declared sizes. */
+export async function unzip(z) {
+    const u16 = (o) => z[o] | (z[o + 1] << 8);
+    const u32 = (o) => (u16(o) | (u16(o + 2) << 16)) >>> 0;
+    let end = z.length - 22;
+    while (end >= 0 &&
+        !(u32(end) === 0x06054b50 && end + 22 + u16(end + 20) === z.length))
+        end--;
+    if (end < 0)
+        throw new Error('not a zip file (no end-of-central-directory)');
+    const out = [];
+    let p = u32(end + 16);
+    let total = 0;
+    const decoder = new TextDecoder();
+    for (let i = 0, n = u16(end + 10); i < n; i++) {
+        const path = decoder.decode(z.slice(p + 46, p + 46 + u16(p + 28)));
+        const method = u16(p + 10);
+        const size = u32(p + 24);
+        total += size;
+        if (total > MAX_UNZIP_BYTES) {
+            throw new Error(`zip expands past ${MAX_UNZIP_BYTES} bytes; a static site is at most 20 MB`);
+        }
+        const at = u32(p + 42);
+        const start = at + 30 + u16(at + 26) + u16(at + 28);
+        const comp = z.slice(start, start + u32(p + 20));
+        p += 46 + u16(p + 28) + u16(p + 30) + u16(p + 32);
+        if (path.endsWith('/'))
+            continue; // directory entry
+        let bytes;
+        if (method === 0)
+            bytes = comp;
+        else if (method === 8) {
+            bytes = new Uint8Array(await new Response(new Blob([comp])
+                .stream()
+                .pipeThrough(new DecompressionStream('deflate-raw'))).arrayBuffer());
+        }
+        else
+            throw new Error(`zip entry '${path}' uses unsupported compression method ${method}`);
+        if (bytes.length !== size) {
+            throw new Error(`zip entry '${path}' declares ${size} bytes but holds ${bytes.length}`);
+        }
+        out.push({ path, bytes });
+    }
+    return out;
+}
+// A zip is recognised by its bytes (local-file-header or empty-archive signature), not its name:
+// an attachment can arrive without a file name, and a zip's path then carries no extension.
+export const isZip = (f) => (f.bytes.length >= 4 &&
+    f.bytes[0] === 0x50 &&
+    f.bytes[1] === 0x4b &&
+    ((f.bytes[2] === 0x03 && f.bytes[3] === 0x04) ||
+        (f.bytes[2] === 0x05 && f.bytes[3] === 0x06))) ||
+    /\.zip$/i.test(f.path);
+const isRootIndex = (p) => /^index\.html?$/i.test(p);
+/**
+ * Turn the raw inputs into the file set to drop: unpack zips, drop junk, strip a
+ * single wrapping folder, require a root index.html. Throws an agent-facing error.
+ */
+export async function normalizeSiteFiles(input) {
+    let list = [];
+    for (const f of input) {
+        if (isZip(f))
+            list.push(...(await unzip(f.bytes)));
+        else
+            list.push(f);
+    }
+    list = list
+        .map((f) => ({
+        ...f,
+        path: f.path.replace(/\\/g, '/').replace(/^\.?\//, '')
+    }))
+        .filter((f) => f.path &&
+        !f.path.startsWith('__MACOSX/') &&
+        !/(^|\/)\.DS_Store$/.test(f.path) &&
+        !f.path.split('/').includes('..'));
+    if (list.length === 0) {
+        throw new Error('No files to upload: pass the site in `files` or `attachments`.');
+    }
+    if (list.length > MAX_SITE_FILES) {
+        throw new Error(`Too many files (${list.length}); a site upload is at most ${MAX_SITE_FILES}.`);
+    }
+    // A zip of a folder: strip the single top-level directory so index.html sits at the root.
+    if (!list.some((f) => isRootIndex(f.path))) {
+        const first = list[0].path.split('/')[0];
+        if (list.every((f) => f.path.includes('/') && f.path.split('/')[0] === first)) {
+            list = list.map((f) => ({
+                ...f,
+                path: f.path.split('/').slice(1).join('/')
+            }));
+        }
+    }
+    // A single root HTML file is the homepage whatever its name — the drop endpoint's
+    // own rule (headless-business-setup renameToIndexHtml), applied here so the
+    // shape check below doesn't reject what the endpoint would accept.
+    const rootHtml = list.filter((f) => !f.path.includes('/') && /\.html?$/i.test(f.path));
+    if (!list.some((f) => isRootIndex(f.path)) && rootHtml.length === 1) {
+        list = list.map((f) => f === rootHtml[0] ? { ...f, path: 'index.html' } : f);
+    }
+    if (!list.some((f) => isRootIndex(f.path))) {
+        const shown = list
+            .slice(0, 8)
+            .map((f) => f.path)
+            .join(', ');
+        throw new Error(`The site needs an index.html at its root. Files received: ${shown}${list.length > 8 ? ', …' : ''}`);
+    }
+    return list;
+}
+export function guessContentType(path) {
+    const ext = (/\.([a-zA-Z0-9]+)$/.exec(path)?.[1] ?? '').toLowerCase();
+    const map = {
+        html: 'text/html',
+        htm: 'text/html',
+        css: 'text/css',
+        js: 'text/javascript',
+        mjs: 'text/javascript',
+        json: 'application/json',
+        svg: 'image/svg+xml',
+        txt: 'text/plain',
+        md: 'text/markdown',
+        xml: 'application/xml',
+        webmanifest: 'application/manifest+json',
+        ico: 'image/x-icon',
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        avif: 'image/avif',
+        woff: 'font/woff',
+        woff2: 'font/woff2',
+        ttf: 'font/ttf',
+        otf: 'font/otf',
+        pdf: 'application/pdf',
+        mp4: 'video/mp4',
+        webm: 'video/webm',
+        mp3: 'audio/mpeg'
+    };
+    return map[ext] ?? 'application/octet-stream';
+}
+/** The drop endpoint's body: one `files` part per file, the path as the filename. */
+export function buildFormData(files) {
+    const fd = new FormData();
+    for (const f of files) {
+        fd.append('files', new Blob([f.bytes], { type: guessContentType(f.path) }), f.path);
+    }
+    return fd;
+}
+//# sourceMappingURL=site-files.js.map

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

@@ -0,0 +1,35 @@
+import { WixMcpServer } from '../wix-mcp-server.js';
+import { type McpAuthenticationStrategy } from '../auth/index.js';
+export declare const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = "UploadHeadlessWebsiteFiles";
+/**
+ * Attribution the drop endpoint stamps on its upload BI event (`source` from
+ * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
+ * anonymous route, and what the headless Drop dashboard keys its "MCP API"
+ * entry point on. `agent` is the MCP client's name as a lowercase slug.
+ */
+export declare function dropAttribution(clientName?: string): string;
+export interface UploadHeadlessWebsiteFilesOptions {
+    authStrategy: McpAuthenticationStrategy;
+    toolDescriptions?: Record<string, string>;
+    /** Test seam; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Client identity for drop attribution when the server cannot tell (the toolkit's configured name). */
+    clientName?: string;
+}
+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 and 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.";
+    readonly attachments: "ChatGPT only. Files attached in the chat or created in your sandbox — any type: a zip of the whole site, HTML, CSS, JS, images. Pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or, with a shell that reaches the internet, drop the files with curl as the StartDeployWebsite recipe shows. A zip is unpacked; a top-level folder wrapping the site is stripped. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.";
+    readonly siteId: "The metaSiteId of the Wix Headless site to upload into: the one returned by the provision call of the StartDeployWebsite recipe for a new site, or of a site deployed earlier to replace its files. Every upload replaces the whole file set, so send all files; the URL stays the same.";
+    readonly calledStartDeployWebsite: "Whether you called StartDeployWebsite earlier in this conversation and are following the recipe it returned. Answer truthfully; it is recorded, not checked.";
+    readonly agentIdentity: "Which agent or product you are and the harness you run in.";
+    readonly reason: "One sentence: the user request that led here and what is being published.";
+};
+export interface DropResult {
+    metaSiteId: string;
+    siteUrl?: string;
+    uploadId?: string;
+    files: string[];
+}
+export declare function formatDropResult(r: DropResult): string;
+export declare function addUploadHeadlessWebsiteFilesTool(server: WixMcpServer, options: UploadHeadlessWebsiteFilesOptions): void;
+//# sourceMappingURL=upload-headless-website-files.d.ts.map

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

@@ -0,0 +1,171 @@
+/**
+ * UploadHeadlessWebsiteFiles — the upload step of the drop flow, as one
+ * individually exposed operation: the files of an existing drop site are
+ * replaced (or first filled) with one multipart POST to
+ * `/headless-business/{msid}/drop`. Provisioning the site is NOT done here —
+ * the recipe's step 1 (StartDeployWebsite → provision) stays with the agent.
+ *
+ * Takes the same file inputs as ExecuteWixAPI — the `files` text bundle and
+ * ChatGPT `attachments` (openai/fileParams) — and does the work directly: parse,
+ * unzip, check the site shape, POST, return the live URL. No sandbox, no
+ * agent-written code, no runtime dependency.
+ */
+import { z } from 'zod';
+import { AttachmentError, resolveAttachments } from '../code-mode/attachments.js';
+import { base64ToBytes, buildFormData, normalizeSiteFiles, parseFileBundle } from './site-files.js';
+import { HEADLESS_GUIDE_URL } from '../docs/start-headless-build.js';
+import { logger } from '../infra/logger.js';
+import { defaultToolDescriptions } from '../config/default-config.js';
+import { rethrowIfUnauthorized } from '../auth/index.js';
+import { WixFetchError } from '../wix-fetch-error.js';
+import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS, START_DEPLOY_WEBSITE_RECIPE_URL as RECIPE_URL } from '../docs/start-deploy-website.js';
+export const UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME = 'UploadHeadlessWebsiteFiles';
+const HEADLESS_BUSINESS = 'https://www.wixapis.com/headless-business-setup/v1/headless-business';
+/**
+ * Attribution the drop endpoint stamps on its upload BI event (`source` from
+ * `campaign`, `agent` from `agent`, both ≤ 64 chars) — the same parser as the
+ * anonymous route, and what the headless Drop dashboard keys its "MCP API"
+ * entry point on. `agent` is the MCP client's name as a lowercase slug.
+ */
+export function dropAttribution(clientName) {
+    const slug = (clientName ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+    return `?campaign=mcp&agent=${encodeURIComponent(slug || 'wix-mcp')}`;
+}
+export const UPLOAD_HEADLESS_WEBSITE_FILES_PARAM_DESCRIPTIONS = {
+    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 and 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.',
+    attachments: 'ChatGPT only. Files attached in the chat or created in your sandbox — any type: a zip of the whole site, HTML, CSS, JS, images. Pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or, with a shell that reaches the internet, drop the files with curl as the StartDeployWebsite recipe shows. A zip is unpacked; a top-level folder wrapping the site is stripped. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.',
+    siteId: 'The metaSiteId of the Wix Headless site to upload into: the one returned by the provision call of the StartDeployWebsite recipe for a new site, or of a site deployed earlier to replace its files. Every upload replaces the whole file set, so send all files; the URL stays the same.',
+    calledStartDeployWebsite: 'Whether you called StartDeployWebsite earlier in this conversation and are following the recipe it returned. Answer truthfully; it is recorded, not checked.',
+    agentIdentity: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity,
+    reason: 'One sentence: the user request that led here and what is being published.'
+};
+export function formatDropResult(r) {
+    const shown = r.files.slice(0, 60);
+    return [
+        'Uploaded; the site is live with this file set.',
+        `Live URL: ${r.siteUrl ?? '(not returned)'}`,
+        `metaSiteId: ${r.metaSiteId} — pass it as \`siteId\` to update this site later; every upload replaces the whole file set.`,
+        `Dashboard: https://manage.wix.com/dashboard/${r.metaSiteId}`,
+        `${r.files.length} file(s): ${shown.join(', ')}${r.files.length > shown.length ? ', …' : ''}`,
+        '',
+        'Give the user the live URL and the dashboard link.',
+        `The upload step is done. For what comes next — changing the site later, connecting a domain, or adding a Wix backend (forms, bookings, a store) to this same site — continue with the guide you are following, from where it left off: the StartDeployWebsite recipe (${RECIPE_URL}) or, for a site built through StartHeadlessBuild, the headless guide (${HEADLESS_GUIDE_URL}).`
+    ].join('\n');
+}
+async function readJson(res, what) {
+    const text = await res.text();
+    if (!res.ok)
+        throw new WixFetchError(res.status, res.statusText, `${what}: ${text}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${what} returned a non-JSON body: ${text.slice(0, 200)}`);
+    }
+}
+function errorResult(message) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `UploadHeadlessWebsiteFiles error: ${message}`
+            }
+        ]
+    };
+}
+export function addUploadHeadlessWebsiteFilesTool(server, options) {
+    const { authStrategy, toolDescriptions } = options;
+    const clientName = () => options.clientName ??
+        server.clientName?.() ??
+        server.server?.getClientVersion?.()?.name;
+    const fetchImpl = options.fetchImpl ?? ((u, i) => fetch(u, i));
+    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, {
+        files: z.string().optional().describe(d.files),
+        attachments: z
+            .array(z.object({
+            download_url: z.string(),
+            file_id: z.string(),
+            file_name: z.string().optional(),
+            mime_type: z.string().optional()
+        }))
+            .optional()
+            .describe(d.attachments),
+        siteId: z
+            .string()
+            .uuid('siteId must be a Wix metaSiteId (UUID)')
+            .describe(d.siteId),
+        calledStartDeployWebsite: z
+            .boolean()
+            .describe(d.calledStartDeployWebsite),
+        agentIdentity: z.string().min(1).describe(d.agentIdentity),
+        reason: z.string().describe(d.reason)
+    }, 
+    // openWorldHint true: it fetches agent-supplied attachment URLs and publishes a
+    // public website.
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async (rawArgs, extra) => {
+        const { files, attachments, siteId, calledStartDeployWebsite, agentIdentity, reason } = rawArgs;
+        logger.log(`[UploadHeadlessWebsiteFiles] siteId=${siteId} calledStartDeployWebsite=${calledStartDeployWebsite} agent="${agentIdentity}" files=${files?.length ?? 0} chars attachments=${attachments?.length ?? 0} reason="${reason}"`);
+        if (!files?.trim() && !(attachments && attachments.length)) {
+            return errorResult('Nothing to publish: pass the site in `files` (text bundle) or `attachments` (files from this chat or your sandbox).');
+        }
+        // 1. Gather bytes: bundle + resolved attachments. All agent-facing errors.
+        let siteFiles;
+        try {
+            const fromAttachments = (await resolveAttachments(attachments, fetchImpl)).map((a) => ({ path: a.path, bytes: base64ToBytes(a.content) }));
+            siteFiles = await normalizeSiteFiles([
+                ...parseFileBundle(files),
+                ...fromAttachments
+            ]);
+        }
+        catch (e) {
+            if (e instanceof AttachmentError || e instanceof Error)
+                return errorResult(e.message);
+            throw e;
+        }
+        // 2. Account auth (outside the try so UnauthorizedError reaches the wrapper).
+        const authHeaders = await authStrategy.getAccountAuthHeaders();
+        try {
+            const metaSiteId = siteId;
+            extra?.setToolBiParams?.({ siteId: metaSiteId });
+            // 3. One multipart POST — the site goes live with this file set.
+            const dropped = await readJson(await fetchImpl(`${HEADLESS_BUSINESS}/${metaSiteId}/drop${dropAttribution(clientName())}`, {
+                method: 'POST',
+                headers: { ...authHeaders }, // fetch sets the multipart boundary itself
+                body: buildFormData(siteFiles)
+            }), 'drop');
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: formatDropResult({
+                            metaSiteId,
+                            siteUrl: dropped.siteUrl,
+                            uploadId: dropped.uploadId,
+                            files: siteFiles.map((f) => f.path)
+                        })
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.log(`[UploadHeadlessWebsiteFiles] Error: ${message}`);
+            rethrowIfUnauthorized(err);
+            await authStrategy.enforceValidWixToken?.(err);
+            return errorResult(message);
+        }
+    });
+    // ChatGPT resolves `attachments` into download URLs only for params listed
+    // here (OpenAI's `openai/fileParams` extension). Other clients ignore it.
+    registered?.update?.({
+        _meta: { ...registered._meta, 'openai/fileParams': ['attachments'] }
+    });
+}
+//# sourceMappingURL=upload-headless-website-files.js.map

package/build/dts/bin.js

@@ -21,7 +21,7 @@ const EXPERIMENTAL_TOOLS = [
     'WIX_API',
     'CLI_COMMAND',
     'GET_TO_KNOW_WIX',
-    'CREATE_WIX_BUSINESS_GUIDE',
+    'CREATE_WIX_BUSINESS_GUIDE', // accepted so old configs still start; the tool was removed
     'VELO_README',
     'WIX_API_THROUGH_FS',
     'GRAPHQL'
@@ -90,15 +90,12 @@ logger.log('Active tools:', activeTools);
 const docsTools = activeTools.filter((tool) => VALID_DOCS_TOOLS.includes(tool));
 const isWixCliAuth = Boolean(parsedArgs['wixCliAuth']);
 const hasGetToKnowWix = activeTools.includes('GET_TO_KNOW_WIX') || isWixCliAuth;
-const hasCreateWixBusinessGuide = activeTools.includes('CREATE_WIX_BUSINESS_GUIDE');
 const hasDynamicContext = Boolean(parsedArgs['dynamicContext']) || isWixCliAuth;
-if (docsTools.length > 0 || hasGetToKnowWix || hasCreateWixBusinessGuide) {
+if (docsTools.length > 0 || hasGetToKnowWix) {
     logger.log('Adding docs tools:', docsTools);
     addDocsTools(server, docsTools, {
         getToKnowWixEnabled: hasGetToKnowWix,
-        createWixBusinessGuideEnabled: hasCreateWixBusinessGuide,
-        dynamicContextEnabled: hasDynamicContext,
-        cliEnabled: true // bin.ts is always a CLI client (e.g. Claude Code)
+        dynamicContextEnabled: hasDynamicContext
     });
 }
 if (activeTools.includes('VELO_README')) {

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

@@ -183,7 +183,7 @@ export async function resolveAttachments(attachments, fetchImpl = fetch) {
             url = undefined;
         }
         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))}). The platform did not hydrate this attachment; retry once, and if it still arrives like this put the file in the \`files\` bundle instead (\`=== FILE: <path> base64 ===\` for binary).`);
+            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);
         if (problem) {

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

@@ -8,6 +8,7 @@ import { validateExecuteCode } from './validation.js';
 import { desc } from '../config/param-descriptions.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { WixFetchError } from '../wix-fetch-error.js';
+import { addUploadHeadlessWebsiteFilesTool, UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME } from '../api-call/upload-headless-website-files.js';
 // Looks `fetch` up per call so a host or test that swaps the global is honored.
 const defaultCodeModeFetch = (url, init) => fetch(url, init);
 const SEARCH_TOOL_NAME = 'SearchWixAPISpec';
@@ -25,6 +26,15 @@ export async function addCodeModeTools(server, options) {
             maxResponseSize
         });
     }
+    // Account-owner flow, registered beside the code-mode tools (same file
+    // inputs, no runtime dependency); never in visitor mode.
+    if (!disableTools.includes(UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME) &&
+        authStrategy) {
+        addUploadHeadlessWebsiteFilesTool(server, {
+            authStrategy,
+            toolDescriptions
+        });
+    }
 }
 /**
  * Register SearchWixAPISpec. The description must stay a byte-stable
@@ -234,8 +244,8 @@ function addExecuteTool(server, options) {
         hasMutations: z
             .boolean()
             .describe(visitor
-            ? 'Whether this code creates, updates, deletes, publishes, imports, uploads, or otherwise mutates site data on the visitor’s behalf. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false.'
-            : 'Whether this code creates, updates, deletes, publishes, installs, imports, uploads, or otherwise mutates Wix data or site/account state. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false.'),
+            ? 'True if the code changes site data on the visitor’s behalf (create, update, delete, import, upload); false if it only reads (get, query, list, search).'
+            : 'True if the code changes anything in the Wix account or a site (create, update, delete, publish, install, import, upload); false if it only reads (get, query, list, search).'),
         sourceDocUrls: z.array(z.string()).describe(d.sourceDocUrls),
         files: z
             .string()
@@ -259,7 +269,7 @@ function addExecuteTool(server, options) {
             mime_type: z.string().optional()
         }))
             .optional()
-            .describe('Files attached in this chat, or files you created in your own file sandbox (any type: a zip of a site, HTML, images, PDFs). Pass the files themselves and the platform resolves each into { download_url, file_id, file_name?, mime_type? }; the bytes are fetched here and appended to the `files` global as { path, content, encoding: "base64" } entries (path = file_name), so `wix.multipart()` and `wix.unzip()` work on them unchanged. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.'),
+            .describe('ChatGPT only. Files attached in the chat or created in your sandbox (any type: a zip of a site, HTML, images, PDFs): pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or upload from your shell if it reaches the internet. The bytes are fetched here and appended to the `files` global as { path, content, encoding: "base64" } entries (path = file_name), so `wix.multipart()` and `wix.unzip()` work on them unchanged. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.'),
         // Visitor mode takes an agent-supplied token and pins the site; account/site
         // mode lets the agent pick the site.
         ...(visitor
@@ -274,7 +284,11 @@ function addExecuteTool(server, options) {
                     .optional()
                     .describe('Default Wix site ID for the `wix.request()` calls in this execution. Optional in the schema, but required for site-level work: supply a `siteId` either here, as the default for every request, or on an individual request. Without one, a request runs at account scope, where site-level endpoints fail. Setting `scope: "account"` on a request runs it at account scope and ignores any `siteId`. Determine the target site with GetSiteContext or ListWixSites before calling; do not pass a guessed or empty value.')
             })
-    }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async (rawArgs, 
+    }, 
+    // openWorldHint true: agent code picks the Wix endpoints at run time (and may
+    // receive platform-resolved attachment URLs); the sandbox's host allowlist
+    // bounds it, but the operation set is open-ended, which is what the hint means.
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async (rawArgs, 
     // Partial: duck-typed servers (the toolkit's capturing server, test
     // doubles) build their own extra and may not supply every field.
     extra) => {

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

@@ -33,10 +33,6 @@ export declare const SITE_CREATION_COPY: {
         readonly nonWidget: "you MUST ask whether they want to build with AI or start from a template, and create nothing and show nothing until they answer";
         readonly widget: "you MUST call `WixSiteCreation` and let them choose";
     };
-    readonly normalCreationRoute: {
-        readonly nonWidget: "route those through `WixSiteBuilder` or `SearchSiteTemplates`";
-        readonly widget: "route those through `WixSiteCreation`";
-    };
 };
 /** Rewrites non-widget copy into its widget form; a no-op on text that carries no divergence. */
 export declare const toWidget: (text: string) => string;