@wix/mcp 1.0.97 → 1.0.98

package/build/dts/wixel/api.d.ts

@@ -62,4 +62,27 @@ export interface WixelStylePresetSummary {
     raw?: Record<string, unknown>;
 }
 export declare function getStylePresetsByIds({ siteAuthHeaders, stylePresetIds, apiBaseURL, conductorOverride }: GetStylePresetsOptions): Promise<WixelStylePresetSummary[]>;
+export interface AssetExportOptions {
+    siteAuthHeaders: Record<string, string>;
+    projectId: string;
+    assetType: string;
+    apiBaseURL?: string;
+    conductorOverride?: string;
+}
+export interface AssetExportState {
+    complete: boolean;
+    progress: number | null;
+    url: string | null;
+    errorDescription: string | null;
+    title: string | null;
+}
+export declare const WIXEL_HOST_EXPORT_ASSET_PATH = "/_api/wixel/v1/export/asset";
+export declare const WIXEL_HOST_EXPORT_STATE_PATH = "/_api/wixel/v1/export/state";
+export declare function startAssetExport({ assetId, params, ...options }: AssetExportOptions & {
+    assetId: string;
+    params?: Record<string, unknown>;
+}): Promise<string>;
+export declare function getAssetExportState({ jobId, ...options }: AssetExportOptions & {
+    jobId: string;
+}): Promise<AssetExportState>;
 //# sourceMappingURL=api.d.ts.map

package/build/dts/wixel/api.js

@@ -100,4 +100,51 @@ export async function getStylePresetsByIds({ siteAuthHeaders, stylePresetIds, ap
         };
     });
 }
+function wixelHostClient({ siteAuthHeaders, apiBaseURL = WWW_ASSET_V1_ASSET_API_BASE_URL, conductorOverride }) {
+    return createHttpClient({
+        headers: {
+            ...COMMON_HEADERS,
+            ...siteAuthHeaders,
+            ...(conductorOverride ? { ...CONDUCTOR_OVERRIDE_HEADERS } : {})
+        },
+        baseURL: apiBaseURL
+    });
+}
+// WixelHost.ExportAsset — the same export the editor's Download button starts.
+// The host hands it to the asset type's own export SPI (icons, logo, slides…),
+// which reads `params` (e.g. icons: fileType, size, layout).
+// WixelHost REST paths on manage.wix.com — the same endpoints the editor's
+// Download button reaches through @wix/ambassador-wixel-v1-asset-dynamic-payload.
+// Called directly so the published package keeps zod as its only dependency
+// and no new client library is added.
+export const WIXEL_HOST_EXPORT_ASSET_PATH = '/_api/wixel/v1/export/asset';
+export const WIXEL_HOST_EXPORT_STATE_PATH = '/_api/wixel/v1/export/state';
+export async function startAssetExport({ assetId, params, ...options }) {
+    const { data } = await wixelHostClient(options).post(WIXEL_HOST_EXPORT_ASSET_PATH, {
+        projectId: options.projectId,
+        assetId,
+        assetType: options.assetType,
+        ...(params ? { params } : {})
+    });
+    if (!data?.jobId) {
+        throw new Error('Wixel did not start an export job for this asset');
+    }
+    return data.jobId;
+}
+// WixelHost.GetJobState — progress, and the file URL once complete.
+export async function getAssetExportState({ jobId, ...options }) {
+    const { data } = await wixelHostClient(options).post(WIXEL_HOST_EXPORT_STATE_PATH, {
+        jobId,
+        projectId: options.projectId,
+        assetType: options.assetType
+    });
+    const state = data?.state ?? {};
+    return {
+        complete: state.complete === true,
+        progress: state.progress ?? null,
+        url: state.url ?? null,
+        errorDescription: state.errorDescription ?? null,
+        title: state.title ?? null
+    };
+}
 //# sourceMappingURL=api.js.map

package/build/dts/wixel/app-icon-files.d.ts

