@wix/mcp 1.0.83 → 1.0.85

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

@@ -80,6 +80,16 @@ export function collectDecks(projectAssets, deckIds) {
     }
     return decks;
 }
+/**
+ * A reply that ends by asking the user something (a plan to approve, a
+ * choice to make) is not a delivery even when it links media — an animation
+ * plan links the source image it will animate. Asset-id markers ("Asset
+ * ready for … (id)") only appear on real deliveries; media URLs alone need
+ * this check.
+ */
+function isQuestionReply(text) {
+    return /\?\s*$/.test(text.trim());
+}
 // Image/video replies often carry no asset-id marker — just the media URL in
 // the text: a wixstatic file, a wixmp render (img-wixmp-*/wixmp-* hosts), or a
 // links.wixel.com short link that redirects to one. Those links are the
@@ -223,12 +233,87 @@ const QUESTION_TOOL_META = {
         visibility: ['app', 'model']
     }
 };
+const MAX_LIVE_CARD_HANDLES = 500;
+// A card that never reported done (unmounted, tab closed, timed out) must not
+// lock the agent out of the handle forever.
+const LIVE_CARD_TTL_MS = 30 * 60 * 1000;
+export function createLiveCardRegistry() {
+    const records = new Map();
+    const get = (handle) => records.get(handle);
+    const forHandle = (handle) => {
+        let record = records.get(handle);
+        if (!record) {
+            if (records.size >= MAX_LIVE_CARD_HANDLES) {
+                const oldest = records.keys().next().value;
+                if (oldest !== undefined)
+                    records.delete(oldest);
+            }
+            record = {
+                turns: new Map(),
+                finishedTurns: new Set(),
+                shownAssets: new Set(),
+                lastSentTurn: null
+            };
+            records.set(handle, record);
+        }
+        return record;
+    };
+    /**
+     * Whether the turn the agent last sent is being followed by a live card
+     * that has not finished. Only the card's own polls mark a turn finished,
+     * so when the card is gone this also consults the inbox: a terminal event
+     * for the turn ends the card's claim, as does the TTL.
+     */
+    const isActive = async (handle, params) => {
+        const record = records.get(handle);
+        const turnId = record?.lastSentTurn;
+        if (!record || !turnId)
+            return false;
+        const renderedAt = record.turns.get(turnId);
+        if (renderedAt === undefined || record.finishedTurns.has(turnId)) {
+            return false;
+        }
+        if (Date.now() - renderedAt > LIVE_CARD_TTL_MS) {
+            record.finishedTurns.add(turnId);
+            return false;
+        }
+        try {
+            if (await hasTerminalEvent({ ...params, handle, turnId })) {
+                record.finishedTurns.add(turnId);
+                return false;
+            }
+        }
+        catch (error) {
+            // Can't tell — keep the card's claim rather than let a second card in.
+            console.warn('[Wixel] live card terminal check failed:', error.message);
+        }
+        return true;
+    };
+    return { get, forHandle, isActive };
+}
+// Replays the inbox from the start (explicit cursor, so the agent's remembered
+// cursor never moves) and reports whether the turn has its reply/failed event.
+async function hasTerminalEvent(params) {
+    const inbox = await listWixelSessionEvents({
+        authHeaders: params.authHeaders,
+        conductorOverride: params.conductorOverride,
+        handle: params.handle,
+        metaSiteId: params.metaSiteId,
+        since: '0'
+    });
+    if (inbox.error) {
+        throw new Error(`${inbox.error} (${inbox.code ?? 'no code'})`);
+    }
+    return (inbox.events ?? []).some((event) => event.turnId === params.turnId &&
+        (event.type === 'reply' || event.type === 'failed'));
+}
 /** McpAppsBiProvider builds the widget's BI logger from
  *  widgetPayload.extras.biContext; without it every widget event is dropped. */
 function widgetResultMeta(server) {
     return { widgetPayload: { extras: server.getWidgetExtras() } };
 }
 export function addGetWixelPendingQuestionTool(server, authStrategy, options = {}) {
+    const liveCards = options.liveCards ?? createLiveCardRegistry();
     const { getSiteAuthHeaders } = authStrategy;
     // The wixel widget resource used by widget-bound tools (registered here
     // since the session tools are now the conversation surface).
@@ -288,6 +373,32 @@ Call this after a reply event whenever the reply asks the user something. In wid
                 sessionId: args.handle,
                 conductorOverride: options.conductorOverride
             });
+            // The live card renders this question inline; a second, standalone
+            // question widget would put it in the chat twice.
+            if (pending &&
+                options.supportsWidgets?.() === true &&
+                (await liveCards.isActive(args.handle, {
+                    authHeaders,
+                    conductorOverride: options.conductorOverride,
+                    metaSiteId: args.metaSiteId
+                }))) {
+                console.log('[WixelResponseDump]', JSON.stringify({
+                    tool: 'get_wixel_pending_question',
+                    args,
+                    suppressed: pending.toolCallId
+                }));
+                return {
+                    isError: false,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `The live result card already shows this question to the user and sends the answer to Wixel itself.
+<agent_instruction>Do NOT present the question and do NOT poll list_wixel_events — the card follows the turn. Do not tell the user to answer either — the card is self-explanatory. End your turn now WITHOUT writing any message — no summary, no "Wixel is working on it", nothing: the card already says it, and a sentence under it is redundant. If your client forces a reply, use at most two words.</agent_instruction>`
+                        }
+                    ],
+                    structuredContent: { success: true, pendingQuestion: null }
+                };
+            }
             // A caller-supplied binding that no longer matches the live pending
             // question means that question was already handled — report "nothing
             // pending" instead of a different question.
