@contenthero/mcp 0.4.11 → 0.4.12

package/dist/format.js

@@ -5,6 +5,7 @@
  */
 // The spec's own spelling of the key that binds a result to its widget. See `server.ts` for why only the
 // constants come from this package and not its server helpers.
+import { aspectLabel } from '@contenthero-ai/brand-ui';
 import { RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps';
 import { GENERATION_WIDGET_URI } from './widget-uri.js';
 import { ContentHeroError, InsufficientCreditsError, RateLimitError } from '@contenthero/sdk';
@@ -72,42 +73,82 @@ export function text(body, isError = false) {
 export const DEFAULT_APP_URL = 'https://app.contenthero.ai';
 export function studioUrlFor(baseUrl, outputId, index, total) {
     const root = baseUrl.replace(/\/+$/, '');
-    const variation = total > 1 ? `&variation=${index}` : '';
+    /**
+     * ⭐⭐⭐ **ONE-BASED, BECAUSE EVERY OTHER THING A PERSON SEES IS.**
+     *
+     * The reference they copy is `<id>-1`. The detail view says "Variation 1 of 4". A url saying
+     * `variation=0` for that same picture made three surfaces disagree, and the one that disagreed was the
+     * only one anybody would ever paste into a message or a bug report.
+     *
+     * ⛔ The studio's `imageIndex` is a ZERO-BASED slot and stays that way. Slot space is an internal fact
+     * about `task_outcomes` and `item_statuses`, not a number to show anyone. The app subtracts one when it
+     * reads this parameter, so the conversion sits at the boundary where the two vocabularies meet rather
+     * than leaking slot space into a shareable link.
+     */
+    const variation = total > 1 ? `&variation=${index + 1}` : '';
     return `${root}/studio?output=${encodeURIComponent(outputId)}${variation}`;
 }
+export function mediaWidgetData(input) {
+    return {
+        outputId: input.outputId ?? null,
+        contentType: input.contentType ?? null,
+        modelId: input.modelId ?? '',
+        /**
+         * ⛔⛔ **NULL WHEN THERE IS NOTHING TO NAME, AND THE WIDGET MUST RENDER NO CHIP.**
+         *
+         * This used to be `displayName ?? modelId`, fed by a catalog fetch with a `catch` that returned the id.
+         * The id reads like a label, so a failed fetch showed as a chip flickering between kebab case and title
+         * case rather than as a failure. The name now arrives on the row.
+         */
+        modelName: input.modelDisplayName ?? null,
+        modelBrandColor: input.modelBrandColor ?? null,
+        modelIconKey: input.modelIconKey ?? null,
+        displayAspect: input.displayAspect ?? null,
+        /** Verbatim. Some prompts are JSON-shaped because the person authored one; that object IS the prompt. */
+        prompt: input.prompt ?? null,
+        items: input.items.map((it) => ({
+            url: it.url,
+            posterUrl: it.posterUrl ?? null,
+            name: it.name,
+            contentType: it.contentType,
+            displayAspect: it.displayAspect ?? null,
+            openUrl: it.openUrl ?? null,
+            reference: it.reference ?? null,
+            modelName: it.modelName ?? null,
+            modelBrandColor: it.modelBrandColor ?? null,
+            modelIconKey: it.modelIconKey ?? null,
+        })),
+    };
+}
+/** A generation's widget payload. A thin adapter over {@link mediaWidgetData}, not a second builder. */
 export function generationWidgetData(gen, posterUrls = [], baseUrl = DEFAULT_APP_URL) {
     const urls = gen.outputUrls ?? [];
-    return {
+    return mediaWidgetData({
         outputId: gen.outputId,
         contentType: gen.contentType,
         modelId: gen.modelId,
+        modelDisplayName: gen.modelDisplayName,
+        modelBrandColor: gen.modelBrandColor,
+        modelIconKey: gen.modelIconKey,
         /**
-         * ⛔⛔ **NULL WHEN THERE IS NOTHING TO NAME, AND THE WIDGET MUST RENDER NO CHIP.**
-         *
-         * This used to be `displayName ?? gen.modelId`, fed by a catalog fetch in the server with a `catch`
-         * that returned the id. The id reads like a label, so a failed fetch showed as a chip flickering
-         * between kebab case and title case rather than as a failure. The name now arrives on the row.
-         *
-         * ⚠️ It is not always this generation's own model: an upload names itself, and a look names the model
-         * that produced the image it was assembled from.
+         * ⭐ SHARED, which is what makes a generation render as a ROW. Every variation of one generation has
+         * the same shape by construction, so the widget lays them out side by side for comparison rather than
+         * as a mixed grid.
          */
-        modelName: gen.modelDisplayName ?? null,
-        /** Hex brand accent from the registry, or null. The widget colors its chip with it. */
-        modelBrandColor: gen.modelBrandColor ?? null,
-        /** Brand family key (e.g. `"openai"`) for choosing a glyph. NOT the model id. */
-        modelIconKey: gen.modelIconKey ?? null,
-        /** `"W:H"`, or null for audio. Drives the column count and the tile's own shape. */
-        displayAspect: gen.displayAspect ?? null,
-        /** Verbatim. Some prompts are JSON-shaped because the person authored one; that object IS the prompt. */
-        prompt: gen.prompt ?? null,
-        outputs: urls.map((url, i) => ({
+        displayAspect: gen.displayAspect,
+        prompt: gen.prompt,
+        items: urls.map((url, i) => ({
             url,
             posterUrl: posterUrls[i] ?? null,
             name: `${gen.outputId}${urls.length > 1 ? `-${i + 1}` : ''}`,
-            /** Where the Open button goes: this asset, in the studio, with its siblings and every action. */
-            studioUrl: studioUrlFor(baseUrl, gen.outputId, i, urls.length),
+            contentType: gen.contentType,
+            displayAspect: gen.displayAspect ?? null,
+            // A generation lives in the studio. Another producer supplies its own destination.
+            openUrl: studioUrlFor(baseUrl, gen.outputId, i, urls.length),
+            // Every generation output is referenceable by id, which is what makes Animate and Edit meaningful.
+            reference: `${gen.outputId}${urls.length > 1 ? `-${i + 1}` : ''}`,
         })),
-    };
+    });
 }
 export function completedResult(gen, attachments = [], posterUrls = [], 
 /** The server this client talks to, so Open deep-links to it rather than always to production. */
@@ -215,7 +256,13 @@ export function getStatusCall(outputIds) {
  * case. The widget polls `get_generation_status`, and the name arrives with the first response.
  */
 export function pendingResult(outputId, pollAfterSeconds = 15, shape) {
-    const prose = `Still rendering (outputId ${outputId}). This is normal for video. Call ${getStatusCall([outputId])} in ~${pollAfterSeconds}s [poll_after_seconds: ${pollAfterSeconds}] to get the final URLs.`;
+    /**
+     * ⚠️ THE REASSURANCE MUST MATCH THE MEDIUM. This said "This is normal for video" on every pending result,
+     * including image jobs, where it reads as the server describing something other than what was asked for.
+     * `shape` is present precisely when we know which medium it is.
+     */
+    const normal = shape?.contentType === 'image' ? '' : ' This is normal for video.';
+    const prose = `Still rendering (outputId ${outputId}).${normal} Call ${getStatusCall([outputId])} in ~${pollAfterSeconds}s [poll_after_seconds: ${pollAfterSeconds}] to get the final URLs.`;
     if (!shape)
         return text(prose);
     return {
@@ -233,16 +280,48 @@ export function pendingResult(outputId, pollAfterSeconds = 15, shape) {
             /** At least one, or the widget renders a grid with nothing in it and looks broken rather than busy. */
             expected: Math.max(1, shape.expected ?? 1),
             pollAfterSeconds,
-            outputs: [],
+            items: [],
         },
         _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
     };
 }
 /** Synchronous audio result (already complete on submit). */
-export function audioResult(result) {
+/**
+ * Synchronous audio: already complete when the call returns.
+ *
+ * ## ⛔⛔⛔ THIS RENDERED NOTHING FOR THE ENTIRE LIFE OF THE WIDGET
+ *
+ * Audio has a first-class MCP block AND the widget plays it, and neither reached anyone, because this
+ * builder returned plain text and `generate_audio` was never added to the hand-maintained list of tools
+ * that declare a widget. Nobody decided audio should be invisible; it is what an allowlist does to
+ * anything nobody remembered to add.
+ *
+ * ⚠️ No model name, brand or aspect here: a synchronous result carries none of them, and inventing them
+ * would be worse than a chip that renders nothing. Audio has no shape, so `displayAspect` is genuinely
+ * null rather than unknown.
+ */
+export function audioResult(result, baseUrl = DEFAULT_APP_URL) {
     const urls = result.outputUrls ?? [];
     const header = `Done. Audio generated (outputId ${result.outputId}):`;
-    return text([header, ...urls.map((u, i) => `${i + 1}. ${u}`)].join('\n'));
+    const prose = [header, ...urls.map((u, i) => `${i + 1}. ${u}`)].join('\n');
+    if (!urls.length)
+        return text(prose);
+    return {
+        content: [{ type: 'text', text: prose }],
+        structuredContent: mediaWidgetData({
+            outputId: result.outputId,
+            contentType: 'audio',
+            items: urls.map((url, i) => ({
+                url,
+                name: `${result.outputId}${urls.length > 1 ? `-${i + 1}` : ''}`,
+                contentType: 'audio',
+                // Audio has no shape, so there is nothing for a tile to take.
+                displayAspect: null,
+                openUrl: studioUrlFor(baseUrl, result.outputId, i, urls.length),
+            })),
+        }),
+        _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
+    };
 }
 /**
  * In-place clip enhancement: ONE JOB PER SOURCE, so the agent gets every outputId.
@@ -299,8 +378,21 @@ export function generationStatusResult(gen, attachments = [], baseUrl) {
      * ⭐ Found by the `verify:inline` harness in its first run, minutes after it existed. The unit tests could
      * not see it: they call `completedResult` directly and never go through here.
      */
-    if (gen.status === 'completed')
-        return completedResult(gen, attachments, [], baseUrl);
+    if (gen.status === 'completed') {
+        const res = completedResult(gen, attachments, [], baseUrl);
+        /**
+         * ⛔⛔ **A REPORT CARRIES NO DISPLAY PAYLOAD, AND STRIPPING IT IS NOT COSMETIC.**
+         *
+         * This tool does not declare the widget, because `generate_*` already returns one that polls itself to
+         * completion and a second card for the same generation is the duplicate we removed. A result that still
+         * carried `structuredContent` and `_meta` would be ignored by the host, but it would also make
+         * "emits widget data" and "declares the widget" disagree, and that equivalence is exactly what the
+         * completeness guard checks in both directions. An invariant with an exemption is a list again.
+         */
+        delete res.structuredContent;
+        delete res._meta;
+        return res;
+    }
     if (gen.status === 'failed') {
         return text(`Generation ${gen.outputId} failed: ${gen.error ?? 'unknown error'}`, true);
     }
@@ -632,7 +724,54 @@ function batchItemLine(it, index, hasImage) {
  * array (fetched + base64-encoded by the caller, image items only; null for
  * video/audio/errors). This just assembles the result. See get-context §9.5.
  */
-export function mediaBatchResult(result, images) {
+/**
+ * Turn resolved media into tiles.
+ *
+ * ## ⭐⭐⭐ THE BYTES ARE FOR THE AGENT, THE URLS ARE FOR THE PERSON, AND ONE CALL DOES BOTH
+ *
+ * The image blocks above are the agent's vision and they cost context, which is why they run through one
+ * shared budget. The widget renders from URLS, which cost nothing. So a call can attach as many pixels as
+ * the budget allows AND display every item, and the two limits do not fight: more items means fewer
+ * inlined images, never a card that shows less than was asked for.
+ *
+ * ⛔ **NO CHIP, BECAUSE `model` HERE IS A RAW ID.** `gpt-image-2` reads like a label, and substituting one
+ * is the exact defect that made the generation chip flicker between kebab case and title case. Resolving
+ * it needs the registry, the same way the generation path got its name, so until this payload carries a
+ * display name the tiles render their media and no label.
+ *
+ * ⚠️ Transcripts are skipped: the widget has no element for text, and a tile that renders nothing is worse
+ * than an item the summary already describes in words.
+ */
+function mediaBatchItems(result, baseUrl) {
+    const items = [];
+    for (const it of result.items) {
+        if (!it.ok || !it.url)
+            continue;
+        if (it.type !== 'image' && it.type !== 'video' && it.type !== 'audio')
+            continue;
+        const g = it.geometry;
+        items.push({
+            url: it.url,
+            // A video's still, so a tile shows something before anyone presses play.
+            posterUrl: it.type === 'video' ? it.imageUrl : null,
+            /** The reference the API takes: `<id>` or `<id>-<n>`, one-based, matching what a person reads. */
+            name: it.mediaId ? `${it.mediaId}${it.variation && it.variation > 1 ? `-${it.variation}` : ''}` : it.url,
+            // ⚠️ Only a mediaId is referenceable. A raw url resolved here is not a library item the API can name.
+            reference: it.mediaId
+                ? `${it.mediaId}${it.variation && it.variation > 1 ? `-${it.variation}` : ''}`
+                : undefined,
+            contentType: it.type,
+            // MEASURED, from the storage spine. Null when nothing measured it, which the tile handles.
+            displayAspect: g ? aspectLabel(g.width, g.height) : null,
+            openUrl: it.mediaId
+                ? `${baseUrl.replace(/\/+$/, '')}/studio?output=${encodeURIComponent(it.mediaId)}` +
+                    (it.variation && it.variation > 1 ? `&variation=${it.variation}` : '')
+                : undefined,
+        });
+    }
+    return items;
+}
+export function mediaBatchResult(result, images, baseUrl = DEFAULT_APP_URL) {
     const { items } = result;
     const okCount = items.filter((i) => i.ok).length;
     const keyframeCount = items.reduce((n, it) => n + (it.keyframes?.length ?? 0), 0);
@@ -658,7 +797,18 @@ export function mediaBatchResult(result, images) {
             }
         }
     });
-    return { content };
+    /**
+     * ⭐ DISPLAY COSTS NOTHING EXTRA. The blocks above are the agent's vision and are budget-bounded; this is
+     * urls, so every resolved item renders whether or not its pixels fit that budget.
+     */
+    const tiles = mediaBatchItems(result, baseUrl);
+    if (tiles.length === 0)
+        return { content };
+    return {
+        content,
+        structuredContent: mediaWidgetData({ items: tiles }),
+        _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
+    };
 }
 /** Phase 1 of an upload: the signed URL + the PUT-then-complete instructions. */
 export function mediaUploadResult(r) {
@@ -679,8 +829,53 @@ export function mediaUploadResult(r) {
     ]));
 }
 /** A finalized upload or import: a first-class media output. */
-export function uploadedMediaResult(r) {
-    return text(`Media ready (id ${r.outputId}): ${r.url}. Reference it by outputId in generate_* or add_post_asset, or find it via list_media / get_media.`);
+/**
+ * Media the person's own bytes just became.
+ *
+ * ## ⭐ AN UPLOAD IS NEW MEDIA IN THEIR LIBRARY, SO IT DISPLAYS
+ *
+ * The rule is that a tool returning newly created or newly acquired media shows it, and an upload is the
+ * second. Confirmation is the value: a thumbnail says the right file landed, where a line of text says
+ * only that something did.
+ *
+ * ⛔ This could not render at all until the API started returning `contentType`. Guessing image from a
+ * url's extension is what renders a video as a broken image, so text was the honest answer while the type
+ * was unknown, and it remains the answer for a `document`, which has no element.
+ *
+ * ⚠️ Referenceable, unlike an export: `outputId` is exactly what `generate_*` accepts, which is what the
+ * prose has always told the caller.
+ */
+export function uploadedMediaResult(r, baseUrl = DEFAULT_APP_URL) {
+    const prose = `Media ready (id ${r.outputId}): ${r.url}. Reference it by outputId in generate_* or add_post_asset, or find it via list_media / get_media.`;
+    return renderableMedia(prose, r.outputId, r.url, r.contentType, baseUrl);
+}
+/**
+ * The shared tail of every "here is one new library item" result.
+ *
+ * ⚠️ ONE PLACE, because an upload and an import differ in their prose and in nothing else that matters
+ * here. Written twice they would drift the first time one of them learned something the other did not.
+ */
+function renderableMedia(prose, outputId, url, contentType, baseUrl) {
+    const medium = contentType === 'image' || contentType === 'video' || contentType === 'audio' ? contentType : undefined;
+    if (!outputId || !medium)
+        return text(prose);
+    return {
+        content: [{ type: 'text', text: prose }],
+        structuredContent: mediaWidgetData({
+            outputId,
+            contentType: medium,
+            items: [
+                {
+                    url,
+                    name: outputId,
+                    contentType: medium,
+                    reference: outputId,
+                    openUrl: studioUrlFor(baseUrl, outputId, 0, 1),
+                },
+            ],
+        }),
+        _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
+    };
 }
 /**
  * The result of an import, which may have created nothing.
@@ -699,9 +894,9 @@ export function uploadedMediaResult(r) {
  * Saying "already imported" without naming what it is would send someone hunting for a library item that
  * does not exist. That is the exact confusion this whole fix came from.
  */
-export function importedMediaResult(r) {
+export function importedMediaResult(r, baseUrl = DEFAULT_APP_URL) {
     if (!r.alreadyExisted) {
-        return text(`Media ready (id ${r.outputId}): ${r.url}. Reference it by outputId in generate_* or add_post_asset, or find it via list_media / get_media.`);
+        return renderableMedia(`Media ready (id ${r.outputId}): ${r.url}. Reference it by outputId in generate_* or add_post_asset, or find it via list_media / get_media.`, r.outputId, r.url, r.contentType, baseUrl);
     }
     if (r.outputId) {
         return text(`Already in your library (id ${r.outputId}): ${r.url}. Nothing was imported: these exact bytes are already there. Reference it by outputId as usual.`);
@@ -1465,6 +1660,53 @@ export function layerTypesResult(cat) {
         JSON.stringify(cat, null, 2));
 }
 /** A completed export -> the download URL; an in-flight one -> the exportId to poll. */
+/**
+ * Which formats the widget can actually draw.
+ *
+ * ⚠️ `pdf` and `pptx` have no element, and a multi-slide `png`/`jpg` export comes back as a ZIP rather than
+ * an image. Rendering a tile for any of them would show a broken picture where the text already gives a
+ * working download link, so they stay text.
+ */
+const EXPORT_MEDIUM = { mp4: 'video', png: 'image', jpg: 'image' };
+/**
+ * An export, DISPLAYED. Separate from {@link exportJobResult} by name, not by a flag.
+ *
+ * ## ⛔⛔ ONLY THE TOOL THAT STARTED THE EXPORT KNOWS ITS FORMAT
+ *
+ * `get_export` polls by exportId alone, so it cannot know whether the file is an mp4 or a pptx and can
+ * never render one. Leaving both paths inside one builder made the completeness guard read `get_export` as
+ * a tool that emits a widget, which it does not, and an invariant that has to be argued with is not one.
+ * Two names, each true on its own.
+ */
+export function completedExportResult(job, format, baseUrl = DEFAULT_APP_URL) {
+    const prose = `Export ${job.exportId} completed.\nDownload: ${job.outputUrl}`;
+    const medium = EXPORT_MEDIUM[format];
+    if (job.status !== 'completed' || !job.outputUrl || !medium)
+        return exportJobResult(job);
+    {
+        /**
+         * ## ⛔⛔ AN EXPORT RENDERS, AND IT IS NOT REFERENCEABLE
+         *
+         * Someone waited for a render, so they should see it. But an `exportId` is not an `outputId`: no
+         * generate tool resolves one, so Animate, Edit and Recreate would emit messages the agent cannot act
+         * on. Omitting `reference` is what hides them, and Download, the verb that actually applies to a
+         * rendered file, stays.
+         *
+         * ⚠️ NO `openUrl` EITHER, and not because it is hard to compute. An export's home is a download; the
+         * project it came from is a different destination with a different meaning, and `/editor/{id}` versus
+         * `/canvas/{id}` is not knowable from here anyway.
+         */
+        return {
+            content: [{ type: 'text', text: prose }],
+            structuredContent: mediaWidgetData({
+                contentType: medium,
+                items: [{ url: job.outputUrl, name: job.exportId, contentType: medium }],
+            }),
+            _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
+        };
+    }
+}
+/** An export, REPORTED. No widget: a poll does not know the format, so it cannot draw the file. */
 export function exportJobResult(job) {
     if (job.status === 'completed') {
         return text(`Export ${job.exportId} completed.\nDownload: ${job.outputUrl}`);