@@ -0,0 +1,19 @@
+export interface AppIconFile {
+    /** Where the file goes in the app project. */
+    path: string;
+    /** Download URL (PNG files). */
+    url?: string;
+    /** Inline content (JSON files). */
+    content?: string;
+}
+/** The Wix Media file a URL points at, without any transform; null when it is not one. */
+export declare function wixMediaFileUrl(url: string): string | null;
+/** A square PNG of the file at `size` px, rendered by Wix Media. */
+export declare function wixMediaSquarePng(fileUrl: string, size: number): string;
+/**
+ * Every app-icon file for one exported PNG. Returns null when the PNG is not on
+ * Wix Media (the sizes cannot be made by URL), so the caller hands back the
+ * single file instead.
+ */
+export declare function buildAppIconFiles(exportedPngUrl: string, appName: string): AppIconFile[] | null;
+//# sourceMappingURL=app-icon-files.d.ts.map

package/build/dts/wixel/app-icon-files.js

@@ -0,0 +1,77 @@
+// App-icon size pack for an app icon staged as an IMAGE asset (the app-icon
+// skill stages each tile as a full-bleed 1024 × 1024 IMAGE). The export gives
+// one PNG on Wix Media; every other size is a Wix Media resize of that file
+// (`/v1/fill/w_N,h_N/…`), so the pack is a list of URLs plus the two small
+// JSON files the platforms read — no image processing in the MCP server.
+//
+// ICONS sets get the same pack as a zip from the icons export itself
+// (layout "appIcons"); this is the IMAGE counterpart.
+const WIX_MEDIA_FILE = /^(https:\/\/static\.wixstatic\.com\/media\/[^/?#]+)/;
+const ANDROID_MIPMAPS = [
+    ['mdpi', 48],
+    ['hdpi', 72],
+    ['xhdpi', 96],
+    ['xxhdpi', 144],
+    ['xxxhdpi', 192]
+];
+/** The Wix Media file a URL points at, without any transform; null when it is not one. */
+export function wixMediaFileUrl(url) {
+    return WIX_MEDIA_FILE.exec(url)?.[1] ?? null;
+}
+/** A square PNG of the file at `size` px, rendered by Wix Media. */
+export function wixMediaSquarePng(fileUrl, size) {
+    return `${fileUrl}/v1/fill/w_${size},h_${size},al_c,q_95/icon-${size}.png`;
+}
+/**
+ * Every app-icon file for one exported PNG. Returns null when the PNG is not on
+ * Wix Media (the sizes cannot be made by URL), so the caller hands back the
+ * single file instead.
+ */
+export function buildAppIconFiles(exportedPngUrl, appName) {
+    const file = wixMediaFileUrl(exportedPngUrl);
+    if (!file) {
+        return null;
+    }
+    const png = (path, size) => ({
+        path,
+        url: wixMediaSquarePng(file, size)
+    });
+    return [
+        png('ios/AppIcon.appiconset/icon-1024.png', 1024),
+        {
+            path: 'ios/AppIcon.appiconset/Contents.json',
+            content: JSON.stringify({
+                images: [
+                    {
+                        filename: 'icon-1024.png',
+                        idiom: 'universal',
+                        platform: 'ios',
+                        size: '1024x1024'
+                    }
+                ],
+                info: { author: 'wixel', version: 1 }
+            }, null, 2)
+        },
+        ...ANDROID_MIPMAPS.map(([density, size]) => png(`android/res/mipmap-${density}/ic_launcher.png`, size)),
+        png('android/play-store-512.png', 512),
+        png('web/favicon-16.png', 16),
+        png('web/favicon-32.png', 32),
+        png('web/favicon-48.png', 48),
+        png('web/apple-touch-icon.png', 180),
+        png('web/icon-192.png', 192),
+        png('web/icon-512.png', 512),
+        {
+            path: 'web/site.webmanifest',
+            content: JSON.stringify({
+                name: appName,
+                short_name: appName.slice(0, 12),
+                icons: [
+                    { src: 'icon-192.png', sizes: '192x192', type: 'image/png' },
+                    { src: 'icon-512.png', sizes: '512x512', type: 'image/png' }
+                ],
+                display: 'standalone'
+            }, null, 2)
+        }
+    ];
+}
+//# sourceMappingURL=app-icon-files.js.map

package/build/dts/wixel/index.d.ts

@@ -6,6 +6,7 @@ export { addGetWixelJobStatusTool } from './get-wixel-job-status-tool.js';
 export { addMarkWixelJobAsFulfilledTool } from './mark-wixel-job-as-fulfilled-tool.js';
 export { addGetWixelAssetTool } from './get-wixel-asset-tool.js';
 export { addGetWixelProjectAssetsTool } from './get-wixel-project-assets-tool.js';
+export { addGetWixelAssetFilesTool } from './wixel-asset-files-tool.js';
 export declare function addWixelTools(server: WixMcpServer, authStrategy: McpAuthenticationStrategy, options?: {
     conductorOverride?: string;
     supportsWidgets?: () => boolean;

package/build/dts/wixel/index.js

@@ -3,12 +3,14 @@ import { addMarkWixelJobAsFulfilledTool } from './mark-wixel-job-as-fulfilled-to
 import { addGetWixelAssetTool } from './get-wixel-asset-tool.js';
 import { addGetWixelProjectAssetsTool } from './get-wixel-project-assets-tool.js';
 import { addWixelSessionTools } from './wixel-session-tools.js';
+import { addGetWixelAssetFilesTool } from './wixel-asset-files-tool.js';
 export { WIXEL_ICON_SVG_URL, WIXEL_ICON_PNG_URL } from './constants.js';
 export { addWixelSessionTools, addSendWixelMessageTool, addGetWixelTaskTool } from './wixel-session-tools.js';
 export { addGetWixelJobStatusTool } from './get-wixel-job-status-tool.js';
 export { addMarkWixelJobAsFulfilledTool } from './mark-wixel-job-as-fulfilled-tool.js';
 export { addGetWixelAssetTool } from './get-wixel-asset-tool.js';
 export { addGetWixelProjectAssetsTool } from './get-wixel-project-assets-tool.js';
+export { addGetWixelAssetFilesTool } from './wixel-asset-files-tool.js';
 export function addWixelTools(server, authStrategy, options = {}) {
     addGetWixelJobStatusTool(server, authStrategy, options);
     addMarkWixelJobAsFulfilledTool(server, authStrategy, options);
@@ -16,5 +18,7 @@ export function addWixelTools(server, authStrategy, options = {}) {
     addGetWixelProjectAssetsTool(server, authStrategy, options);
     // Conversation tools over the Wixel agent's A2A endpoint
     addWixelSessionTools(server, authStrategy, options);
+    // Engine-ready files of an asset (sprite sheet, app-icon pack, PNGs)
+    addGetWixelAssetFilesTool(server, authStrategy, options);
 }
 //# sourceMappingURL=index.js.map

package/build/dts/wixel/wixel-asset-files-tool.d.ts

@@ -0,0 +1,29 @@
+import { McpAuthenticationStrategy } from '../auth/index.js';
+import { WixMcpServer } from '../wix-mcp-server.js';
+export declare const ASSET_FILE_LAYOUTS: readonly ["files", "spriteSheet", "appIcons"];
+export type AssetFileLayout = (typeof ASSET_FILE_LAYOUTS)[number];
+declare const ICONS_FILE_TYPES: readonly ["png", "pngTransparentBackground", "svg", "svgTransparentBackground"];
+declare const ICONS_SIZES: readonly ["16px", "24px", "32px", "64px", "128px", "256px", "512px"];
+export interface AssetFilesArgs {
+    metaSiteId: string;
+    sessionId: string;
+    assetId?: string;
+    layout?: AssetFileLayout;
+    fileType?: (typeof ICONS_FILE_TYPES)[number];
+    size?: (typeof ICONS_SIZES)[number];
+    jobId?: string;
+    assetType?: string;
+    waitSeconds?: number;
+}
+/**
+ * The export params for an asset type. Only ICONS reads layout / fileType /
+ * size; other types export with their own defaults. A layout that needs an
+ * icon set is refused for any other type instead of silently exporting
+ * something else.
+ */
+export declare function buildExportParams(assetType: string, args: Pick<AssetFilesArgs, 'layout' | 'fileType' | 'size'>): Record<string, unknown> | undefined;
+export declare function addGetWixelAssetFilesTool(server: WixMcpServer, authStrategy: McpAuthenticationStrategy, options?: {
+    conductorOverride?: string;
+}): void;
+export {};
+//# sourceMappingURL=wixel-asset-files-tool.d.ts.map

package/build/dts/wixel/wixel-asset-files-tool.js

@@ -0,0 +1,327 @@
+import { rethrowIfUnauthorized } from '../auth/index.js';
+import { setWixelToolBi as setBi } from './wixel-bi.js';
+import { z } from 'zod';
+import { getAsset, getAssetExportState, queryAssets, startAssetExport } from './api.js';
+import { buildAppIconFiles } from './app-icon-files.js';
+import { getWixelSessionProjectId } from './wixel-session-entries.js';
+// get_wixel_asset_files: the files of a Wixel asset, for a coding agent that
+// builds something with them (a game, an app, a site). It runs the same export
+// the editor's Download button runs and returns the file URL.
+//
+// It takes the conversation's metaSiteId + sessionId (both returned by
+// send_wixel_message), so it does not depend on get_wixel_task having reported
+// asset ids: without assetId it lists the project's assets to pick from.
+//
+// ICONS sets have two engine-ready layouts on top of the plain per-tile files:
+// - spriteSheet: one aligned sheet PNG + Aseprite JSON frame map (Phaser
+//   createFromAseprite) + the aligned frames — for character pose sets;
+// - appIcons: iOS app icon set, Android mipmaps + Play Store icon, web
+//   favicons + manifest — for an app or game icon.
+export const ASSET_FILE_LAYOUTS = ['files', 'spriteSheet', 'appIcons'];
+const ICONS_FILE_TYPES = [
+    'png',
+    'pngTransparentBackground',
+    'svg',
+    'svgTransparentBackground'
+];
+const ICONS_SIZES = [
+    '16px',
+    '24px',
+    '32px',
+    '64px',
+    '128px',
+    '256px',
+    '512px'
+];
+const POLL_INTERVAL_MS = 2_000;
+const MAX_WAIT_SECONDS = 25;
+/**
+ * The export params for an asset type. Only ICONS reads layout / fileType /
+ * size; other types export with their own defaults. A layout that needs an
+ * icon set is refused for any other type instead of silently exporting
+ * something else.
+ */
+export function buildExportParams(assetType, args) {
+    const layout = args.layout ?? 'files';
+    if (assetType === 'IMAGE' && layout === 'appIcons') {
+        // An app icon from the app-icon skill is a full-bleed 1024 × 1024 IMAGE:
+        // export it as one full-size PNG; the sizes are made from it by URL.
+        return { format: 'png', quality: 100, scale: 1 };
+    }
+    if (assetType !== 'ICONS') {
+        if (layout !== 'files') {
+            throw new Error(layout === 'appIcons'
+                ? `layout "appIcons" needs an ICONS or IMAGE asset (the app icon); this asset is ${assetType}`
+                : `layout "${layout}" needs an ICONS asset (an icon / sprite set); this asset is ${assetType}`);
+        }
+        return undefined;
+    }
+    if (layout === 'files') {
+        return {
+            // Engines and app projects want plain transparent PNGs, not the
+            // editor's default SVG-wrapped PNG.
+            fileType: args.fileType ?? 'pngTransparentBackground',
+            ...(args.size ? { size: args.size } : { size: '512px' })
+        };
+    }
+    return {
+        layout,
+        ...(layout === 'spriteSheet' && args.size ? { size: args.size } : {})
+    };
+}
+async function waitForExport(read, waitSeconds) {
+    const deadline = Date.now() + waitSeconds * 1000;
+    let state = await read();
+    while (!state.complete && !state.errorDescription && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        state = await read();
+    }
+    return state;
+}
+function describeContents(layout, assetType) {
+    if (assetType !== 'ICONS') {
+        return 'The file is the asset as the editor downloads it.';
+    }
+    switch (layout) {
+        case 'spriteSheet':
+            return 'The zip holds <set>-sheet.png (frames on one grid, feet on one baseline), <set>-sheet.json (Aseprite array frame map: frames "0","1"…, one frameTags entry per pose — load with Phaser this.load.aseprite + this.anims.createFromAseprite) and frames/<n>-<pose>.png.';
+        case 'appIcons':
+            return 'The zip holds ios/AppIcon.appiconset (1024 px + Contents.json, drop into Assets.xcassets), android/res/mipmap-*/ic_launcher.png + android/play-store-512.png, and web/ favicons, apple-touch-icon.png, icon-192/512.png and site.webmanifest.';
+        default:
+            return 'The zip holds one transparent PNG per tile, named after the tile.';
+    }
+}
+export function addGetWixelAssetFilesTool(server, authStrategy, options = {}) {
+    const { getSiteAuthHeaders } = authStrategy;
+    server.registerTool('get_wixel_asset_files', {
+        title: 'Get Wixel asset files',
+        description: `Download the files of an asset made in a Wixel conversation, to use them in code (a game, an app, a site). Pass the metaSiteId and sessionId that send_wixel_message returned.
+- Without assetId: lists the project's assets (id, name, type) — pick one.
+- With assetId: exports it and returns a zip URL. For an ICONS asset choose layout:
+  "files" (default) one transparent PNG per tile;
+  "spriteSheet" for a character's poses / animation frames: one aligned sheet + Aseprite JSON frame map (Phaser createFromAseprite) + aligned frames;
+  "appIcons" for an app or game icon: iOS app icon set, Android mipmaps + Play Store 512, web favicons + manifest.
+  An IMAGE asset (an app icon tile) also takes layout "appIcons": you get one URL per file instead of a zip.
+- If the export is still running, call again with the returned jobId, assetType, layout and assetId.
+Download the URL and unzip it into the project; never re-draw or re-generate assets the user already approved.`,
+        inputSchema: {
+            metaSiteId: z
+                .string()
+                .describe('metaSiteId returned by send_wixel_message'),
+            sessionId: z
+                .string()
+                .describe('sessionId returned by send_wixel_message'),
+            assetId: z
+                .string()
+                .optional()
+                .describe('Asset to export; omit to list the project assets'),
+            layout: z
+                .enum(ASSET_FILE_LAYOUTS)
+                .optional()
+                .describe('ICONS assets only: files (default), spriteSheet, appIcons'),
+            fileType: z
+                .enum(ICONS_FILE_TYPES)
+                .optional()
+                .describe('ICONS layout "files" only; default pngTransparentBackground'),
+            size: z
+                .enum(ICONS_SIZES)
+                .optional()
+                .describe('ICONS: tile size for "files" (default 512px), frame cell size for "spriteSheet" (default 256px)'),
+            jobId: z
+                .string()
+                .optional()
+                .describe('Continue waiting on an export this tool started'),
+            assetType: z
+                .string()
+                .optional()
+                .describe('With jobId: the assetType this tool returned'),
+            waitSeconds: z
+                .number()
+                .min(0)
+                .max(MAX_WAIT_SECONDS)
+                .optional()
+                .describe('How long to wait for the export (default 25)')
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        }
+    }, async (args, extra) => {
+        setBi(extra, { siteId: args.metaSiteId });
+        const siteAuthHeaders = await getSiteAuthHeaders(args.metaSiteId);
+        try {
+            const projectId = await getWixelSessionProjectId({
+                authHeaders: siteAuthHeaders,
+                conductorOverride: options.conductorOverride,
+                sessionId: args.sessionId
+            });
+            if (!projectId) {
+                throw new Error('This Wixel conversation has no project yet — make something first');
+            }
+            const base = {
+                siteAuthHeaders,
+                projectId,
+                conductorOverride: options.conductorOverride
+            };
+            const waitSeconds = args.waitSeconds ?? MAX_WAIT_SECONDS;
+            if (args.jobId) {
+                if (!args.assetType) {
+                    throw new Error('Pass the assetType returned with the jobId');
+                }
+                const assetType = args.assetType;
+                const state = await waitForExport(() => getAssetExportState({ ...base, assetType, jobId: args.jobId }), waitSeconds);
+                // The app-icon manifest is named after the asset, so a follow-up
+                // poll that carries the assetId looks the name up again.
+                // Only an IMAGE app-icon pack uses the name, and a failed lookup
+                // must not hide an export that is already done.
+                const assetName = state.complete &&
+                    args.assetId &&
+                    assetType === 'IMAGE' &&
+                    args.layout === 'appIcons'
+                    ? await getAsset({ ...base, assetId: args.assetId })
+                        .then((asset) => asset?.name)
+                        .catch(() => undefined)
+                    : undefined;
+                return exportResult(state, args, assetType, args.jobId, assetName);
+            }
+            if (!args.assetId) {
+                const { assets } = await queryAssets(base);
+                const list = (assets ?? [])
+                    .filter((asset) => !asset.archived)
+                    .map((asset) => ({
+                    id: asset.id,
+                    name: asset.name ?? null,
+                    type: asset.type ?? null
+                }));
+                return {
+                    isError: false,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${list.length} assets in this Wixel project:\n${list
+                                .map((a) => `- ${a.name ?? '(unnamed)'} [${a.type}] id=${a.id}`)
+                                .join('\n')}\nCall get_wixel_asset_files again with the assetId to download one.`
+                        }
+                    ],
+                    structuredContent: { success: true, projectId, assets: list }
+                };
+            }
+            const asset = await getAsset({ ...base, assetId: args.assetId });
+            const assetType = asset?.type;
+            if (!assetType) {
+                throw new Error(`Asset ${args.assetId} was not found in this project`);
+            }
+            const params = buildExportParams(assetType, args);
+            const jobId = await startAssetExport({
+                ...base,
+                assetType,
+                assetId: args.assetId,
+                params
+            });
+            const state = await waitForExport(() => getAssetExportState({ ...base, assetType, jobId }), waitSeconds);
+            return exportResult(state, args, assetType, jobId, asset?.name);
+        }
+        catch (error) {
+            rethrowIfUnauthorized(error);
+            // Log the message and request id only: an HttpError carries the request
+            // config, whose headers hold the user's site token.
+            console.error('❌ Error getting Wixel asset files:', {
+                message: error.message,
+                requestId: error.requestId
+            });
+            const errorMessage = error.message;
+            return {
+                isError: true,
+                content: [{ type: 'text', text: errorMessage }],
+                structuredContent: { success: false, error: errorMessage }
+            };
+        }
+    });
+}
+function exportResult(state, args, assetType, jobId, assetName) {
+    if (state.errorDescription) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Export failed: ${state.errorDescription}`
+                }
+            ],
+            structuredContent: {
+                success: false,
+                error: state.errorDescription,
+                jobId,
+                assetType
+            }
+        };
+    }
+    // A follow-up poll carries only what this reply tells the caller to pass
+    // back, so the layout travels with the jobId: without it the ready reply
+    // would describe plain files for a sprite sheet or an app-icon pack.
+    const layout = args.layout ?? 'files';
+    if (!state.complete || !state.url) {
+        return {
+            isError: false,
+            content: [
+                {
+                    type: 'text',
+                    text: `Export still running${state.progress != null ? ` (${state.progress}%)` : ''}. Call get_wixel_asset_files again with jobId "${jobId}", assetType "${assetType}", layout "${layout}"${args.assetId ? ` and assetId "${args.assetId}"` : ''}.`
+                }
+            ],
+            structuredContent: {
+                success: true,
+                status: 'running',
+                progress: state.progress,
+                jobId,
+                assetType,
+                layout,
+                ...(args.assetId ? { assetId: args.assetId } : {})
+            }
+        };
+    }
+    if (assetType === 'IMAGE' && layout === 'appIcons') {
+        const files = buildAppIconFiles(state.url, assetName || 'App');
+        if (files) {
+            return {
+                isError: false,
+                content: [
+                    {
+                        type: 'text',
+                        text: `App icon files ready — download each URL to its path, write the JSON files as given:\n${files
+                            .map((f) => `- ${f.path}: ${f.url ?? f.content}`)
+                            .join('\n')}`
+                    }
+                ],
+                structuredContent: {
+                    success: true,
+                    status: 'ready',
+                    url: state.url,
+                    files,
+                    jobId,
+                    assetType,
+                    layout
+                }
+            };
+        }
+    }
+    return {
+        isError: false,
+        content: [
+            {
+                type: 'text',
+                text: `Files ready: ${state.url}\n${describeContents(args.layout, assetType)}`
+            }
+        ],
+        structuredContent: {
+            success: true,
+            status: 'ready',
+            url: state.url,
+            jobId,
+            assetType,
+            layout: args.layout ?? 'files'
+        }
+    };
+}
+//# sourceMappingURL=wixel-asset-files-tool.js.map

package/build/dts/wixel/wixel-session-entries.d.ts

@@ -50,6 +50,28 @@ export interface WixelPendingQuestion {
     toolCallId: string;
     turnId?: string;
     questions: WixelAskUserQuestion[];
+    /** Pictures the asking turn made before it asked — the sample a "make the
+     *  rest in this look?" question is about. Empty when the turn made none. */
+    previewUrls?: string[];
+}
+/**
+ * The pictures the turn made before its question, newest last: the image
+ * tools' results in that turn up to the ask_user. A client that cannot render
+ * the stage (Claude Code, Cursor) otherwise approves a look it never sees.
+ */
+export declare function collectPreviewUrls(messages: SessionEntryMessage[], askIndex: number, turnId: string | undefined): string[];
+interface SessionEntryPart {
+    text?: string;
+    functionCall?: {
+        id?: string;
+        name?: string;
+        args?: Record<string, unknown>;
+    };
+    functionResponse?: {
+        id?: string;
+        name?: string;
+        response?: unknown;
+    };
 }
 export interface WixelSessionActivity {
     /** Unanswered ask_user the turn is suspended on (nothing will generate
@@ -66,6 +88,12 @@ export interface WixelSessionActivity {
  * alone cannot distinguish the two.
  */
 export declare function getWixelSessionActivity({ sessionId, ...base }: GetSessionEntriesOptions): Promise<WixelSessionActivity>;
+interface SessionEntryMessage {
+    id?: string;
+    role?: string;
+    turnId?: string;
+    parts?: SessionEntryPart[];
+}
 export declare function getWixelPendingQuestion({ sessionId, requireParked, turnId, ...base }: GetSessionEntriesOptions & {
     requireParked?: boolean;
     /** The asking task's turn. A question another turn of the session asked —

package/build/dts/wixel/wixel-session-entries.js

@@ -1,5 +1,6 @@
 import { createHttpClient } from '@wix/http-client';
 import { WIXEL_AGENT_SESSIONS_API_BASE_URL } from './constants.js';
+import { extractMediaUrls } from './wixel-a2a-client.js';
 // Reads of the Wixel agent's internal sessions API (wixel-agent-service):
 // the durable entries log of a session and the sessions listing. A2A tasks
 // report a turn's state and reply, but a parked ask_user question — the
@@ -41,6 +42,36 @@ export async function getWixelSessionProjectId({ sessionId, ...base }) {
     const session = data?.sessions?.find((entry) => entry.id === sessionId);
     return session?.projectId ?? null;
 }
+/** Image tools whose results are the pictures a question can be about. */
+const PREVIEW_TOOLS = new Set([
+    'generate_image',
+    'edit_image',
+    'remove_image_background'
+]);
+const MAX_PREVIEW_URLS = 4;
+/**
+ * The pictures the turn made before its question, newest last: the image
+ * tools' results in that turn up to the ask_user. A client that cannot render
+ * the stage (Claude Code, Cursor) otherwise approves a look it never sees.
+ */
+export function collectPreviewUrls(messages, askIndex, turnId) {
+    const urls = [];
+    for (let i = 0; i <= askIndex; i++) {
+        const message = messages[i];
+        if (turnId && message.turnId !== turnId)
+            continue;
+        for (const part of message.parts ?? []) {
+            const response = part.functionResponse;
+            if (!response?.name || !PREVIEW_TOOLS.has(response.name))
+                continue;
+            for (const url of extractMediaUrls(JSON.stringify(response.response ?? ''))) {
+                if (!urls.includes(url))
+                    urls.push(url);
+            }
+        }
+    }
+    return urls.slice(-MAX_PREVIEW_URLS);
+}
 /**
  * Classify the session's current state from the durable entries log with a
  * single read: parked on an ask_user question, actively generating, or idle.
@@ -169,10 +200,12 @@ export async function getWixelPendingQuestion({ sessionId, requireParked = false
                     continue;
                 if (ownTurn && message.turnId !== ownTurn)
                     return null;
+                const previewUrls = collectPreviewUrls(messages, i, message.turnId);
                 return {
                     toolCallId: call.id,
                     turnId: message.turnId,
-                    questions
+                    questions,
+                    ...(previewUrls.length ? { previewUrls } : {})
                 };
             }
             if (part.text || part.functionCall || part.functionResponse) {