@@ -450,6 +561,7 @@ Without arguments Wixel provisions a new project and session. Pass metaSiteId to
     });
 }
 export function addSendWixelMessageTool(server, authStrategy, options = {}) {
+    const liveCards = options.liveCards ?? createLiveCardRegistry();
     const { getSiteAuthHeaders } = authStrategy;
     registerAppTool(server, 'send_wixel_message', {
         title: 'Send Wixel message',
@@ -483,14 +595,12 @@ Send the user's request as THEY phrased it. Do NOT add creative direction they d
         });
         const authHeaders = await getSiteAuthHeaders(args.metaSiteId);
         try {
-            // The external-session policy answers ask_user itself, so the agent
-            // has no reason to ask — but the structured payload is still persisted
-            // and get_wixel_pending_question renders it as a widget. Say so, or
-            // the outline and style the user was about to choose get decided for
-            // them. Mirrors the hint the widget appends to an answer.
-            const text = options.supportsWidgets?.()
-                ? `${args.text}\n(This client renders structured ask_user questions as interactive widgets. If the request leaves the outline, style or palette open, call ask_user and WAIT for a real answer before generating — do not fill the gaps yourself, and do not proceed on a default: once the asset exists the user can no longer choose.)`
-                : args.text;
+            // The user's text goes through as typed — nothing is appended. An
+            // earlier hint here asked Wixel to stop and ask about style/palette
+            // whenever a request left them open, which is why MCP users got
+            // questions the Wixel app never asks. Wixel's own flows (a deck's
+            // outline and style review) still ask, and the live card renders them.
+            const text = args.text;
             const result = await sendWixelSessionMessage({
                 authHeaders,
                 conductorOverride: options.conductorOverride,
@@ -520,22 +630,35 @@ Send the user's request as THEY phrased it. Do NOT add creative direction they d
                     }
                 };
             }
+            if (result.turnId) {
+                liveCards.forHandle(args.handle).lastSentTurn = result.turnId;
+            }
+            // Widget clients get a live result card that follows the turn itself
+            // (progress, questions, final asset), so the agent renders it once
+            // and stops — no polling loop of tool calls in the conversation.
+            const instruction = options.supportsWidgets?.()
+                ? `<agent_instruction>Now call get_wixel_asset_result with handle: "${args.handle}", metaSiteId: "${args.metaSiteId}", turnId: "${result.turnId}", prompt: <the user's request as they phrased it>. It renders a live result card that shows progress, asks the user any question Wixel has, and displays the final asset. Then end your turn — do NOT poll list_wixel_events and do NOT call get_wixel_pending_question, and do NOT write a message after the card (it explains itself).</agent_instruction>`
+                : `<agent_instruction>Poll list_wixel_events (handle: "${args.handle}", metaSiteId: "${args.metaSiteId}", waitSeconds: 25, advancing the returned cursor) until an event with turnId "${result.turnId}" has type "reply" or "failed". Turns can take minutes for generation tasks — keep polling.
+After a reply that asks the user something (review an outline, pick a style, confirm), call get_wixel_pending_question (same handle/metaSiteId) and follow its response instruction.</agent_instruction>`;
+            const structuredContent = {
+                success: true,
+                sessionId: result.sessionId,
+                turnId: result.turnId,
+                transactionId: result.transactionId ?? null
+            };
             return {
                 isError: false,
                 content: [
                     {
                         type: 'text',
                         text: `Turn accepted — turnId: ${result.turnId}.
-<agent_instruction>Poll list_wixel_events (handle: "${args.handle}", metaSiteId: "${args.metaSiteId}", waitSeconds: 25, advancing the returned cursor) until an event with turnId "${result.turnId}" has type "reply" or "failed". Turns can take minutes for generation tasks — keep polling.
-After a reply that asks the user something (review an outline, pick a style, confirm), call get_wixel_pending_question (same handle/metaSiteId) and follow its response instruction.</agent_instruction>`
-                    }
+${instruction}`
+                    },
+                    // The widgets send answers through this tool and need the turnId
+                    // back; hosts that drop structuredContent get it from this item.
+                    { type: 'text', text: JSON.stringify(structuredContent) }
                 ],
-                structuredContent: {
-                    success: true,
-                    sessionId: result.sessionId,
-                    turnId: result.turnId,
-                    transactionId: result.transactionId ?? null
-                }
+                structuredContent
             };
         }
         catch (error) {
@@ -551,6 +674,7 @@ After a reply that asks the user something (review an outline, pick a style, con
     });
 }
 export function addListWixelEventsTool(server, authStrategy, options = {}) {
+    const liveCards = options.liveCards ?? createLiveCardRegistry();
     const { getSiteAuthHeaders } = authStrategy;
     // Models routinely forget to thread the cursor through poll loops, which
     // makes them re-read old replies and misjudge the session state. Remember
@@ -603,6 +727,33 @@ Event types: "reply" (the agent's answer), "failed" (the turn failed), and "user
                 since,
                 historyMode: args.historyMode
             });
+            // A live result card is following the last turn: the agent has
+            // nothing to do here, and text instructions alone don't stop its
+            // polling loop — so refuse the call (no fetch, cursor untouched).
+            // The tool works again once the turn has ended (the card saw it, or
+            // the inbox says so when the card is gone).
+            if (options.supportsWidgets?.() === true &&
+                (await liveCards.isActive(args.handle, {
+                    authHeaders,
+                    conductorOverride: options.conductorOverride,
+                    metaSiteId: args.metaSiteId
+                }))) {
+                console.log('[WixelResponseDump]', JSON.stringify({ tool: 'list_wixel_events', args, refused: true }));
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Not needed: the live result card is following this generation and will display progress, any question, and the final result by itself. This is not a failure — there is nothing to wait for here. Do NOT call list_wixel_events, get_wixel_pending_question or get_wixel_asset_result again for this generation. End your turn now WITHOUT writing any message — no summary, no "Wixel is working on it", nothing: the card already says it, and a sentence under it is redundant. If your client forces a reply, use at most two words.`
+                        }
+                    ],
+                    structuredContent: {
+                        success: false,
+                        liveCard: true,
+                        error: 'live result card active'
+                    }
+                };
+            }
             let result = await fetchEvents();
             // Long-poll: hold the request while the inbox is empty so callers can
             // wait on slow turns (generation, widget answers) without hammering.
