@contenthero/mcp 0.4.12 → 0.4.14

package/dist/format.js

@@ -1,1760 +0,0 @@
-/**
- * Helpers that turn SDK results and errors into MCP CallToolResult content.
- * Tool errors are returned as `isError` results (not thrown) so the agent sees
- * a readable message instead of a transport failure.
- */
-// 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';
-export function text(body, isError = false) {
-    return { content: [{ type: 'text', text: body }], isError };
-}
-/**
- * A finished generation: the asset URLs and placement outcome, plus the asset ITSELF.
- *
- * ## Why this used to be text only
- *
- * 🚨 **AN AGENT THAT GENERATES AN IMAGE COULD NOT SEE IT.** This returned a header, an outputId and a
- * numbered list of urls, so the model had metadata and nothing else. Measured 2026-09-19 in a real ChatGPT
- * and Claude session: Claude said "I can't see the image myself, only the metadata", and the link it
- * surfaced was dead on arrival because ChatGPT had appended `utm_source=chatgpt.com` to a presigned URL and
- * broken its signature.
- *
- * ⭐ The machinery already existed and was wired to the wrong tools: `mediaBatchResult` and
- * `liveContextResult` have pushed image blocks for a while. Generation, the surface where a user most wants
- * to SEE the result, was the one that did not.
- *
- * ## ⛔ THE AGENT CANNOT SEE WHAT IT MADE FROM THIS RESULT, AND THAT IS DELIBERATE
- *
- * An `image` block feeds the MODEL's vision; a `resource_link` gives the HOST something to render for the
- * human. So the user sees every variation inline, and the model has a name and a url.
- *
- * ⭐ **`get_media` IS HOW A MODEL ACTUALLY LOOKS AT SOMETHING.** It embeds bytes as image blocks for exactly
- * that purpose, so an agent that needs to judge a result (is the hand wrong, is the text legible, which of
- * these four is best) calls it with the outputId. Embedding bytes HERE instead would spend the user's
- * context on every generation to answer a question they may never ask, and a four-image batch would pay
- * that cost four times over, repeated in every later turn.
- *
- * ⚠️ ATTACHMENTS ARE BUILT BY THE CALLER, not here. This module stays pure, the same split
- * `mediaBatchResult` already uses: the handler decides, the formatter assembles.
- */
-/**
- * What the generation WIDGET reads.
- *
- * ⭐⭐ `structuredContent` IS THE WIDGET'S ONLY INPUT. It is a separate channel from `content`: the blocks
- * feed the model and any host without app support, this feeds the UI. Both are emitted, so nothing regresses
- * where widgets are unsupported and nothing is duplicated where they are.
- *
- * ⚠️ URLS ONLY, NEVER BYTES. The widget runs in the host's frame and fetches media itself, and our
- * capability urls carry their token in the QUERY STRING, so `<video src>` loads one directly with no header
- * to set. Embedding base64 here would pay the context cost twice over.
- */
-/**
- * Where one output lives in the product.
- *
- * ## ⭐⭐⭐ COMPUTED HERE, NOT IN THE WIDGET, BECAUSE HERE THE INDEX IS ALREADY A NUMBER
- *
- * The widget's first version parsed the slot back out of the output's NAME (`<id>-3` means slot 2), which
- * is a derivation of something this function has in its hand. Parsing a number out of a string we formatted
- * two lines earlier is how an off-by-one gets in, and the symptom would be "Open shows the wrong picture",
- * which reads as a broken link rather than an index bug.
- *
- * ⚠️ **ONE-BASED IN THE NAME, ZERO-BASED IN THE URL.** `<id>-3` is what a person reads as "variation 3",
- * and `variation=2` is the studio's `imageIndex`, which is slot space. Both conventions are correct in
- * their own place and the conversion belongs at exactly one boundary, which is this one.
- *
- * ⚠️ A single-output generation gets NO `variation`. There is no variation to name, and passing 0 would
- * imply there was a choice.
- */
-/** Where a deep link points when no client base url was threaded through. */
-export const DEFAULT_APP_URL = 'https://app.contenthero.ai';
-export function studioUrlFor(baseUrl, outputId, index, total) {
-    const root = baseUrl.replace(/\/+$/, '');
-    /**
-     * ⭐⭐⭐ **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 mediaWidgetData({
-        outputId: gen.outputId,
-        contentType: gen.contentType,
-        modelId: gen.modelId,
-        modelDisplayName: gen.modelDisplayName,
-        modelBrandColor: gen.modelBrandColor,
-        modelIconKey: gen.modelIconKey,
-        /**
-         * ⭐ 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.
-         */
-        displayAspect: gen.displayAspect,
-        prompt: gen.prompt,
-        items: urls.map((url, i) => ({
-            url,
-            posterUrl: posterUrls[i] ?? null,
-            name: `${gen.outputId}${urls.length > 1 ? `-${i + 1}` : ''}`,
-            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. */
-baseUrl) {
-    const urls = gen.outputUrls ?? [];
-    const noun = urls.length === 1 ? gen.contentType : `${gen.contentType}s`;
-    /**
-     * ⭐⭐ **ONE TEXT LIST, AND NO `resource_link` BLOCKS. THREE REPRESENTATIONS OF ONE URL WAS TWO TOO MANY.**
-     *
-     * This went through both extremes before landing here. Listing the urls in prose AND attaching a link per
-     * output printed every url twice. Suppressing the prose left the links alone, and a host renders those as
-     * `name: uri` with NO SEPARATOR BETWEEN THEM, so url 1 ended flush against filename 2 and anything
-     * splitting on whitespace read a corrupted token. Measured at all three boundaries of a four-image batch.
-     *
-     * ⛔ THE SEPARATOR WAS NEVER OURS TO ADD. Our text block ends with a newline; the run-together is the host
-     * concatenating sibling blocks, and no content we emit can put a break between two of them.
-     *
-     * ⭐ So the fallback is the thing we fully control: one newline-delimited list. The widget is the surface
-     * that renders, and this is what a host without app support (or a model reading the transcript) gets. It
-     * costs less than the links did and it cannot be run together by anybody.
-     */
-    /**
-     * ⭐ **THE ID IS AN ACCEPTABLE FALLBACK HERE AND NOWHERE ELSE.** This block's reader is the model, for
-     * whom `gpt-image-2` is a true and directly useful token. The widget's chip has a human reader, for whom
-     * the same string is an unexplained failure wearing a label's clothes, so there it renders as nothing.
-     */
-    const header = `Done. ${urls.length} ${noun} from ${gen.modelDisplayName ?? gen.modelId} (outputId ${gen.outputId}):`;
-    const lines = [header, ...urls.map((u, i) => `${i + 1}. ${u}`)];
-    const p = gen.placement;
-    if (p) {
-        if (p.surface === 'canvas') {
-            lines.push(`Placed as a canvas layer (id ${p.layerId ?? p.itemId ?? 'resolved'}) on slide ${p.slideId ?? 'resolved'}. Use that layer id to chain further ops (animate, reposition, reorder, set as background).`);
-        }
-        else {
-            lines.push(`Placed on the timeline (clip id ${p.itemId ?? 'resolved'}). Use that clip id to chain further ops.`);
-        }
-        if (p.warnings?.length)
-            lines.push(`Placement notes: ${p.warnings.join('; ')}`);
-    }
-    // ⚠️ A TRAILING NEWLINE, because a host concatenates blocks without inserting one. Without it the last
-    // url ran straight into the next block's rendering, producing `...MBCo_Kkcfe3bafb-...-1.png: https://...`
-    // and a token that anything splitting on whitespace would read as part of the filename.
-    const content = [{ type: 'text', text: lines.join('\n') + '\n' }];
-    for (const a of attachments) {
-        if (a.kind === 'bytes') {
-            content.push({ type: a.type, data: a.data, mimeType: a.mimeType });
-        }
-        else {
-            // A `resource_link` names the bytes without carrying them. The uri is a capability url, so it does not
-            // expire and appended query parameters cannot invalidate it.
-            content.push({ type: 'resource_link', uri: a.uri, name: a.name, mimeType: a.mimeType });
-        }
-    }
-    /**
-     * ⭐⭐⭐ **THE `_meta` KEY IS WHAT MAKES A WIDGET APPEAR.** Without it the host has an HTML resource it was
-     * never told to mount, and the result renders as blocks alone. With it, a host that supports MCP Apps
-     * shows the widget and a host that does not ignores the key entirely.
-     *
-     * ⚠️ Emitted ALONGSIDE the blocks, never instead of them. Two mechanisms, one of which is better where it
-     * exists: ChatGPT and Claude get the widget, anything else still gets an image it can draw.
-     */
-    return {
-        content,
-        isError: false,
-        structuredContent: generationWidgetData(gen, posterUrls, baseUrl),
-        _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
-    };
-}
-/** Suggested seconds to wait before re-polling a job, by content type. */
-export function pollAfterSecondsFor(contentType) {
-    return contentType === 'image' ? 5 : 15;
-}
-/**
- * How to call `get_generation_status`, written as the call itself.
- *
- * ⚠️ THE ARGUMENT IS `outputIds` AND IT IS AN ARRAY, ALWAYS, even for one job. Every handoff here used to
- * say "call get_generation_status with this outputId", which names a parameter that does not exist: an agent
- * following the sentence literally sends `{ outputId }` and the schema rejects it. Naming the shape in prose
- * is what drifted, so these messages now print the call instead, and every site shares this one function.
- */
-export function getStatusCall(outputIds) {
-    return `get_generation_status { outputIds: [${outputIds.map((id) => `"${id}"`).join(', ')}] }`;
-}
-/**
- * A slow job that did not finish within the smart-wait window.
- *
- * ## ⭐⭐⭐ THIS IS WHERE THE SKELETONS COME FROM, AND WHY IT IS THE ONLY PLACE THEY COULD
- *
- * A generation returns one of two ways: it finished inside the smart wait, in which case there is nothing
- * to show a spinner for, or it did not, and until now that produced ONE SENTENCE of prose asking the agent
- * to poll. Every video takes that path. So the person who waited longest got the least: a paragraph, while
- * the same job in the studio shows placeholder cards filling in.
- *
- * ⛔ **THE FIX IS NOT TO MAKE `generate_*` RETURN EARLY.** That would hand every host the pending path,
- * including hosts with no MCP Apps support, which would lose the inline image they get today. The pending
- * path already exists and already reaches exactly the people who are waiting.
- *
- * ⚠️ **THE TEXT STAYS, WORD FOR WORD.** It is what a host without app support renders, and it is what the
- * AGENT reads to know it must poll. The widget is added ALONGSIDE it, not instead of it: an agent that
- * stopped polling because the prose was replaced by a payload it cannot see would leave the generation
- * unclaimed.
- *
- * ⚠️ No model NAME here, and that is deliberate. Resolving one would mean a second network call from
- * inside a `catch`, which is the exact shape that produced a chip flickering between kebab case and title
- * case. The widget polls `get_generation_status`, and the name arrives with the first response.
- */
-export function pendingResult(outputId, pollAfterSeconds = 15, shape) {
-    /**
-     * ⚠️ 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 {
-        content: [{ type: 'text', text: prose }],
-        structuredContent: {
-            outputId,
-            status: 'processing',
-            contentType: shape.contentType,
-            modelId: shape.modelId,
-            modelName: null,
-            modelBrandColor: null,
-            modelIconKey: null,
-            displayAspect: shape.displayAspect ?? null,
-            prompt: null,
-            /** 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,
-            items: [],
-        },
-        _meta: { [RESOURCE_URI_META_KEY]: GENERATION_WIDGET_URI, ui: { resourceUri: GENERATION_WIDGET_URI } },
-    };
-}
-/** Synchronous audio result (already complete on submit). */
-/**
- * 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}):`;
-    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.
- *
- * Reporting only the first would let an agent see one recording finish and call the whole edit done, while the
- * other recordings were still running. The applied-automatically note matters too: unlike every other async
- * tool here, the caller does NOT place the result, so without saying so an agent would reasonably try to.
- */
-export function enhanceClipsResult(result) {
-    const jobs = result.outputs ?? [];
-    if (jobs.length === 0) {
-        return text(result.note ?? 'Nothing to enhance: no audible clips in that selection.');
-    }
-    const lines = jobs.map((j, i) => `${i + 1}. outputId ${j.outputId} covers ${j.clipIds.length} clip${j.clipIds.length === 1 ? '' : 's'}` +
-        ` from one source (${j.windows} window${j.windows === 1 ? '' : 's'})`);
-    const poll = `Poll with ${getStatusCall(jobs.map((j) => j.outputId))}`;
-    const header = jobs.length === 1
-        ? `Enhancing 1 source. ${poll}:`
-        : `Enhancing ${jobs.length} sources as separate jobs, because a noise profile is estimated per recording. ${poll} (EVERY id, in one call):`;
-    const footer = [
-        'The enhanced audio is applied to the clips automatically when each job lands, so no placement call is needed.',
-        result.silencedClipsExcluded
-            ? `${result.silencedClipsExcluded} silenced clip${result.silencedClipsExcluded === 1 ? ' was' : 's were'} skipped.`
-            : null,
-    ].filter(Boolean);
-    return text([header, ...lines, ...footer].join('\n'));
-}
-/** Result of a get_cost preflight: the estimate, with nothing generated or charged. */
-export function costResult(est) {
-    const what = est.modelId ?? est.contentType ?? 'this generation';
-    const credits = `${est.creditsEstimate} credit${est.creditsEstimate === 1 ? '' : 's'}`;
-    return text(`Estimated cost: ${credits} for ${what}. No generation ran and nothing was charged.`);
-}
-/**
- * One generation's status. Used directly for a single id, and per-row by the batch form below.
- *
- * ⭐ A STILL-RUNNING GENERATION REPORTS THE URLS IT ALREADY HAS. `outputUrls` fills in slot by slot,
- * so a 4-image batch can have three finished assets while `status` is still 'processing'. Reporting
- * only "still processing" threw those away and made every caller block on the SLOWEST slot, even
- * though the finished ones are already visible in the app's own grid. The caller can start reviewing
- * immediately and re-poll only for the remainder.
- *
- * ⚠️ THE PARTIAL LIST IS NOT A FINAL ONE, so it never uses `completedResult`'s "Done." header. A
- * caller that stopped at a partial result believing it was complete would silently lose images,
- * which is the failure this is meant to prevent, not cause.
- */
-export function generationStatusResult(gen, attachments = [], baseUrl) {
-    /**
-     * ⛔⛔ **THIS DROPPED THE ATTACHMENTS AND THEREFORE RENDERED NOTHING.** It called `completedResult(gen)`
-     * with no second argument, so POLLING returned text alone even after the generate handlers started
-     * attaching blocks. That is the path EVERY async generation takes, which is every video, so the common
-     * case stayed blank while the synchronous one worked.
-     *
-     * ⭐ 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') {
-        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);
-    }
-    const secs = pollAfterSecondsFor(gen.contentType);
-    const ready = gen.outputUrls ?? [];
-    const poll = `Call get_generation_status again in ~${secs}s [poll_after_seconds: ${secs}]`;
-    if (ready.length === 0) {
-        return text(`Generation ${gen.outputId} is still ${gen.status}. ${poll}.`);
-    }
-    const noun = ready.length === 1 ? gen.contentType : `${gen.contentType}s`;
-    return text([
-        `Partial. ${ready.length} ${noun} ready from ${gen.modelId} (outputId ${gen.outputId}), more still ${gen.status}:`,
-        ...ready.map((u, i) => `${i + 1}. ${u}`),
-        `NOT the full set. ${poll} for the rest.`,
-    ].join('\n'));
-}
-/** One or more generations (snapshot or post-wait). Falls through to the single form for one id. */
-export function generationBatchResult(gens, attachmentsByOutputId = {}, baseUrl) {
-    // ⚠️ ONLY THE SINGLE FORM ATTACHES. A batch status covering ten generations would embed ten sets of
-    // bytes into one result, which is the context blow-up the link design was originally protecting against.
-    // The single form is what a caller polling one generation hits, and that is the case worth rendering.
-    if (gens.length === 1)
-        return generationStatusResult(gens[0], attachmentsByOutputId[gens[0].outputId] ?? [], baseUrl);
-    const rows = gens.map((gen) => {
-        if (gen.status === 'completed') {
-            const urls = gen.outputUrls ?? [];
-            return `- ${gen.outputId}: completed | ${urls.join(', ') || '(no urls)'}`;
-        }
-        if (gen.status === 'failed') {
-            return `- ${gen.outputId}: failed | ${gen.error ?? 'unknown error'}`;
-        }
-        const secs = pollAfterSecondsFor(gen.contentType);
-        // Same rule as the single form: surface the slots that already landed rather than making the
-        // caller block on the slowest one. The count says the set is incomplete, so a row can never be
-        // mistaken for a finished generation.
-        const ready = gen.outputUrls ?? [];
-        if (ready.length > 0) {
-            return `- ${gen.outputId}: ${gen.status}, ${ready.length} ready so far | ${ready.join(', ')} [poll_after_seconds: ${secs}]`;
-        }
-        return `- ${gen.outputId}: ${gen.status} [poll_after_seconds: ${secs}]`;
-    });
-    return text([`${gens.length} generation(s):`, ...rows].join('\n'));
-}
-/** A finished transcription: header line plus the transcript body. */
-export function transcriptResult(t) {
-    const lang = t.language ? ` (${t.language})` : '';
-    const cost = t.creditsUsed > 0 ? `, ${t.creditsUsed} credits` : '';
-    const header = `Transcript${lang}, ${t.wordCount} words${cost} (outputId ${t.outputId}):`;
-    return text([header, '', t.transcript].join('\n'));
-}
-/** Join the non-empty lines (drops null/empty entries). */
-function lines(parts) {
-    return parts.filter((p) => !!p).join('\n');
-}
-/** List of avatars, each with the fields an agent needs to drive lip-sync. */
-export function avatarListResult(avatars) {
-    if (!avatars.length) {
-        return text('No avatars found. Create one in the ContentHero app first.');
-    }
-    const rows = avatars.map((a) => `- ${a.name} (id ${a.id})${a.isDefault ? ' [default]' : ''} | image: ${a.imageUrl ?? 'none'} | voice: ${a.defaultVoiceId ?? 'none'}`);
-    return text([`${avatars.length} avatar(s):`, ...rows].join('\n'));
-}
-/** One avatar's full detail, including its looks. */
-export function avatarResult(a) {
-    const traits = [a.gender, a.age, a.ethnicity].filter(Boolean).join(', ');
-    return text(lines([
-        `${a.name} (id ${a.id})${a.isDefault ? ' [default]' : ''}`,
-        `image (base look, use as imageUrl for generate_lip_sync): ${a.imageUrl ?? 'none'}`,
-        `default voice (use as voiceId): ${a.defaultVoiceId ?? 'none'}`,
-        a.description ? `description: ${a.description}` : null,
-        traits ? `traits: ${traits}` : null,
-        a.niche.length ? `niche: ${a.niche.join(', ')}` : null,
-        a.looks.length ? `looks (${a.looks.length}):` : 'looks: none',
-        ...a.looks.map((l) => `  - ${l.name ?? l.lookType ?? 'look'} (id ${l.id})${l.isDefault ? ' [default]' : ''}${l.isFavorited ? ' [favorite]' : ''}${l.isArchived ? ' [archived]' : ''}: ${l.imageUrl ?? 'none'}`),
-    ]));
-}
-/**
- * A just-created avatar, which is NOT READY.
- *
- * ⚠️ THE POINT OF A SEPARATE FORMATTER IS THE WAIT. `avatarResult` describes a finished avatar, and
- * using it here would show an avatar with `image: none` and no looks, which reads as "created, and
- * empty" rather than "created, and still generating". A model that reads it that way goes on to
- * generate a look into an avatar whose own first look is still in flight, or reports success to the
- * user for something they cannot yet see.
- *
- * Says the poll call explicitly, the same way `pendingResult` does for a generation.
- */
-export function avatarPendingResult(created) {
-    const a = created.avatar;
-    return text(lines([
-        `Created "${a.name}" (id ${a.id}).`,
-        '',
-        `⚠️ NOT READY YET: status is ${created.status}. The avatar has no image until its first look`,
-        'finishes generating, which is also when its default look and profile photo are set.',
-        `Poll with: get_avatar { "avatarId": "${a.id}" } until status is "completed" (usually 1-4 minutes).`,
-        '',
-        'Credits are charged when that look completes, not now, so a failed generation is not charged.',
-    ]));
-}
-/** List of saved voices. */
-export function voiceListResult(voices) {
-    if (!voices.length)
-        return text('No saved voices found.');
-    const rows = voices.map((v) => `- ${v.name ?? '(unnamed)'} (voiceId ${v.voiceId})${v.isFavorited ? ' [favorite]' : ''}${v.previewUrl ? ` | preview: ${v.previewUrl}` : ''}`);
-    return text([`${voices.length} voice(s):`, ...rows].join('\n'));
-}
-/** One voice's full detail. */
-export function voiceResult(v) {
-    const traits = [v.gender, v.age, v.accent, v.language].filter(Boolean).join(', ');
-    return text(lines([
-        `${v.name ?? '(unnamed)'} (voiceId ${v.voiceId})${v.isFavorited ? ' [favorite]' : ''}`,
-        v.provider ? `provider: ${v.provider}` : null,
-        traits ? `traits: ${traits}` : null,
-        v.description ? `description: ${v.description}` : null,
-        v.useCase ? `use case: ${v.useCase}` : null,
-        v.previewUrl ? `preview: ${v.previewUrl}` : null,
-    ]));
-}
-/** List of brand kits. */
-export function brandKitListResult(kits) {
-    if (!kits.length)
-        return text('No brand kits found. Create one in the ContentHero app first.');
-    const rows = kits.map((k) => `- ${k.name}${k.businessName && k.businessName !== k.name ? ` (${k.businessName})` : ''} (id ${k.id})${k.isDefault ? ' [default]' : ''}${k.nicheDefinition ? ` | niche: ${k.nicheDefinition}` : ''}`);
-    return text([`${kits.length} brand kit(s):`, ...rows].join('\n'));
-}
-/**
- * One brand kit in full. The kit is deeply structured (visual identity, voice,
- * curated sections, linked accounts, knowledge), so return a short header plus
- * the whole object as JSON: faithful and complete, and an agent reads it cleanly.
- */
-export function brandKitResult(kit, extraction) {
-    const header = `Brand kit "${kit.name}"${kit.isDefault ? ' [default]' : ''} (id ${kit.id}):`;
-    // Stated in words, not just left in the JSON, because the caller has to know the kit it just got back is
-    // still FILLING IN. Without this line an agent reads an almost-empty kit and concludes extraction failed.
-    const note = extraction && extraction.status !== 'unconfigured'
-        ? extraction.status === 'deduped'
-            ? 'Extraction was ALREADY RUNNING for this kit, so nothing new was queued. Poll extractionStatus with get_brand_kit.'
-            : 'Extraction STARTED and is still running. The fields below will fill in. Poll extractionStatus with get_brand_kit.'
-        : extraction?.status === 'unconfigured'
-            ? 'Extraction is NOT CONFIGURED on this deployment, so nothing was queued.'
-            : null;
-    return text([header, ...(note ? ['', note] : []), '', JSON.stringify(kit, null, 2)].join('\n'));
-}
-/** A created/updated/archived brand-kit section. */
-export function brandKitSectionResult(s, verb = 'Section') {
-    const fieldCount = Array.isArray(s.fields) ? s.fields.length : 0;
-    return text(`${verb}: "${s.sectionName}" in tab "${s.tab}" (id ${s.id}) | ${fieldCount} field(s).`);
-}
-/** A brand kit that was just archived. */
-export function brandKnowledgeListResult(result) {
-    if (!result.items.length) {
-        return text('No knowledge items in this brand kit yet. Add one with add_brand_knowledge.');
-    }
-    const more = result.hasMore ? ` (showing ${result.items.length} of ${result.total})` : '';
-    const lines = result.items.map((k) => `- ${k.title ?? '(untitled)'} [${k.sourceType ?? 'unknown'}] (id ${k.id})`);
-    return text([`${result.total} knowledge item(s)${more}:`, ...lines].join('\n'));
-}
-export function brandKnowledgeDetailResult(item) {
-    return text([
-        `${item.title ?? '(untitled)'} [${item.sourceType ?? 'unknown'}] (id ${item.id})`,
-        item.sourceUrl ? `Source: ${item.sourceUrl}` : null,
-        '',
-        item.content ?? '(no stored body; use search_brand_knowledge for the full depth)',
-    ]
-        .filter((l) => l !== null)
-        .join('\n'));
-}
-export function brandKnowledgeSearchResult(matches) {
-    if (!matches.length) {
-        return text('No matching knowledge found. Try a broader query or a lower threshold.');
-    }
-    const blocks = matches.map((m, i) => {
-        const score = m.similarity.toFixed(3);
-        const header = `[${i + 1}] ${m.title ?? '(untitled)'} (item ${m.knowledgeId ?? '?'}, score ${score})`;
-        return `${header}\n${m.content}`;
-    });
-    return text([`${matches.length} match(es):`, ...blocks].join('\n\n'));
-}
-export function brandKnowledgeItemResult(item, verb = 'Added') {
-    return text(`${verb} knowledge item: "${item.title ?? '(untitled)'}" [${item.sourceType ?? 'unknown'}] (id ${item.id}).`);
-}
-/**
- * Confirmation of a universal favorite / unfavorite / archive / unarchive action.
- * `target` describes what was acted on: a studio variation slot when
- * variationIndex is set, otherwise a top-level asset by type + id.
- */
-export function statusActionResult(action, target) {
-    const what = target.variationIndex != null
-        ? `variation ${target.variationIndex} of output ${target.id}`
-        : `${target.assetType ?? 'asset'} ${target.id}`;
-    return text(`${action} ${what}.`);
-}
-/** List of library media, one row per VARIATION (the atomic grain). */
-export function mediaListResult(items) {
-    if (!items.length)
-        return text('No media found.');
-    const rows = items.map((m) => {
-        // A studio generation lists as one row per variation; show which slot when it has siblings. The
-        // addressable token for this variation is `<id>-<variant+1>`.
-        const varTag = m.generationSize > 1 ? ` | v${m.variant + 1}/${m.generationSize}` : '';
-        const favTag = m.isFavorited ? ' [favorite]' : '';
-        const promptStr = m.prompt ? ` | ${m.prompt.slice(0, 80)}${m.prompt.length > 80 ? '...' : ''}` : '';
-        const kindTag = m.kind === 'board'
-            ? ` | board${m.boardType ? `:${m.boardType}` : ''}`
-            : m.kind && m.kind !== 'creation'
-                ? ` | ${m.kind}`
-                : '';
-        const nameStr = m.fileName ? ` | ${m.fileName}` : '';
-        const durStr = m.durationSeconds != null ? ` | ${Math.round(m.durationSeconds)}s` : '';
-        // Every item is a single variation carrying its resolved url; surface it inline so the agent can
-        // reference the media directly (e.g. add it to a timeline) without a get call.
-        const urlStr = m.url ? ` | ${m.url}` : '';
-        return `- [${m.type}] ${m.model ?? ''} (id ${m.id})${varTag}${favTag}${kindTag}${nameStr}${durStr} | ${m.status}${promptStr}${urlStr}`;
-    });
-    return text([`${items.length} item(s) (newest first):`, ...rows].join('\n'));
-}
-/** Semantic library-search matches: assets ranked by relevance, with matched scene timestamps for video. */
-export function mediaSearchResult(results) {
-    if (!results.length)
-        return text('No matching media found.');
-    const rows = results.map((r) => {
-        const rel = ` | ${Math.round(r.relevance * 100)}%`;
-        const kindTag = r.kind ? `[${r.kind}]` : '[media]';
-        const summaryStr = r.summary ? ` | ${r.summary.slice(0, 90)}${r.summary.length > 90 ? '...' : ''}` : '';
-        const scenesStr = r.scenes.length
-            ? ` | scenes: ${r.scenes.map((s) => `${(s.startMs / 1000).toFixed(1)}-${(s.endMs / 1000).toFixed(1)}s`).join(', ')}`
-            : '';
-        const urlStr = r.url ? ` | ${r.url}` : '';
-        return `- ${kindTag} (id ${r.id})${rel}${summaryStr}${scenesStr}${urlStr}`;
-    });
-    return text([`${results.length} match(es) (most relevant first):`, ...rows].join('\n'));
-}
-/** The user's folders (their own + the built-in derived folders). */
-export function folderListResult(data) {
-    const own = data.folders.map((f) => `- ${f.name} [${f.type}] (id ${f.id})${f.parentId ? ` | in ${f.parentId}` : ''}`);
-    const derived = data.derived.map((d) => `- ${d.name} (key ${d.key})`);
-    return text([
-        own.length ? `Your folders (${own.length}):` : 'You have no folders yet.',
-        ...own,
-        '',
-        'Built-in folders:',
-        ...derived,
-    ].join('\n'));
-}
-/** One folder's contents (media items + entities). */
-export function folderContentsResult(folder, items) {
-    const header = folder ? `"${folder.name}" - ${items.length} item(s):` : `${items.length} item(s):`;
-    if (!items.length)
-        return text(`${header}\n(empty)`);
-    const rows = items.map((i) => {
-        if (i.type === 'media') {
-            const rel = i.relevance != null ? ` | ${Math.round(i.relevance * 100)}%` : '';
-            const fav = i.isFavorited ? ' [favorite]' : '';
-            const summ = i.summary ? ` | ${i.summary.slice(0, 80)}${i.summary.length > 80 ? '...' : ''}` : '';
-            return `- [${i.kind ?? 'media'}] (${i.sourceTable} ${i.sourceRecordId} v${i.variant})${rel}${fav}${summ}${i.url ? ` | ${i.url}` : ''}`;
-        }
-        return `- [${i.type}] ${i.name} (id ${i.id})${i.subtype ? ` | ${i.subtype}` : ''}`;
-    });
-    return text([header, ...rows].join('\n'));
-}
-/** One studio output's detail, with its variations. */
-export function mediaResult(m) {
-    const specs = [
-        m.aspectRatio ? `aspect ${m.aspectRatio}` : null,
-        m.resolution ? `res ${m.resolution}` : null,
-        m.duration ? `${m.duration}s` : null,
-    ]
-        .filter(Boolean)
-        .join(', ');
-    return text(lines([
-        `${m.type} from ${m.model ?? 'unknown'} (id ${m.id})${m.selectedVariation ? `, variation ${m.selectedVariation}` : ''}`,
-        m.kind && m.kind !== 'creation' ? `kind: ${m.kind}${m.boardType ? ` (${m.boardType})` : ''}` : null,
-        m.prompt ? `prompt: ${m.prompt}` : null,
-        m.script ? `script: ${m.script}` : null,
-        specs || null,
-        `status: ${m.status}${m.creditsUsed != null ? ` | ${m.creditsUsed} credits` : ''}`,
-        `variations (${m.generationSize}):`,
-        ...m.variations.map((v) => `  ${v.variation}. ${v.url ?? `(no url, ${v.status})`}${v.isFavorited ? ' [favorite]' : ''}${v.isArchived ? ' [archived]' : ''}`),
-    ]));
-}
-/** One resolved batch item's metadata line (no image; that is added separately). */
-function batchItemLine(it, index, hasImage) {
-    const label = `[${index + 1}]`;
-    if (!it.ok) {
-        const ref = it.mediaId ?? ('url' in it.input ? it.input.url : JSON.stringify(it.input));
-        return `${label} ERROR (${ref}): ${it.error ?? 'could not resolve'}`;
-    }
-    const idPart = it.mediaId
-        ? `${it.type ?? 'media'} ${it.mediaId}${it.variation != null ? ` v${it.variation}` : ''}`
-        : `${it.type ?? 'media'} (url)`;
-    const others = it.otherVariations.length > 0 ? ` | other variations: ${it.otherVariations.join(', ')}` : '';
-    const model = it.model ? ` from ${it.model}` : '';
-    const prompt = it.prompt ? `\n    prompt: ${it.prompt}` : '';
-    // Explain the absence of an image so the model does not assume it failed.
-    let note = '';
-    if (!hasImage) {
-        if (it.type === 'audio')
-            note = '\n    (audio: no visual; use the url)';
-        else if (it.type === 'video')
-            note = '\n    (video: no still available for this view; use the url)';
-        else if (it.type === 'transcript')
-            note = '\n    (transcript: text only)';
-    }
-    // MEASURED GEOMETRY, when the spine has it. Without these numbers a caller cannot compute an asset's true
-    // aspect (so it stretches it on placement) and cannot align to the VISIBLE artwork of a padded logo at all.
-    // `content` is the artwork's bounds inside the file; when it is smaller than the file, say so explicitly,
-    // because that difference is the whole reason to read it.
-    let geom = '';
-    if (it.geometry) {
-        const { width, height, content } = it.geometry;
-        geom = `\n    dimensions: ${width}x${height}`;
-        if (content) {
-            const trimmed = content.width < width || content.height < height;
-            geom += trimmed
-                ? ` | artwork: ${content.width}x${content.height} at (${content.x}, ${content.y}) -- the rest is transparent margin, so place and align by THIS box, not the file`
-                : ' | artwork fills the frame';
-        }
-    }
-    // MEASURED DURATION, for anything time-based. Reported for AUDIO too, which is the point: audio has no
-    // dimensions, so it carried no measured facts at all, and `edit_audio` requires a durationSeconds to price
-    // the job. The only way to call it correctly was to download the file and probe it.
-    const dur = it.durationSeconds != null ? `\n    duration: ${it.durationSeconds.toFixed(2)}s` : '';
-    return `${label} ${idPart}${model}${others}\n    ${it.url}${geom}${dur}${prompt}${note}`;
-}
-/**
- * A vision-enabled media batch (get_media). Returns a text summary + one metadata
- * line per item, and, for each image item whose bytes were fetched, an IMAGE
- * content block so the calling model can SEE it. Images arrive as a parallel
- * 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.
- */
-/**
- * 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);
-    const shownImages = images.filter(Boolean).length + keyframeCount;
-    const summary = `Resolved ${okCount}/${items.length} media item(s); ${shownImages} image(s) attached below` +
-        (keyframeCount > 0 ? ` (incl. ${keyframeCount} video keyframe(s))` : '') +
-        `.\n\n` +
-        items.map((it, i) => batchItemLine(it, i, Boolean(images[i]) || (it.keyframes?.length ?? 0) > 0)).join('\n');
-    const content = [{ type: 'text', text: summary }];
-    items.forEach((it, i) => {
-        const img = images[i];
-        if (img) {
-            content.push({ type: 'text', text: `Image for item [${i + 1}]:` });
-            content.push({ type: 'image', data: img.data, mimeType: img.mimeType });
-        }
-        const keyframes = it.keyframes ?? [];
-        if (keyframes.length > 0) {
-            content.push({ type: 'text', text: `${keyframes.length} keyframe(s) for item [${i + 1}] (raw footage, in order):` });
-            for (const kf of keyframes) {
-                const parsed = parseDataUrl(kf.dataUrl);
-                if (parsed)
-                    content.push({ type: 'image', data: parsed.data, mimeType: parsed.mimeType });
-            }
-        }
-    });
-    /**
-     * ⭐ 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) {
-    // The headers are listed EXPLICITLY rather than described, because this instruction is executed by an agent
-    // and "with the file's Content-Type" was about to become wrong. Object storage is moving to R2, where the
-    // presigned URL signs the owner in as `x-amz-meta-user_id`; a PUT missing it is refused with
-    // SignatureDoesNotMatch (verified: 403 with Content-Type alone, 200 with both). Telling the caller which
-    // headers to send, from the server's own answer, means the migration needs no change here at all.
-    const headers = r.uploadHeaders ?? { 'Content-Type': 'the file MIME type' };
-    return text(lines([
-        `Upload created (id ${r.outputId}). Two steps remain:`,
-        `1. PUT the file bytes to this URL (expires ${r.expiresAt}):`,
-        `   ${r.uploadUrl}`,
-        '   Send EXACTLY these headers, unchanged:',
-        ...Object.entries(headers).map(([k, v]) => `     ${k}: ${v}`),
-        `2. Call complete_media_upload(outputId: "${r.outputId}") to finalize.`,
-        'Once complete, reference the media by its outputId in generations or post assets.',
-    ]));
-}
-/** A finalized upload or import: a first-class media output. */
-/**
- * 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.
- *
- * ## Why a duplicate gets its own sentence rather than the same one
- *
- * An import of bytes the account already holds is a successful no-op. Reporting it as "Media ready" would
- * be a lie an agent then acts on: it would try to reference an `outputId` that is null, or import again on
- * the next run because nothing said it had already happened.
- *
- * The two duplicate cases differ in what the caller can DO next, so they read differently:
- *
- *   an existing library item -> there is an id to use, so give it
- *   no library item          -> the bytes are an export or a look; there is no id, so say what it IS
- *
- * 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, baseUrl = DEFAULT_APP_URL) {
-    if (!r.alreadyExisted) {
-        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.`);
-    }
-    const what = r.existing?.role ? `a ${r.existing.role}` : 'an existing file';
-    return text(`You already have this file. Nothing was imported: these exact bytes are already in your account as ${what}` +
-        `${r.existing?.objectName ? ` (${r.existing.objectName})` : ''}. ` +
-        `It is not a library item, so there is no outputId to reference. Use its URL directly: ${r.url}`);
-}
-export function balanceResult(b) {
-    return text(`Balance: ${b.balance} credits (tier: ${b.tier}, auto top-up: ${b.autoTopupEnabled ? 'on' : 'off'}).`);
-}
-// -- reference elements (named reference library) -----------------------------
-/** List of the account's saved reference elements. */
-export function elementListResult(items) {
-    if (!items.length) {
-        return text('No reference elements. Create one with create_element, then reference it in a Kling generation by elementId.');
-    }
-    const rows = items.map((e) => {
-        const media = e.input_video_url ? '1 video' : `${e.input_urls.length} image(s)`;
-        return `- ${e.name} (id ${e.id}) | ${e.category} | ${media}${e.description ? ` | ${e.description.slice(0, 60)}` : ''}`;
-    });
-    return text([`${items.length} element(s):`, ...rows].join('\n'));
-}
-/** Confirmation that an element was deleted. */
-export function elementDeletedResult(id) {
-    return text(`Deleted element ${id}.`);
-}
-/** One saved reference element. */
-export function elementResult(e, verb) {
-    if (verb) {
-        return text(`${verb} element "${e.name}" (id ${e.id}, ${e.category}). Reference it in a Kling generation via references.elements [{ elementId: "${e.id}" }] and @${e.name} in the prompt.`);
-    }
-    return text(lines([
-        `${e.name} (id ${e.id}) | ${e.category}`,
-        e.description ? `description: ${e.description}` : null,
-        e.input_video_url ? `video: ${e.input_video_url}` : `images (${e.input_urls.length}): ${e.input_urls.join(', ')}`,
-        `Reference in a Kling prompt as @${e.name}; pass references.elements [{ elementId: "${e.id}" }].`,
-    ]));
-}
-// -- models (discovery catalog) -----------------------------------------------
-/** Read a possibly-absent capability field from the loosely-typed bag. */
-function cap(m, key) {
-    return m.capabilities[key];
-}
-/** Human duration spec, e.g. "5s|10s", "4-12s", "8s", or null when not applicable. */
-function durationSummary(d) {
-    if (!d || d.mode === 'none')
-        return null;
-    if (d.mode === 'locked')
-        return `${d.value}s`;
-    if (d.mode === 'discrete')
-        return Array.isArray(d.options) ? `${d.options.join('s|')}s` : null;
-    if (d.mode === 'range')
-        return `${d.min}-${d.max}s`;
-    return null;
-}
-/** Compact, decision-relevant capability summary for the list view. */
-function capabilitySummary(m) {
-    const parts = [];
-    const inputs = cap(m, 'inputTypes');
-    if (Array.isArray(inputs) && inputs.length)
-        parts.push(`inputs:${inputs.join('+')}`);
-    const dur = durationSummary(cap(m, 'duration'));
-    if (dur)
-        parts.push(`dur:${dur}`);
-    const res = cap(m, 'resolution')?.supported;
-    if (Array.isArray(res) && res.length)
-        parts.push(`res:${res.join('/')}`);
-    const ar = cap(m, 'aspectRatio')?.supported;
-    if (Array.isArray(ar) && ar.length)
-        parts.push(`ar:${ar.join('/')}`);
-    if (cap(m, 'audio')?.supported)
-        parts.push('audio');
-    const refMax = Math.max(cap(m, 'maxImageRefs') ?? 0, cap(m, 'maxVideoRefs') ?? 0, cap(m, 'maxAudioRefs') ?? 0);
-    if (refMax > 0)
-        parts.push(`refs:≤${refMax}`);
-    return parts.join(' | ');
-}
-/** List of models in the discovery catalog. */
-export function modelListResult(models) {
-    if (!models.length)
-        return text('No models found.');
-    const rows = models.map((m) => {
-        const summary = capabilitySummary(m);
-        const def = m.isDefault ? ' [default]' : '';
-        return `- [${m.contentType}] ${m.modelId} (${m.displayName})${def} | ${m.kind}${summary ? ` | ${summary}` : ''}`;
-    });
-    return text([
-        `${models.length} model(s). Call get_model(modelId) for the full request shape before generating:`,
-        ...rows,
-    ].join('\n'));
-}
-/** One model's full request shape (the grounding view). */
-export function modelResult(m) {
-    const res = cap(m, 'resolution');
-    const ar = cap(m, 'aspectRatio');
-    const dur = cap(m, 'duration');
-    const gen = cap(m, 'generations');
-    const audio = cap(m, 'audio');
-    const features = cap(m, 'features');
-    const enabledFeatures = features ? Object.keys(features).filter((k) => features[k]) : [];
-    const refLines = [
-        cap(m, 'maxImageRefs') ? `image refs: up to ${cap(m, 'maxImageRefs')}` : null,
-        cap(m, 'maxVideoRefs') ? `video refs: up to ${cap(m, 'maxVideoRefs')}` : null,
-        cap(m, 'maxAudioRefs') ? `audio refs: up to ${cap(m, 'maxAudioRefs')}` : null,
-    ].filter(Boolean);
-    return text(lines([
-        `${m.modelId} (${m.displayName})${m.isDefault ? ' [default]' : ''}`,
-        `type: ${m.contentType} | operation: ${m.kind}`,
-        m.description ? `description: ${m.description}` : null,
-        m.tags.length ? `tags: ${m.tags.join(', ')}` : null,
-        '',
-        'Request shape:',
-        `  prompt: ${cap(m, 'promptMode') ?? 'optional'}${cap(m, 'promptMaxChars') ? ` (max ${cap(m, 'promptMaxChars')} chars)` : ''}`,
-        Array.isArray(cap(m, 'inputTypes')) && cap(m, 'inputTypes').length
-            ? `  input types: ${cap(m, 'inputTypes').join(', ')}`
-            : null,
-        res?.supported?.length
-            ? `  resolution: ${res.supported.join(', ')}${res.default ? ` (default ${res.default})` : ''}`
-            : null,
-        ar?.supported?.length
-            ? `  aspect ratio: ${ar.supported.join(', ')}${ar.default ? ` (default ${ar.default})` : ''}`
-            : null,
-        durationSummary(dur) ? `  duration: ${durationSummary(dur)}${dur?.default ? ` (default ${dur.default}s)` : ''}` : null,
-        audio?.supported ? `  audio: supported${audio.alwaysOn ? ' (always on)' : ''}` : null,
-        cap(m, 'negativePrompt') ? '  negativePrompt: supported' : null,
-        gen ? `  generations: ${gen.min}-${gen.max} (default ${gen.default})` : null,
-        ...refLines.map((l) => `  ${l}`),
-        enabledFeatures.length ? `  features: ${enabledFeatures.join(', ')}` : null,
-        ...promptReferenceLines(m.promptReferences),
-        '',
-        "Build the request within this shape, preview cost with the matching generate tool's getCost option, then run it.",
-    ]));
-}
-export function platformListResult(platforms) {
-    if (!platforms.length)
-        return text('No publish platforms found.');
-    const rows = platforms.map((p) => {
-        const fmts = p.formats.map((f) => f.value).join(', ');
-        return `- ${p.platform} (${p.name})${p.connected ? ' [connected]' : ''} | formats: ${fmts || 'post'}`;
-    });
-    return text([
-        `${platforms.length} publish platform(s). Call get_platform(platform[, format]) for the exact fields, options, and limits a post requires:`,
-        ...rows,
-    ].join('\n'));
-}
-export function platformResult(p) {
-    const fmtBlocks = p.formats.map((fmt) => {
-        const fields = Object.keys(p.fieldTemplatesByFormat[fmt] ?? {});
-        return `  ${fmt}: ${fields.length ? fields.join(', ') : '(no fields)'}`;
-    });
-    const enumLines = Object.entries(p.enums).map(([k, vals]) => {
-        const rendered = vals
-            .map((v) => (v && typeof v === 'object' && 'id' in v ? String(v.id) : String(v)))
-            .join(', ');
-        return `  ${k}: ${rendered}`;
-    });
-    const limitLines = p.characterLimits
-        ? Object.entries(p.characterLimits).map(([k, n]) => `  ${k}: ${n}`)
-        : [];
-    return text(lines([
-        `${p.platform} (${p.name})`,
-        `formats: ${p.formats.join(', ')}`,
-        `posting modes: ${p.postingModes.join(', ')}`,
-        '',
-        'Fields by format (set these as platformSettings on a post in update_card):',
-        ...fmtBlocks,
-        enumLines.length ? '' : null,
-        enumLines.length ? 'Allowed option values:' : null,
-        ...enumLines,
-        limitLines.length ? '' : null,
-        limitLines.length ? 'Character limits:' : null,
-        ...limitLines,
-        '',
-        'Fill platformSettings to this shape, then attach it as a post with update_card.',
-    ]));
-}
-/** Render the reference-addressing guidance (how to tag references in the prompt). */
-function promptReferenceLines(pr) {
-    if (!pr || pr.scheme === 'none')
-        return [];
-    const tokens = pr.inputs
-        .filter((i) => i.token)
-        .map((i) => `${i.token}${i.max > 1 ? ` (up to ${i.max})` : ''}`)
-        .join(', ');
-    return [
-        '',
-        `Referencing (${pr.scheme}${pr.honored ? ', bound' : ', positional'}):`,
-        `  ${pr.instruction}`,
-        tokens ? `  tokens: ${tokens}` : null,
-    ];
-}
-// -- posts (content pipeline) -------------------------------------------------
-/** One line summarizing a post. */
-function cardLine(p) {
-    const where = p.platforms.length ? p.platforms.join('+') : (p.platform ?? 'general');
-    const when = p.publishedAt
-        ? ` | published ${p.publishedAt}`
-        : p.scheduledAt
-            ? ` | scheduled ${p.scheduledAt}`
-            : '';
-    // `[archived]` rather than a status. The list excludes archived cards unless asked for, so when one
-    // appears here the agent asked for it and the flag confirms the filter did what it said.
-    return `- ${p.title || '(untitled)'} (id ${p.id})${p.isArchived ? ' [archived]' : ''} | ${where}${when}`;
-}
-/** List of posts with pagination context. */
-export function cardListResult(result) {
-    /**
-     * ⭐⭐⭐ NAME THE SCOPE, INCLUDING WHEN THE LIST IS EMPTY.
-     *
-     * This read covers ONE space and falls back to the default when none is named, so "No cards found" and
-     * "9 card(s)" are both answers about a board the caller may not have meant. Measured 2026-09-14: a call
-     * passing `space_id`, where the tool declares `spaceId`, had the key dropped, listed the default space,
-     * and read as proof that the tool ignored its filters.
-     *
-     * ⚠️ THE EMPTY CASE IS THE ONE THAT MATTERS MOST. A wrong-scope list of cards at least looks unfamiliar;
-     * a wrong-scope EMPTY list looks like the thing you asked for does not exist.
-     */
-    const where = result.space ? ` in ${result.space.name}` : '';
-    if (!result.cards.length)
-        return text(`No cards found${where}.`);
-    const more = result.hasMore ? ` (showing ${result.cards.length} of ${result.total}; raise limit/offset for more)` : '';
-    return text([`${result.total} card(s)${where}${more}:`, ...result.cards.map(cardLine)].join('\n'));
-}
-/**
- * A single post summary line (create / update / schedule / archive results).
- *
- * ⚠️ THIS USED TO PRINT `p.status`, AND A CARD NO LONGER HAS ONE. The field was almost always `draft`
- * regardless of the card's real state, so it told the agent nothing while looking like it did. What it
- * prints now is what is true: where the card sits, when it publishes, and whether it is archived.
- *
- * ⭐ ARCHIVE IS SHOWN ONLY WHEN TRUE. A live card saying "not archived" is noise on every line, and
- * `spaceListResult` below already made this call for spaces.
- */
-export function postSummaryResult(p, prefix = 'Post') {
-    const stage = p.stageId ? ` | stage ${p.stageId}` : '';
-    // The schedule is surfaced here because scheduling is now part of update_card rather than its own tool.
-    // Without it a caller who just set a publish time gets no confirmation of what time was actually stored.
-    const scheduled = p.scheduledAt ? ` | Scheduled: ${p.scheduledAt}` : '';
-    const archived = p.isArchived ? ' | ARCHIVED' : '';
-    return text(`${prefix}: ${p.title || '(untitled)'} (id ${p.id})${stage}${scheduled}${archived}`);
-}
-/** One card in full, with its posts and assets. */
-export function cardResult(p) {
-    return text(lines([
-        `${p.title || '(untitled)'} (id ${p.id}) | platform: ${p.platform ?? 'general'}`,
-        p.stageId ? `stage: ${p.stageId}` : null,
-        // Stated only when archived, and it says WHEN, because "archived" with no date is half a fact.
-        p.archivedAt ? `archived: ${p.archivedAt}` : null,
-        p.scheduledAt ? `scheduled: ${p.scheduledAt}` : null,
-        p.publishedAt ? `published: ${p.publishedAt}` : null,
-        p.publishUrl ? `publish url: ${p.publishUrl}` : null,
-        p.notes ? `notes: ${p.notes}` : null,
-        /**
-         * ⭐⭐⭐ **PRINTED UNCONDITIONALLY, INCLUDING AT 0, BECAUSE IT IS AN INPUT TO THE NEXT CALL.**
-         *
-         * Every other line here is omitted when empty, which is right for a fact the agent merely reads.
-         * This one is a TOKEN the agent has to hand back: `update_card` refuses a `notes` write that does
-         * not carry the revision it read. Hiding it at 0 would make a never-edited card the single case
-         * where the agent has nothing to send, and 0 is a real revision, not an absence.
-         */
-        `revision: ${p.revision} (pass as expectedRevision to write notes)`,
-        p.tags?.length ? `tags: ${p.tags.join(', ')}` : null,
-        `posts (${p.posts.length}):`,
-        ...p.posts.map((d) => {
-            const set = settingsKeys(d.platformSettings);
-            return `  - ${d.platform} (id ${d.id})${d.format ? ` ${d.format}` : ''} | ${d.status ?? 'draft'}${d.connectedAccountId ? ` | account ${d.connectedAccountId}` : ' | no connected account'}${set ? ` | settings: ${set}` : ''}`;
-        }),
-        `assets (${p.assets.length}):`,
-        ...p.assets.map((a) => `  - [${a.assetType ?? '?'}] ${a.assetUrl ?? '(no url)'} (id ${a.id})`),
-    ]));
-}
-/** List of stages (the agent resolves a stage from here before placing a post). */
-/**
- * The account's spaces.
- *
- * The card count is stated on every row because "which board has work on it" is the question an agent
- * asks next, and making it call get_space per row to find out is the N+1 the API already avoids.
- */
-export function spaceListResult(spaces) {
-    if (!spaces.length)
-        return text('No spaces found.');
-    const rows = spaces.map((s) => {
-        const bits = [`id ${s.id}`, `${s.postCount ?? 0} card(s)`];
-        if (s.isFavorite)
-            bits.push('favorite');
-        if (s.archivedAt)
-            bits.push('ARCHIVED');
-        return `- ${s.name} (${bits.join(', ')})`;
-    });
-    return text([`${spaces.length} space(s):`, ...rows].join('\n'));
-}
-/** A deleted space. */
-export function spaceDeletedResult(id) {
-    return text(`Deleted space ${id}. Its stages went with it; the space had to be empty of cards.`);
-}
-/** One space. */
-export function spaceResult(s) {
-    const lines = [
-        `${s.name} (id ${s.id})`,
-        `Cards: ${s.postCount ?? 0}`,
-        `Favorite: ${s.isFavorite ? 'yes' : 'no'}`,
-        s.archivedAt ? `Archived: ${s.archivedAt}` : 'Archived: no',
-        s.coverUrl ? `Cover: ${s.coverUrl}` : 'Cover: none',
-        `Updated: ${s.updatedAt}`,
-    ];
-    return text(lines.join('\n'));
-}
-export function stageListResult(result) {
-    /**
-     * ⭐⭐⭐ NAME THE SCOPE, EMPTY CASE INCLUDED, matching `cardListResult` word for word.
-     *
-     * Stages are per-space and this read falls back to the default space when none is named, so a list of
-     * unfamiliar column names and "No stages found." are both answers about a board the caller may not have
-     * meant. The old signature took a bare `Stage[]` and had nothing to say it with.
-     */
-    const where = result.space ? ` in ${result.space.name}` : '';
-    if (!result.stages.length)
-        return text(`No stages found${where}.`);
-    const rows = result.stages.map((s) => `- ${s.name} (id ${s.id}${s.slug ? `, slug ${s.slug}` : ''})`);
-    return text([`${result.stages.length} stage(s)${where} (in order):`, ...rows].join('\n'));
-}
-/** One created or updated stage. */
-export function stageResult(s, respaced = false) {
-    const lines = [
-        `Stage ${s.name} (id ${s.id})`,
-        s.slug ? `Slug: ${s.slug}` : null,
-        s.color ? `Color: ${s.color}` : null,
-        `Position: ${s.sortOrder}`,
-    ].filter(Boolean);
-    /*
-      ⚠️ SAID OUT LOUD, because it is the one answer the caller cannot derive. A move with no room between
-      two columns renumbers the WHOLE board, so every other stage the agent is holding is stale and a
-      renumbered key looks like any other number.
-    */
-    if (respaced) {
-        lines.push('The whole board was renumbered to make room. Call list_stages again: every other stage position you are holding is now stale.');
-    }
-    return text(lines.join('\n'));
-}
-/** A deleted stage, and the board that is left. */
-export function stageDeletedResult(id, movedCards, stages) {
-    const moved = movedCards > 0
-        ? `${movedCards} ${movedCards === 1 ? 'card' : 'cards'} moved to the target stage.`
-        : 'It held no cards.';
-    const rows = stages.map((s) => `- ${s.name} (id ${s.id})`);
-    return text([`Deleted stage ${id}. ${moved}`, '', `${stages.length} stage(s) remaining:`, ...rows].join('\n'));
-}
-/** The non-empty keys of a post's platformSettings, for a compact summary. */
-function settingsKeys(settings) {
-    if (!settings)
-        return null;
-    const keys = Object.keys(settings).filter((k) => {
-        const v = settings[k];
-        if (v == null)
-            return false;
-        if (Array.isArray(v))
-            return v.length > 0;
-        if (typeof v === 'string')
-            return v.length > 0;
-        return true;
-    });
-    return keys.length ? keys.join(', ') : null;
-}
-/** A created or updated post. */
-export function postResult(d) {
-    const set = settingsKeys(d.platformSettings);
-    return text(`Post: ${d.platform} (id ${d.id})${d.format ? ` ${d.format}` : ''} | ${d.status ?? 'draft'}${d.connectedAccountId ? ` | account ${d.connectedAccountId}` : ' | no connected account (set one before publishing)'}${set ? ` | settings: ${set}` : ' | no settings (set platformSettings to make it publishable)'}.`);
-}
-/** An attached asset. */
-export function assetResult(a) {
-    return text(`Asset attached: [${a.assetType ?? '?'}] ${a.assetUrl ?? '(no url)'} (id ${a.id}).`);
-}
-/** A post's assets in their (new) order. */
-export function assetOrderResult(assets) {
-    if (!assets.length)
-        return text('No assets on this post.');
-    return text([
-        `Assets reordered (${assets.length}):`,
-        ...assets.map((a, i) => `  ${i + 1}. [${a.assetType ?? '?'}] ${a.assetUrl ?? '(no url)'} (id ${a.id})`),
-    ].join('\n'));
-}
-/** Confirmation of a detached asset. */
-export function assetRemovedResult(r) {
-    return text(`Asset removed (id ${r.id}).`);
-}
-/** Confirmation of a detached post. */
-export function postRemovedResult(r) {
-    return text(`Post removed (id ${r.id}).`);
-}
-/** The account's tags. */
-export function tagListResult(tags) {
-    if (!tags.length)
-        return text('No tags yet. Create one with create_tag.');
-    return text([`${tags.length} tag(s):`, ...tags.map((t) => `- ${t.name} (id ${t.id})`)].join('\n'));
-}
-/** A created or renamed tag. */
-export function tagResult(t, verb = 'Tag') {
-    return text(`${verb}: ${t.name} (id ${t.id}).`);
-}
-/** Confirmation of a deleted tag. */
-export function tagDeletedResult(r) {
-    return text(`Tag deleted (id ${r.id}). It was removed from all posts.`);
-}
-/** The result of publishing a card's posts (one outcome per post). */
-export function publishResult(r) {
-    if (!r.results.length) {
-        return text('Nothing to publish: this card has no posts. Add one with update_card first.', true);
-    }
-    const rows = r.results.map((d) => d.success
-        ? `- ${d.platform}: published${d.url ? ` | ${d.url}` : ''}`
-        : `- ${d.platform}: FAILED | ${d.error ?? 'unknown error'}`);
-    const header = `Published ${r.publishedCount}/${r.results.length} post(s)${r.failedCount ? `, ${r.failedCount} failed` : ''}:`;
-    return text([header, ...rows].join('\n'), r.publishedCount === 0);
-}
-// -- inspiration / research ---------------------------------------------------
-/** Compact integer formatting (1.2M, 45.3K) for engagement counts. */
-function compactNum(n) {
-    if (n == null)
-        return '?';
-    if (n >= 1_000_000)
-        return `${(n / 1_000_000).toFixed(1)}M`;
-    if (n >= 1_000)
-        return `${(n / 1_000).toFixed(1)}K`;
-    return String(n);
-}
-/** One line summarizing a tracked account. */
-function accountLine(a) {
-    const handle = a.handle ? `@${a.handle}` : (a.name ?? '(unnamed)');
-    // The kind is on every line because the list is MIXED by default: without it a reader cannot tell the
-    // owner's own profile from a competitor they watch, and those mean opposite things.
-    const kind = a.accountType === 'brand' ? ' [yours]' : a.accountType === 'inspiration' ? ' [watching]' : '';
-    return `- ${handle} (id ${a.id})${kind} | ${a.platform ?? '?'} | ${compactNum(a.followerCount)} followers`;
-}
-/** List of tracked accounts, either kind. */
-export function trackedAccountListResult(accounts, noun = 'tracked account(s)') {
-    if (!accounts.length)
-        return text(`No ${noun} found. Add one in the ContentHero app first.`);
-    return text([`${accounts.length} ${noun}:`, ...accounts.map(accountLine)].join('\n'));
-}
-/** One line summarizing an outlier / content item. */
-function outlierLine(o) {
-    const score = o.outlierScore != null ? `${o.outlierScore.toFixed(1)}x` : 'n/a';
-    const creator = o.sourceCreator || (o.accountHandle ? `@${o.accountHandle}` : '');
-    // One list spans the owner's posts and the creators they watch, so each line has to say which it is.
-    const own = o.isOwn ? ' [yours]' : '';
-    return `- [${score}] ${o.title ?? '(untitled)'}${own}${creator ? ` | ${creator}` : ''} | ${compactNum(o.viewCount)} views (id ${o.id})`;
-}
-/** A page of outliers. */
-export function outlierListResult(result) {
-    if (!result.outliers.length) {
-        return text('No content found. Track some creators in the ContentHero app, or widen the filters.');
-    }
-    const more = result.hasMore ? ` (showing ${result.outliers.length} of ${result.total})` : '';
-    return text([`${result.total} outlier(s) by score${more}:`, ...result.outliers.map(outlierLine)].join('\n'));
-}
-/**
- * One tracked account with its performance.
- *
- * Merged from two formatters that printed the same account from the same table and differed only in how
- * much they showed: the inspiration one omitted totals, averages and recent content for no reason other
- * than which function you happened to call.
- */
-export function accountDetailResult(d) {
-    const a = d.account;
-    const handle = a.handle ? `@${a.handle}` : (a.name ?? '(unnamed)');
-    const kind = a.accountType === 'brand' ? ' [yours]' : a.accountType === 'inspiration' ? ' [watching]' : '';
-    const avgEng = d.averages.engagementRate != null ? `${(d.averages.engagementRate * 100).toFixed(1)}%` : 'n/a';
-    const avgScore = d.averages.outlierScore != null ? `${d.averages.outlierScore.toFixed(2)}x` : 'n/a';
-    return text(lines([
-        `${handle} (id ${a.id})${kind} | ${a.platform ?? '?'} | ${compactNum(a.followerCount)} followers`,
-        `content tracked: ${d.contentCount}`,
-        `totals: ${compactNum(d.totals.views)} views, ${compactNum(d.totals.likes)} likes, ${compactNum(d.totals.comments)} comments`,
-        `averages: ${compactNum(d.averages.views)} views/post, ${avgEng} engagement, ${avgScore} outlier score`,
-        d.topContent.length ? 'top content by outlier score:' : 'top content: none yet',
-        ...d.topContent.map(outlierLine),
-        d.recentContent.length ? 'most recent:' : null,
-        ...d.recentContent.map(outlierLine),
-    ]));
-}
-/** The transcript block, at whatever grain was asked for. */
-function transcriptLines(t) {
-    // The status is printed even when there is text, because 'failed' and 'absent' are the difference between
-    // "there is nothing to read" and "ask again later", and a reader cannot infer that from an empty body.
-    const head = `transcript [${t.status}]${t.language ? ` (${t.language})` : ''}${t.windowed ? ' (windowed)' : ''}:`;
-    if (t.segments) {
-        if (!t.segments.length) {
-            return [head, t.windowed ? '  (no segments in that window)' : '  (none stored)'];
-        }
-        return [head, ...t.segments.map((sg) => `  [${(sg.startMs / 1000).toFixed(1)}s] ${sg.text}`)];
-    }
-    return [head, t.text ? t.text : '  (none stored)'];
-}
-/** One tracked post in full, with its transcript when it was asked for. */
-export function inspirationContentResult(c) {
-    const stats = `${compactNum(c.viewCount)} views, ${compactNum(c.likeCount)} likes, ${compactNum(c.commentCount)} comments`;
-    const score = c.outlierScore != null ? `${c.outlierScore.toFixed(1)}x outlier` : null;
-    return text(lines([
-        `${c.title ?? '(untitled)'} (id ${c.id})${c.isOwn ? ' [yours]' : ''}`,
-        `${c.platform ?? '?'} ${c.contentType ?? ''} | ${c.sourceCreator ?? c.accountHandle ?? ''}`.trim(),
-        `${stats}${score ? ` | ${score}` : ''}`,
-        c.url ? `url: ${c.url}` : null,
-        c.publishedAt ? `published: ${c.publishedAt}` : null,
-        c.hashtags.length ? `hashtags: ${c.hashtags.join(' ')}` : null,
-        c.description ? `description: ${c.description}` : null,
-        ...(c.transcript ? transcriptLines(c.transcript) : []),
-    ]));
-}
-/** One line summarizing a connected account (a publish target). */
-function connectedAccountLine(a) {
-    const handle = a.accountHandle ? `@${a.accountHandle}` : (a.accountName ?? '(unnamed)');
-    const status = a.connectionStatus ? ` | ${a.connectionStatus}` : '';
-    return `- ${handle} (id ${a.id}) | ${a.platform ?? '?'}${a.isDefault ? ' [default]' : ''}${status}`;
-}
-/** List of connected accounts (publish targets). */
-export function connectedAccountListResult(accounts) {
-    if (!accounts.length) {
-        return text('No connected accounts. Connect a social account in the ContentHero app to publish.');
-    }
-    return text([`${accounts.length} connected account(s):`, ...accounts.map(connectedAccountLine)].join('\n'));
-}
-/** One connected account in detail, including its capabilities. */
-export function connectedAccountResult(a) {
-    const handle = a.accountHandle ? `@${a.accountHandle}` : (a.accountName ?? '(unnamed)');
-    const caps = a.capabilities ? Object.keys(a.capabilities).filter((k) => a.capabilities[k]) : [];
-    return text(lines([
-        `${handle} (id ${a.id}) | ${a.platform ?? '?'}${a.isDefault ? ' [default]' : ''}`,
-        `status: ${a.connectionStatus ?? 'unknown'}${a.connectionType ? ` (${a.connectionType})` : ''}`,
-        a.accountUrl ? `url: ${a.accountUrl}` : null,
-        caps.length ? `capabilities: ${caps.join(', ')}` : null,
-        a.lastValidatedAt ? `last validated: ${a.lastValidatedAt}` : null,
-        `Use this id as connectedAccountId on a post in update_card to publish here.`,
-    ]));
-}
-/** Map any thrown error onto a readable isError result. */
-export function errorResult(err) {
-    if (err instanceof InsufficientCreditsError) {
-        const parts = [];
-        if (err.required != null)
-            parts.push(`need ${err.required}`);
-        if (err.balance != null)
-            parts.push(`have ${err.balance}`);
-        const detail = parts.length ? ` (${parts.join(', ')})` : '';
-        return text(`Insufficient credits${detail}. Top up to continue.`, true);
-    }
-    if (err instanceof RateLimitError) {
-        const wait = err.retryAfter != null ? ` Retry in ${err.retryAfter}s.` : '';
-        return text(`Rate limit exceeded.${wait || ' Wait a moment before retrying.'}`, true);
-    }
-    if (err instanceof ContentHeroError || err instanceof Error) {
-        return text(err.message, true);
-    }
-    return text('Unknown error', true);
-}
-// -- editor / canvas ops ------------------------------------------------------
-/** The outcome of an applyEditorOps batch: the new revision + a per-op summary. */
-export function editorOpsResult(r) {
-    const okCount = r.results.filter((x) => x.ok).length;
-    const failures = r.results.filter((x) => !x.ok);
-    const created = r.results.flatMap((x) => x.createdIds ?? []);
-    const lines = [
-        // The surface no longer names the ops: it says `editor` or `canvas`, and "editor op(s)" reads worse than
-        // saying nothing, since the caller already knows which tool they invoked.
-        `Applied ${okCount}/${r.results.length} op(s). New revision: ${r.revision}.`,
-    ];
-    if (created.length)
-        lines.push(`Created: ${created.join(', ')}.`);
-    // Async effect ops (remove_background) dispatch a job and return its outputId; surface it so the agent can poll.
-    const generating = r.results.map((x) => x.generatingOutputId).filter((id) => !!id);
-    if (generating.length) {
-        lines.push(`Dispatched ${generating.length} async job(s); get_generation_status on: ${generating.join(', ')}.`);
-    }
-    if (r.renderUrl)
-        lines.push(`Preview: ${r.renderUrl}`);
-    if (failures.length) {
-        lines.push('Failed ops:');
-        for (const f of failures)
-            lines.push(`  - ${f.op}: ${f.error ?? 'unknown error'}`);
-    }
-    const warnings = r.results.flatMap((x) => x.warnings ?? []);
-    if (warnings.length)
-        lines.push(`Warnings: ${warnings.join('; ')}.`);
-    // A partial failure is surfaced as an error result so the caller (agent) can self-correct.
-    return text(lines.join('\n'), failures.length > 0);
-}
-/**
- * EXPOSURE GUARD for ProjectDetail.
- *
- * The MCP answers in TEXT, so a field this formatter does not print is INVISIBLE to the calling agent even
- * though the SDK fetched it. That makes silent drift the default: the app can add a field, the SDK type can
- * carry it, every build and test stays green, and no agent can ever see it. `compositionSpace` sat in
- * exactly that state, and the cost was an agent sizing every layer 2.26x wrong with no error.
- *
- * `satisfies Record<keyof ProjectDetail, ...>` makes the omission a DECISION rather than an accident: add a
- * field to ProjectDetail and this stops compiling until someone classifies it. Omitting is fine; omitting
- * silently is not.
- */
-const PROJECT_DETAIL_EXPOSURE = {
-    // Rendered in the summary line or the JSON body below.
-    id: 'rendered',
-    title: 'rendered',
-    kind: 'rendered',
-    // Added when `surface` joined ProjectDetail (8aecfd0). It went unnoticed because `dist/` is gitignored
-    // and this file typechecks against the BUILT SDK, so a stale dist hid the missing key until the next
-    // rebuild. Same value as `kind`, which is the name it used to have.
-    surface: 'rendered',
-    orientation: 'rendered',
-    width: 'rendered',
-    height: 'rendered',
-    revision: 'rendered',
-    compositionSpace: 'rendered',
-    groups: 'rendered',
-    state: 'rendered',
-    renderUrl: 'rendered (opt-in)',
-    brandKitId: 'rendered',
-    // Deliberately omitted, with the reason. Each of these is reachable through a dedicated tool, or is
-    // list-view metadata that tells a single-project reader nothing it did not already know by fetching it.
-    assetReferences: 'omitted: large payload; the composition state already names what is in use',
-    thumbnailUrl: 'omitted: presentation metadata, not an editing input',
-    isArchived: 'omitted: lifecycle state, surfaced by list_projects',
-    isFavorited: 'omitted: lifecycle state, surfaced by list_projects',
-    archivedAt: 'omitted: lifecycle state, surfaced by list_projects',
-    favoritedAt: 'omitted: lifecycle state, surfaced by list_projects',
-    createdAt: 'omitted: list metadata',
-    updatedAt: 'omitted: superseded by revision, which is the token that actually matters here',
-    exportedCardId: 'omitted: publishing workflow, owned by the card tools',
-    exportedUrl: 'omitted: publishing workflow, owned by the post tools',
-    shareId: 'omitted: sharing workflow, no editing effect',
-};
-void PROJECT_DETAIL_EXPOSURE;
-/** A single project's full detail (read-before-write): metadata, surface, revision, and the state JSON. */
-export function projectDetailResult(p) {
-    return text(`Project ${p.id}: "${p.title}" (${p.kind}, ${p.orientation} ${p.width}x${p.height}), revision ${p.revision}.\n` +
-        `Pass this revision back as expectedRevision when you edit.\n` +
-        // The output resolution above is NOT the coordinate space layer geometry uses. Stating both, adjacent
-        // and labeled, is the point: an agent that read only "2168x1152" sized every layer 2.26x too large
-        // and got no error for it, because an oversized box is valid input.
-        (p.compositionSpace
-            ? `Layer geometry is in composition space ${p.compositionSpace.width}x${p.compositionSpace.height} ` +
-                `(center-relative px), NOT the ${p.width}x${p.height} output resolution. ` +
-                `Use ${p.compositionSpace.width}x${p.compositionSpace.height} as layerWidth/layerHeight for a full-frame layer.\n`
-            : '') +
-        (p.renderUrl ? `Preview: ${p.renderUrl}\n` : '') +
-        // An agent asked to keep a design on-brand otherwise has no way to know WHICH kit this project is
-        // linked to: it can list kits, but not resolve the association.
-        (p.brandKitId ? `Brand kit: ${p.brandKitId} (read it with get_brand_kit).\n` : '') +
-        (p.groups?.length
-            ? `Groups: ${p.groups
-                .map((g) => `${g.name || `Group ${g.ordinal ?? '?'}`} [${g.id}] (${g.memberClipIds.length} clips)`)
-                .join('; ')}\n` +
-                `  Rename with update_group; bulk-edit a whole group with update_clips { groupId }.\n`
-            : '') +
-        `\n` +
-        JSON.stringify(p.state, null, 2));
-}
-/**
- * Live context (get_context). Returns a text summary + the discriminated context JSON, plus IMAGE content
- * block(s) so the calling model can actually SEE: the viewport `snapshot` (capture) when the user's screen was
- * requested, and/or the inline composed-output render (`context.rendered.dataUrl`) when `render` was requested.
- * The heavy render data URL is stripped from the JSON text (it rides only as the image block).
- */
-export function liveContextResult(result, snapshot) {
-    const { context, participant, participants } = result;
-    if (!context || !participant) {
-        return text('No live context: no one is currently viewing this in the open app (no session within the presence window). ' +
-            'The user may not have the editor/studio/content open right now.');
-    }
-    // Pull the inline render out as image block(s). A still carries `rendered.dataUrl` (one image); a filmstrip /
-    // clip carries `rendered.frames[].dataUrl` (many). Keep the light `rendered` metadata in the JSON but drop the
-    // bulky dataUrl(s) so the text summary stays readable.
-    const rendered = (context.rendered ?? null);
-    const renderImages = [];
-    let contextForJson = context;
-    if (rendered) {
-        const still = parseDataUrl(rendered.dataUrl);
-        const frames = Array.isArray(rendered.frames) ? rendered.frames : null;
-        if (still)
-            renderImages.push(still);
-        if (frames) {
-            for (const f of frames) {
-                const img = parseDataUrl(f.dataUrl);
-                if (img)
-                    renderImages.push(img);
-            }
-        }
-        if (renderImages.length > 0) {
-            // Strip the base64 payloads from the JSON but keep the frame timing (frame / atSec).
-            const strippedFrames = frames
-                ? frames.map((f) => {
-                    const { dataUrl: _drop, ...rest } = f;
-                    return rest;
-                })
-                : undefined;
-            contextForJson = {
-                ...context,
-                rendered: {
-                    ...rendered,
-                    ...(still ? { dataUrl: '[attached as an image below]' } : {}),
-                    ...(strippedFrames ? { frames: strippedFrames } : {}),
-                },
-            };
-        }
-    }
-    const others = participants.length > 1 ? ` (${participants.length} live participants; showing the most recent)` : '';
-    const renderNote = renderImages.length === 1
-        ? 'A render of your work is attached below.\n'
-        : renderImages.length > 1
-            ? `${renderImages.length} rendered frames are attached below, in order.\n`
-            : '';
-    const summary = `Live context on the ${String(context.surface)} surface${others}, updated ${participant.updatedAt}.\n` +
-        (snapshot ? 'An image of what the user is looking at (their screen) is attached below.\n' : '') +
-        renderNote +
-        `\n` +
-        JSON.stringify(contextForJson, null, 2);
-    const content = [{ type: 'text', text: summary }];
-    if (snapshot)
-        content.push({ type: 'image', data: snapshot.data, mimeType: snapshot.mimeType });
-    for (const img of renderImages)
-        content.push({ type: 'image', data: img.data, mimeType: img.mimeType });
-    return { content };
-}
-/** Parse a `data:<mime>;base64,<data>` URL into an image block's parts. Returns null on any non-data-URL. */
-function parseDataUrl(dataUrl) {
-    if (typeof dataUrl !== 'string')
-        return null;
-    const m = /^data:([^;]+);base64,(.+)$/s.exec(dataUrl);
-    const mimeType = m?.[1];
-    const data = m?.[2];
-    if (!mimeType || !data)
-        return null;
-    return { mimeType, data };
-}
-/** The project list: one line per project (id, kind, title, state flags). */
-export function projectListResult(projects) {
-    if (projects.length === 0)
-        return text('No projects found.');
-    const lines = projects.map((p) => {
-        const flags = [p.isArchived ? 'archived' : null, p.isFavorited ? 'favorited' : null].filter(Boolean).join(', ');
-        return `- ${p.id}  [${p.kind}]  "${p.title}"  ${p.orientation}${flags ? `  (${flags})` : ''}`;
-    });
-    return text(`${projects.length} project(s):\n${lines.join('\n')}`);
-}
-/** A freshly created project: the id + kind to start editing against. */
-export function projectCreatedResult(p) {
-    return text(`Created ${p.kind} project ${p.id}: "${p.title}" (${p.orientation} ${p.width}x${p.height}), revision ${p.revision}.\n` +
-        // The TOOL is still called update_timeline; `kind` is what says which one applies.
-        `Use this id with update_${p.kind === 'canvas' ? 'canvas' : 'timeline'} to add content.`);
-}
-/** Confirmation of a permanent delete. */
-export function projectDeletedResult(projectId) {
-    return text(`Permanently deleted project ${projectId}. This cannot be undone.`);
-}
-/** The canvas layer-type catalog (types + editable props) as readable text + the JSON. */
-export function layerTypesResult(cat) {
-    const lines = cat.layerTypes.map((t) => `- ${t.type}: ${t.description} (props: ${t.props.map((p) => p.name).join(', ')}; supports: ${t.supports.join(', ')})`);
-    const ops = cat.ops ? cat.ops.ops.map((o) => `- ${o.shape}  ${o.description}`) : [];
-    return text(`Canvas layer types (edit via update_canvas ops):\n${lines.join('\n')}\n\n` +
-        (ops.length ? `update_canvas ops (${cat.ops.description}):\n${ops.join('\n')}\n\n` : '') +
-        `Shared prop groups: ${Object.keys(cat.sharedProps).join(', ')}.\n\n` +
-        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}`);
-    }
-    if (job.status === 'failed') {
-        return text(`Export ${job.exportId} failed: ${job.errorMessage ?? 'unknown error'}.`, true);
-    }
-    const pct = typeof job.progress === 'number' ? ` (${Math.round(job.progress * 100)}%)` : '';
-    return text(`Export ${job.exportId} is ${job.status}${pct}. Still rendering. Poll get_export with this exportId for the download URL.`);
-}
-/** The export-format catalog as readable text + JSON. */
-export function exportFormatsResult(cat) {
-    const lines = cat.formats.map((f) => `- ${f.format} (${f.surfaces.join('/')}${f.async ? ', async' : ''}): ${f.description}`);
-    return text(`Export formats:\n${lines.join('\n')}\n\nResolutions (mp4): ${cat.resolutions.join(', ')}. Qualities: ${cat.qualities.join(', ')}.\n\n` +
-        JSON.stringify(cat, null, 2));
-}
-/** The editor timeline clip + track-type catalog as readable text + the JSON. */
-export function editorTranscriptResult(r) {
-    if (!r.mediaTranscribed) {
-        return text(r.note ?? 'No transcript available for this project yet.');
-    }
-    // A readable, clip-by-clip transcript in timeline order: each line is one clip, marked [disabled] when it is
-    // cut (excluded from the render) so the agent sees what is already removed. In word mode each line also
-    // summarizes its word / silence / event counts. The full structured data (clipIds, timeline frames, word
-    // timing, silences, audio events) follows as JSON for exact targeting via update_timeline.
-    const lines = r.segments.map((s) => {
-        const tag = s.disabled ? `[disabled${s.disabledReason ? `:${s.disabledReason}` : ''}]` : '[enabled]';
-        const body = s.text ? s.text : '(no speech)';
-        const extra = s.words || s.silences || s.audioEvents
-            ? ` {${s.words?.length ?? 0} words, ${s.silences?.length ?? 0} silences, ${s.audioEvents?.length ?? 0} events}`
-            : '';
-        return `${tag} ${s.clipId}  ${s.sourceStartMs}-${s.sourceEndMs}ms (frames ${s.fromFrame}-${s.fromFrame + s.durationFrames}):${extra} ${body}`;
-    });
-    const speakerLine = r.speakers && r.speakers.length > 0 ? `Speakers: ${r.speakers.join(', ')}.\n` : '';
-    return text(`Transcript for ${r.projectId} (${r.segmentCount} clip segment(s), ${r.fps}fps, revision ${r.revision}). [disabled] = cut/excluded from the render, [enabled] = kept.\n` +
-        `Cut non-destructively with update_timeline disable_ranges (source-media ranges) or set_disabled (whole clip); restore with set_disabled disabled:false. Word timing + timeline frames + silences + audio events are in the JSON when granularity 'word' was requested.\n` +
-        speakerLine +
-        `To edit safely against a concurrent change, pass revision ${r.revision} as expectedRevision; or omit expectedRevision to just apply to the current state.\n\n` +
-        `${lines.join('\n')}\n\n` +
-        JSON.stringify(r, null, 2));
-}
-export function timelineTypesResult(cat) {
-    const clips = cat.clipTypes.map((t) => `- ${t.type}: ${t.description} (props: ${t.props.map((p) => p.name).join(', ')})`);
-    const tracks = cat.trackTypes.map((t) => `- ${t.trackType}: holds ${t.holds.join(', ')}`);
-    const editOps = cat.editOps ? cat.editOps.ops.map((o) => `- ${o.shape}  ${o.description}`) : [];
-    return text(`Editor timeline clip types (edit via update_timeline ops):\n${clips.join('\n')}\n\nTrack types:\n${tracks.join('\n')}\n\n` +
-        (editOps.length ? `update_timeline edit ops (${cat.editOps.description}):\n${editOps.join('\n')}\n\n` : '') +
-        `Shared prop groups: ${Object.keys(cat.sharedProps).join(', ')}.\n\n` +
-        JSON.stringify(cat, null, 2));
-}
-//# sourceMappingURL=format.js.map