@@ -659,9 +810,30 @@ Event types: "reply" (the agent's answer), "failed" (the turn failed), and "user
                     .filter((event) => event.type === 'reply' && event.text)
                     .map((event) => event.text);
                 deliveredAssetIds = replyTexts.flatMap(extractAssetIds);
-                deliveredMediaUrls = replyTexts.flatMap(extractMediaUrls);
+                // Same rule as the live card: a reply that asks the user something
+                // (e.g. an animation plan linking its source image) delivers
+                // nothing by its media URLs alone.
+                deliveredMediaUrls = replyTexts
+                    .filter((text) => !isQuestionReply(text))
+                    .flatMap(extractMediaUrls);
                 if (deliveredAssetIds.length || deliveredMediaUrls.length) {
                     deliveredAssets = true;
+                    // Delivered by a turn a live card follows: the card shows them,
+                    // so a get_wixel_asset_result for these ids is a duplicate. Only
+                    // that turn's ids — a batch may also carry a turn no card follows.
+                    const record = liveCards.get(args.handle);
+                    if (record) {
+                        events
+                            .filter((event) => event.type === 'reply' &&
+                            !!event.text &&
+                            !!event.turnId &&
+                            record.turns.has(event.turnId))
+                            .flatMap((event) => [
+                            ...extractAssetIds(event.text).slice(0, MAX_RESULT_ITEMS),
+                            ...extractMediaUrls(event.text).slice(0, MAX_RESULT_ITEMS)
+                        ])
+                            .forEach((item) => record.shownAssets.add(item));
+                    }
                     try {
                         const projectId = await getWixelSessionProjectId({
                             authHeaders,
@@ -821,12 +993,380 @@ export function addGetWixelStylePresetsTool(server, authStrategy, options = {})
         }
     });
 }
+// Widget-internal (not exposed to the model). The result card renders the
+// moment the request is sent and drives the rest of the flow itself: it polls
+// this for the answer's turn and gets back "generating", a "question" to show
+// inline, the "done" assets, or "failed". The inbox is replayed from cursor
+// "0" with an explicit cursor, so the cursor list_wixel_events remembers per
+// handle for the agent is never advanced. "Done" is the reply/failed event of
+// the turn — the same signal the agent would have waited on; the entries log
+// only decides whether the turn is parked on a question, because the agent
+// emits text mid-turn and that log cannot tell it from the final reply.
+// `ui.visibility` is what MCP Apps hosts read; ChatGPT reads
+// `openai/visibility` instead, so both are set or its model would see the tool.
+const WIDGET_ONLY_TOOL_META = {
+    ui: { visibility: ['app'] },
+    'openai/visibility': 'private'
+};
+export function addGetWixelTurnResultTool(server, authStrategy, options = {}) {
+    const liveCards = options.liveCards ?? createLiveCardRegistry();
+    const { getSiteAuthHeaders } = authStrategy;
+    registerAppTool(server, 'get_wixel_turn_result', {
+        title: 'Get Wixel turn result',
+        description: 'Widget-internal: the live result card polls this for the outcome of a turn (generating, a question to answer, the delivered assets, or a failure). Not needed for normal conversation flows.',
+        inputSchema: {
+            handle: z.string().describe('Session handle from start_wixel_session'),
+            metaSiteId: z
+                .string()
+                .describe('Meta site ID from start_wixel_session'),
+            turnId: z
+                .string()
+                .describe('The turn to report on (returned by send_wixel_message)'),
+            live: z
+                .boolean()
+                .optional()
+                .describe('Set by the live result card: marks the turn as followed by the card, so the agent is told to stand back for it.')
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false
+        },
+        _meta: WIDGET_ONLY_TOOL_META
+    }, async (args, extra) => {
+        setBi(extra, {
+            siteId: args.metaSiteId,
+            conversationId: args.handle
+        });
+        // A turn the live card follows — including the turns its inline
+        // answers open, which get_wixel_asset_result never saw.
+        if (args.live) {
+            const record = liveCards.forHandle(args.handle);
+            if (!record.turns.has(args.turnId)) {
+                record.turns.set(args.turnId, Date.now());
+            }
+        }
+        const authHeaders = await getSiteAuthHeaders(args.metaSiteId);
+        const base = {
+            authHeaders,
+            conductorOverride: options.conductorOverride
+        };
+        try {
+            const inbox = await listWixelSessionEvents({
+                ...base,
+                handle: args.handle,
+                metaSiteId: args.metaSiteId,
+                since: '0'
+            });
+            if (inbox.error) {
+                throw new Error(`Failed to replay events: ${inbox.error} (${inbox.code ?? 'no code'})`);
+            }
+            const terminal = (inbox.events ?? []).find((event) => event.turnId === args.turnId &&
+                (event.type === 'reply' || event.type === 'failed'));
+            let status = 'generating';
+            let assets = [];
+            let editorUrl = null;
+            let pendingQuestion = null;
+            const replyText = terminal?.text ?? null;
+            if (terminal?.type === 'failed') {
+                status = 'failed';
+            }
+            else if (terminal) {
+                // Capped like the resolver's input, so what gets recorded as
+                // shown below is exactly what was considered for rendering.
+                const assetIds = extractAssetIds(terminal.text ?? '').slice(0, MAX_RESULT_ITEMS);
+                const mediaUrls = extractMediaUrls(terminal.text ?? '').slice(0, MAX_RESULT_ITEMS);
+                // Media URLs alone count only when the reply is not a question:
+                // an animation plan links the source image and asks for approval.
+                const delivers = assetIds.length > 0 ||
+                    (mediaUrls.length > 0 && !isQuestionReply(terminal.text ?? ''));
+                if (delivers) {
+                    status = 'done';
+                    // Only the live card displays what it resolves. The standalone
+                    // question widget polls for the status alone: resolving for it
+                    // would be wasted work, and marking the ids as shown would make
+                    // the agent's own get_wixel_asset_result a "duplicate".
+                    if (args.live) {
+                        ({ assets, editorUrl } = await resolveWixelAssetResults({
+                            ...base,
+                            handle: args.handle,
+                            metaSiteId: args.metaSiteId,
+                            assetIds,
+                            mediaUrls
+                        }));
+                        // Only what the card will actually show counts as shown. A
+                        // resolution that came back empty (transient lookup failure)
+                        // leaves the result for the agent's get_wixel_asset_result.
+                        if (assets.length) {
+                            const record = liveCards.forHandle(args.handle);
+                            [...assetIds, ...mediaUrls].forEach((item) => record.shownAssets.add(item));
+                        }
+                    }
+                }
+                else {
+                    // A reply without a delivery is either a question restated as
+                    // text (its structured payload is still pending) or a plain
+                    // message — the card shows it with a reply box.
+                    pendingQuestion = await getWixelPendingQuestion({
+                        ...base,
+                        sessionId: args.handle
+                    });
+                    status = pendingQuestion ? 'question' : 'done';
+                }
+            }
+            else {
+                // No terminal event yet: parked on a question (custom_widget asks
+                // park the turn without a reply event) or still generating.
+                const activity = await getWixelSessionActivity({
+                    ...base,
+                    sessionId: args.handle
+                });
+                pendingQuestion = activity.parkedQuestion;
+                if (pendingQuestion)
+                    status = 'question';
+            }
+            console.log('[WixelResponseDump]', JSON.stringify({
+                tool: 'get_wixel_turn_result',
+                args,
+                status,
+                assets,
+                editorUrl,
+                pendingQuestionId: pendingQuestion?.toolCallId ?? null
+            }).slice(0, 30000));
+            if (args.live && (status === 'done' || status === 'failed')) {
+                liveCards.forHandle(args.handle).finishedTurns.add(args.turnId);
+            }
+            const structuredContent = {
+                success: true,
+                status,
+                turnId: args.turnId,
+                assets,
+                editorUrl,
+                pendingQuestion,
+                replyText,
+                message: status === 'failed' ? replyText : null
+            };
+            return {
+                isError: false,
+                // Widget-only tool: the text IS the payload, so a host that drops
+                // structuredContent (the widget bridge falls back to parsing the
+                // first JSON text item) still delivers the status to the card.
+                content: [
+                    { type: 'text', text: JSON.stringify(structuredContent) }
+                ],
+                structuredContent
+            };
+        }
+        catch (error) {
+            rethrowIfUnauthorized(error);
+            console.error('❌ Error getting Wixel turn result:', error);
+            const errorMessage = error.message;
+            return {
+                isError: true,
+                content: [{ type: 'text', text: errorMessage }],
+                structuredContent: { success: false, error: errorMessage }
+            };
+        }
+    });
+}
+/**
+ * Turn the asset ids and media URLs a reply delivered into renderable result
+ * entries (video first, then decks, stills, documents) plus the editor deep
+ * link. Shared by get_wixel_asset_result and get_wixel_turn_result.
+ */
+async function resolveWixelAssetResults(args) {
+    const { authHeaders } = args;
+    const options = { conductorOverride: args.conductorOverride };
+    // The model-facing schema caps these, but the live path feeds the resolver
+    // straight from a reply's text — cap here too, or one oversized reply
+    // fans out into an unbounded number of authenticated lookups.
+    const cappedAssetIds = (args.assetIds ?? []).slice(0, MAX_RESULT_ITEMS);
+    const cappedMediaUrls = (args.mediaUrls ?? []).slice(0, MAX_RESULT_ITEMS);
+    // Best-effort: the project id only builds the editor deep link, so a
+    // failing sessions endpoint must not sink a result whose media URLs
+    // are perfectly renderable.
+    let projectId = null;
+    try {
+        projectId = await getWixelSessionProjectId({
+            authHeaders,
+            conductorOverride: options.conductorOverride,
+            sessionId: args.handle
+        });
+    }
+    catch (projectError) {
+        console.warn('[Wixel] editor link resolution failed:', projectError.message);
+    }
+    const editorUrl = projectId
+        ? buildWixelEditorUrl(args.metaSiteId, projectId)
+        : null;
+    // Repeated ids/URLs would each cost their own request.
+    const requestedAssetIds = Array.from(new Set(cappedAssetIds));
+    const requestedMediaUrls = Array.from(new Set(cappedMediaUrls));
+    // Short links resolve to the final media file (mp4 on wixmp etc.) so
+    // the widget can play/show them inline. Anything that isn't allowlisted
+    // Wix media is dropped rather than passed through.
+    const resolvedMedia = (await mapWithConcurrency(requestedMediaUrls, RESULT_CONCURRENCY, async (raw) => {
+        const parsed = parseWixelMediaUrl(raw);
+        if (!parsed) {
+            console.warn('[Wixel] rejected media URL', raw);
+            return null;
+        }
+        const finalUrl = isWixelShortLink(parsed)
+            ? await resolveWixelShortLink(parsed)
+            : parsed.toString();
+        if (!finalUrl)
+            return null;
+        return {
+            url: finalUrl,
+            kind: isVideoUrl(finalUrl)
+                ? 'video'
+                : isDocumentUrl(finalUrl)
+                    ? 'document'
+                    : 'image'
+        };
+    })).filter((media) => media !== null);
+    // getAsset is project-scoped, so without a real project id every lookup
+    // would be invalid — skip them and let the reply's media URLs carry the
+    // result rather than returning nothing.
+    if (requestedAssetIds.length && !projectId) {
+        console.warn('[Wixel] skipping asset id lookups — project id unavailable');
+    }
+    // Fetch the entities first, keeping assetIds order — assigning media
+    // URLs inside the concurrent lookups would pair them by completion
+    // order instead.
+    const entities = projectId
+        ? await mapWithConcurrency(requestedAssetIds, RESULT_CONCURRENCY, async (assetId) => {
+            try {
+                return {
+                    assetId,
+                    asset: await getAsset({
+                        siteAuthHeaders: authHeaders,
+                        assetId,
+                        projectId,
+                        conductorOverride: options.conductorOverride
+                    })
+                };
+            }
+            catch (assetError) {
+                // An auth failure is the caller's problem to fix, not a
+                // skippable asset — let it reach rethrowIfUnauthorized below.
+                rethrowIfUnauthorized(assetError);
+                console.warn('[Wixel] asset resolution failed', assetId, assetError.message);
+                return { assetId, asset: null };
+            }
+        })
+        : [];
+    // Video assets carry no thumbnailUrl — their playable file arrives as a
+    // media URL in the reply. Only pair them when the counts line up 1:1;
+    // with a failed lookup in the mix there is no way to tell which URL
+    // belongs to which asset, and guessing would label the wrong file.
+    const videoMedia = resolvedMedia.filter((m) => m.kind === 'video');
+    const videoEntities = entities.filter(({ asset }) => asset && String(asset.type) === 'VIDEO');
+    const pairVideos = videoMedia.length === videoEntities.length;
+    if (!pairVideos && videoMedia.length && videoEntities.length) {
+        console.warn(`[Wixel] not pairing video media: ${videoEntities.length} video assets vs ${videoMedia.length} URLs`);
+    }
+    const videoMediaQueue = pairVideos ? [...videoMedia] : [];
+    const usedUrls = new Set();
+    // Pages are sibling assets, so they need a project-wide lookup.
+    const deckIds = selectDeckIds(entities.flatMap(({ asset }) => (asset ? [asset] : [])));
+    let decks = new Map();
+    if (deckIds.size && projectId) {
+        try {
+            const { assets: projectAssets } = await queryAssets({
+                siteAuthHeaders: authHeaders,
+                projectId,
+                conductorOverride: options.conductorOverride
+            });
+            decks = collectDecks((projectAssets ?? []), deckIds);
+        }
+        catch (deckError) {
+            rethrowIfUnauthorized(deckError);
+            console.warn('[Wixel] slide page lookup failed:', deckError.message);
+        }
+    }
+    const seenDecks = new Set();
+    let assets = entities.flatMap(({ assetId, asset }) => {
+        if (!asset)
+            return [];
+        // One card per deck: several page ids are one deliverable.
+        if (isSlideAsset(asset)) {
+            const deckId = asset.parentId ?? asset.id ?? assetId;
+            if (!deckIds.has(deckId))
+                return [];
+            const deck = decks.get(deckId);
+            if (deck) {
+                if (seenDecks.has(deckId))
+                    return [];
+                seenDecks.add(deckId);
+                deck.pageUrls.forEach((url) => usedUrls.add(url));
+                return [
+                    {
+                        id: deckId,
+                        kind: 'slides',
+                        name: deck.name ?? asset.name ?? null,
+                        url: deck.pageUrls[0],
+                        slideUrls: deck.pageUrls
+                    }
+                ];
+            }
+            // No pages resolved — fall through to the cover image.
+        }
+        const kind = String(asset.type) === 'VIDEO'
+            ? 'video'
+            : 'image';
+        // A video card needs the playable file. Some video assets do carry a
+        // thumbnailUrl (a poster frame), but rendering that as the video
+        // would produce a card that never plays — so drop the entity instead
+        // and let the reply's own video URLs stand in below.
+        const url = (kind === 'video'
+            ? (videoMediaQueue.shift()?.url ?? null)
+            : (asset.thumbnailUrl ?? null)) ?? null;
+        if (!url)
+            return [];
+        usedUrls.add(url);
+        return [{ id: asset.id ?? assetId, kind, name: asset.name ?? null, url }];
+    });
+    // Media URLs stand in for assets we couldn't resolve, so append the
+    // leftovers — but only for a kind no entity already produced, or an
+    // animation reply (image id + video URL, plus the source image URL)
+    // would render its still twice.
+    const resolvedKinds = new Set(assets.map((asset) => asset.kind));
+    const resolvedDeck = assets.some((asset) => asset.kind === 'slides');
+    resolvedMedia.forEach((media, index) => {
+        if (usedUrls.has(media.url) || resolvedKinds.has(media.kind))
+            return;
+        // A deck's reply cites imagery used inside its pages, and its own
+        // PDF export — ingredients and duplicates, not extra deliverables.
+        if (resolvedDeck && media.kind !== 'video')
+            return;
+        assets.push({
+            id: `media-${index}`,
+            kind: media.kind,
+            name: null,
+            url: media.url
+        });
+    });
+    // Animating a still delivers BOTH the source image and the video, in
+    // that order — but the video is the deliverable the user asked for, so
+    // it leads, then decks, then loose stills. Image-only results keep
+    // their reply order.
+    assets = [
+        ...assets.filter((asset) => asset.kind === 'video'),
+        ...assets.filter((asset) => asset.kind === 'slides'),
+        ...assets.filter((asset) => asset.kind === 'image'),
+        ...assets.filter((asset) => asset.kind === 'document')
+    ];
+    return { assets, editorUrl };
+}
 export function addGetWixelAssetResultTool(server, authStrategy, options = {}) {
+    const liveCards = options.liveCards ?? createLiveCardRegistry();
     const { getSiteAuthHeaders } = authStrategy;
     registerAppTool(server, 'get_wixel_asset_result', {
         title: 'Get Wixel asset result',
-        description: `Resolve the assets a Wixel reply delivered into previewable results. Call this once a reply event delivers assets, passing the assetIds and mediaUrls EXACTLY as returned by list_wixel_events (never invent ids — a turnId is NOT an asset id).
-In widget-capable clients this renders the result card (preview image/video with edit and download actions); otherwise present the returned asset links as text, always including the Edit in Wixel link.`,
+        description: `Render the result of a Wixel generation.
+In widget-capable clients call it RIGHT AFTER send_wixel_message with the returned turnId: it renders a live result card that shows generation progress, asks the user any questions Wixel has, and displays the final asset — no polling needed.
+Otherwise (or when a list_wixel_events reply already delivered assets) pass the assetIds and mediaUrls EXACTLY as returned by list_wixel_events (never invent ids — a turnId is NOT an asset id) and present the returned asset links as text, always including the Edit in Wixel link.`,
         inputSchema: {
             handle: z.string().describe('Session handle from start_wixel_session'),
             metaSiteId: z
@@ -848,7 +1388,11 @@ In widget-capable clients this renders the result card (preview image/video with
                 .string()
                 .max(4000)
                 .optional()
-                .describe("The user's original generation request, shown above the preview")
+                .describe("The user's original generation request, shown above the preview"),
+            turnId: z
+                .string()
+                .optional()
+                .describe('The turn returned by send_wixel_message. Widget clients: pass this (without assetIds/mediaUrls) to render the live card while Wixel generates.')
         },
         annotations: {
             readOnlyHint: true,
@@ -863,183 +1407,137 @@ In widget-capable clients this renders the result card (preview image/video with
         });
         const authHeaders = await getSiteAuthHeaders(args.metaSiteId);
         try {
-            // Best-effort: the project id only builds the editor deep link, so a
-            // failing sessions endpoint must not sink a result whose media URLs
-            // are perfectly renderable.
-            let projectId = null;
-            try {
-                projectId = await getWixelSessionProjectId({
-                    authHeaders,
-                    conductorOverride: options.conductorOverride,
-                    sessionId: args.handle
-                });
-            }
-            catch (projectError) {
-                console.warn('[Wixel] editor link resolution failed:', projectError.message);
-            }
-            const editorUrl = projectId
-                ? buildWixelEditorUrl(args.metaSiteId, projectId)
-                : null;
-            // Repeated ids/URLs would each cost their own request.
-            const requestedAssetIds = Array.from(new Set(args.assetIds ?? []));
-            const requestedMediaUrls = Array.from(new Set(args.mediaUrls ?? []));
-            // Short links resolve to the final media file (mp4 on wixmp etc.) so
-            // the widget can play/show them inline. Anything that isn't allowlisted
-            // Wix media is dropped rather than passed through.
-            const resolvedMedia = (await mapWithConcurrency(requestedMediaUrls, RESULT_CONCURRENCY, async (raw) => {
-                const parsed = parseWixelMediaUrl(raw);
-                if (!parsed) {
-                    console.warn('[Wixel] rejected media URL', raw);
-                    return null;
-                }
-                const finalUrl = isWixelShortLink(parsed)
-                    ? await resolveWixelShortLink(parsed)
-                    : parsed.toString();
-                if (!finalUrl)
-                    return null;
-                return {
-                    url: finalUrl,
-                    kind: isVideoUrl(finalUrl)
-                        ? 'video'
-                        : isDocumentUrl(finalUrl)
-                            ? 'document'
-                            : 'image'
-                };
-            })).filter((media) => media !== null);
-            // getAsset is project-scoped, so without a real project id every lookup
-            // would be invalid — skip them and let the reply's media URLs carry the
-            // result rather than returning nothing.
-            if (requestedAssetIds.length && !projectId) {
-                console.warn('[Wixel] skipping asset id lookups — project id unavailable');
-            }
-            // Fetch the entities first, keeping assetIds order — assigning media
-            // URLs inside the concurrent lookups would pair them by completion
-            // order instead.
-            const entities = projectId
-                ? await mapWithConcurrency(requestedAssetIds, RESULT_CONCURRENCY, async (assetId) => {
-                    try {
-                        return {
-                            assetId,
-                            asset: await getAsset({
-                                siteAuthHeaders: authHeaders,
-                                assetId,
-                                projectId,
-                                conductorOverride: options.conductorOverride
-                            })
-                        };
-                    }
-                    catch (assetError) {
-                        // An auth failure is the caller's problem to fix, not a
-                        // skippable asset — let it reach rethrowIfUnauthorized below.
-                        rethrowIfUnauthorized(assetError);
-                        console.warn('[Wixel] asset resolution failed', assetId, assetError.message);
-                        return { assetId, asset: null };
-                    }
-                })
-                : [];
-            // Video assets carry no thumbnailUrl — their playable file arrives as a
-            // media URL in the reply. Only pair them when the counts line up 1:1;
-            // with a failed lookup in the mix there is no way to tell which URL
-            // belongs to which asset, and guessing would label the wrong file.
-            const videoMedia = resolvedMedia.filter((m) => m.kind === 'video');
-            const videoEntities = entities.filter(({ asset }) => asset && String(asset.type) === 'VIDEO');
-            const pairVideos = videoMedia.length === videoEntities.length;
-            if (!pairVideos && videoMedia.length && videoEntities.length) {
-                console.warn(`[Wixel] not pairing video media: ${videoEntities.length} video assets vs ${videoMedia.length} URLs`);
-            }
-            const videoMediaQueue = pairVideos ? [...videoMedia] : [];
-            const usedUrls = new Set();
-            // Pages are sibling assets, so they need a project-wide lookup.
-            const deckIds = selectDeckIds(entities.flatMap(({ asset }) => asset ? [asset] : []));
-            let decks = new Map();
-            if (deckIds.size && projectId) {
-                try {
-                    const { assets: projectAssets } = await queryAssets({
-                        siteAuthHeaders: authHeaders,
-                        projectId,
-                        conductorOverride: options.conductorOverride
-                    });
-                    decks = collectDecks((projectAssets ?? []), deckIds);
+            if (!args.assetIds?.length && !args.mediaUrls?.length) {
+                // Live mode: nothing to resolve yet — the widget follows the turn.
+                if (!args.turnId) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Pass the turnId from send_wixel_message (widget clients) or the assetIds/mediaUrls a reply delivered.'
+                            }
+                        ],
+                        structuredContent: { success: false, error: 'missing turnId' }
+                    };
                 }
-                catch (deckError) {
-                    rethrowIfUnauthorized(deckError);
-                    console.warn('[Wixel] slide page lookup failed:', deckError.message);
+                if (options.supportsWidgets?.() !== true) {
+                    return {
+                        isError: false,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `This client cannot render the live card.
+<agent_instruction>Poll list_wixel_events (handle: "${args.handle}", metaSiteId: "${args.metaSiteId}", waitSeconds: 25) until turnId "${args.turnId}" has a "reply" or "failed" event, then follow that response's instruction.</agent_instruction>`
+                            }
+                        ],
+                        structuredContent: {
+                            success: false,
+                            pending: true,
+                            turnId: args.turnId
+                        }
+                    };
                 }
-            }
-            const seenDecks = new Set();
-            let assets = entities.flatMap(({ assetId, asset }) => {
-                if (!asset)
-                    return [];
-                // One card per deck: several page ids are one deliverable.
-                if (isSlideAsset(asset)) {
-                    const deckId = asset.parentId ?? asset.id ?? assetId;
-                    if (!deckIds.has(deckId))
-                        return [];
-                    const deck = decks.get(deckId);
-                    if (deck) {
-                        if (seenDecks.has(deckId))
-                            return [];
-                        seenDecks.add(deckId);
-                        deck.pageUrls.forEach((url) => usedUrls.add(url));
-                        return [
+                const record = liveCards.forHandle(args.handle);
+                if (record.turns.has(args.turnId)) {
+                    // Already rendered for this turn — a second card would show the
+                    // same generation twice.
+                    console.log('[WixelResponseDump]', JSON.stringify({
+                        tool: 'get_wixel_asset_result',
+                        args,
+                        live: true,
+                        duplicate: true
+                    }));
+                    const duplicateContent = {
+                        success: true,
+                        pending: true,
+                        duplicate: true,
+                        turnId: args.turnId,
+                        assets: [],
+                        editorUrl: null,
+                        prompt: args.prompt ?? null
+                    };
+                    return {
+                        isError: false,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `The live result card for this turn is already displayed.
+<agent_instruction>Do not call any Wixel tool again for this generation. End your turn now WITHOUT writing any message — no summary, no "Wixel is working on it", nothing: the card already says it, and a sentence under it is redundant. If your client forces a reply, use at most two words.</agent_instruction>`
+                            },
                             {
-                                id: deckId,
-                                kind: 'slides',
-                                name: deck.name ?? asset.name ?? null,
-                                url: deck.pageUrls[0],
-                                slideUrls: deck.pageUrls
+                                type: 'text',
+                                text: JSON.stringify(duplicateContent)
                             }
-                        ];
-                    }
-                    // No pages resolved — fall through to the cover image.
+                        ],
+                        structuredContent: duplicateContent
+                    };
                 }
-                const kind = String(asset.type) === 'VIDEO'
-                    ? 'video'
-                    : 'image';
-                // A video card needs the playable file. Some video assets do carry a
-                // thumbnailUrl (a poster frame), but rendering that as the video
-                // would produce a card that never plays — so drop the entity instead
-                // and let the reply's own video URLs stand in below.
-                const url = (kind === 'video'
-                    ? (videoMediaQueue.shift()?.url ?? null)
-                    : (asset.thumbnailUrl ?? null)) ?? null;
-                if (!url)
-                    return [];
-                usedUrls.add(url);
-                return [
-                    { id: asset.id ?? assetId, kind, name: asset.name ?? null, url }
-                ];
-            });
-            // Media URLs stand in for assets we couldn't resolve, so append the
-            // leftovers — but only for a kind no entity already produced, or an
-            // animation reply (image id + video URL, plus the source image URL)
-            // would render its still twice.
-            const resolvedKinds = new Set(assets.map((asset) => asset.kind));
-            const resolvedDeck = assets.some((asset) => asset.kind === 'slides');
-            resolvedMedia.forEach((media, index) => {
-                if (usedUrls.has(media.url) || resolvedKinds.has(media.kind))
-                    return;
-                // A deck's reply cites imagery used inside its pages, and its own
-                // PDF export — ingredients and duplicates, not extra deliverables.
-                if (resolvedDeck && media.kind !== 'video')
-                    return;
-                assets.push({
-                    id: `media-${index}`,
-                    kind: media.kind,
-                    name: null,
-                    url: media.url
-                });
+                record.turns.set(args.turnId, Date.now());
+                console.log('[WixelResponseDump]', JSON.stringify({ tool: 'get_wixel_asset_result', args, live: true }));
+                const liveContent = {
+                    success: true,
+                    pending: true,
+                    turnId: args.turnId,
+                    assets: [],
+                    editorUrl: null,
+                    prompt: args.prompt ?? null
+                };
+                return {
+                    isError: false,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `The live result card is displayed to the user. It shows generation progress, lets the user answer any question Wixel asks, and displays the final asset with edit/download actions — all inside the card.
+<agent_instruction>Do NOT poll list_wixel_events and do NOT call get_wixel_pending_question — the card handles the rest of this generation itself. End your turn now WITHOUT writing any message — no summary, no "Wixel is working on it", nothing: the card already says it, and a sentence under it is redundant. If your client forces a reply, use at most two words.</agent_instruction>`
+                        },
+                        { type: 'text', text: JSON.stringify(liveContent) }
+                    ],
+                    structuredContent: liveContent,
+                    _meta: widgetResultMeta(server)
+                };
+            }
+            // A live card already displays these assets (list_wixel_events or
+            // get_wixel_turn_result recorded them for a live turn) — rendering
+            // them again would put the result in the chat twice.
+            const shown = liveCards.get(args.handle)?.shownAssets;
+            const requested = [...(args.assetIds ?? []), ...(args.mediaUrls ?? [])];
+            if (options.supportsWidgets?.() === true &&
+                shown?.size &&
+                requested.every((item) => shown.has(item))) {
+                console.log('[WixelResponseDump]', JSON.stringify({
+                    tool: 'get_wixel_asset_result',
+                    args,
+                    duplicate: true
+                }));
+                const duplicateContent = {
+                    success: true,
+                    duplicate: true,
+                    assets: [],
+                    editorUrl: null,
+                    prompt: args.prompt ?? null
+                };
+                return {
+                    isError: false,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `This result is already displayed by the live result card.
+<agent_instruction>Do NOT present the asset again (no links, no image). End your turn now WITHOUT writing any message — no summary, no "Wixel is working on it", nothing: the card already says it, and a sentence under it is redundant. If your client forces a reply, use at most two words.</agent_instruction>`
+                        },
+                        { type: 'text', text: JSON.stringify(duplicateContent) }
+                    ],
+                    structuredContent: duplicateContent
+                };
+            }
+            const { assets, editorUrl } = await resolveWixelAssetResults({
+                authHeaders,
+                conductorOverride: options.conductorOverride,
+                handle: args.handle,
+                metaSiteId: args.metaSiteId,
+                assetIds: args.assetIds,
+                mediaUrls: args.mediaUrls
             });
-            // Animating a still delivers BOTH the source image and the video, in
-            // that order — but the video is the deliverable the user asked for, so
-            // it leads, then decks, then loose stills. Image-only results keep
-            // their reply order.
-            assets = [
-                ...assets.filter((asset) => asset.kind === 'video'),
-                ...assets.filter((asset) => asset.kind === 'slides'),
-                ...assets.filter((asset) => asset.kind === 'image'),
-                ...assets.filter((asset) => asset.kind === 'document')
-            ];
             console.log('[WixelResponseDump]', JSON.stringify({
                 tool: 'get_wixel_asset_result',
                 args,
@@ -1103,11 +1601,16 @@ In widget-capable clients this renders the result card (preview image/video with
     });
 }
 export function addWixelSessionTools(server, authStrategy, options = {}) {
-    addStartWixelSessionTool(server, authStrategy, options);
-    addSendWixelMessageTool(server, authStrategy, options);
-    addListWixelEventsTool(server, authStrategy, options);
-    addGetWixelPendingQuestionTool(server, authStrategy, options);
-    addGetWixelAssetResultTool(server, authStrategy, options);
-    addGetWixelStylePresetsTool(server, authStrategy, options);
+    const shared = {
+        ...options,
+        liveCards: options.liveCards ?? createLiveCardRegistry()
+    };
+    addStartWixelSessionTool(server, authStrategy, shared);
+    addSendWixelMessageTool(server, authStrategy, shared);
+    addListWixelEventsTool(server, authStrategy, shared);
+    addGetWixelPendingQuestionTool(server, authStrategy, shared);
+    addGetWixelAssetResultTool(server, authStrategy, shared);
+    addGetWixelStylePresetsTool(server, authStrategy, shared);
+    addGetWixelTurnResultTool(server, authStrategy, shared);
 }
 //# sourceMappingURL=wixel-session-tools.js.map