@contenthero/mcp 0.3.2 → 0.3.3

package/dist/format.js

@@ -4,15 +4,27 @@
  * a readable message instead of a transport failure.
  */
 import { ContentHeroError, InsufficientCreditsError, RateLimitError } from '@contenthero/sdk';
-function text(body, isError = false) {
+export function text(body, isError = false) {
     return { content: [{ type: 'text', text: body }], isError };
 }
-/** A finished image/video generation: list the asset URLs. */
+/** A finished image/video generation: list the asset URLs, plus the placement outcome when placed on a project. */
 export function completedResult(gen) {
     const urls = gen.outputUrls ?? [];
     const noun = urls.length === 1 ? gen.contentType : `${gen.contentType}s`;
     const header = `Done. ${urls.length} ${noun} from ${gen.modelId} (outputId ${gen.outputId}):`;
-    return text([header, ...urls.map((u, i) => `${i + 1}. ${u}`)].join('\n'));
+    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('; ')}`);
+    }
+    return text(lines.join('\n'));
 }
 /** Suggested seconds to wait before re-polling a job, by content type. */
 export function pollAfterSecondsFor(contentType) {
@@ -28,6 +40,31 @@ export function audioResult(result) {
     const header = `Done. Audio generated (outputId ${result.outputId}):`;
     return text([header, ...urls.map((u, i) => `${i + 1}. ${u}`)].join('\n'));
 }
+/**
+ * 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 header = jobs.length === 1
+        ? 'Enhancing 1 source. Poll its outputId with get_generation_status (or wait_for_generation):'
+        : `Enhancing ${jobs.length} sources as separate jobs, because a noise profile is estimated per recording. Poll EVERY outputId:`;
+    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';
@@ -64,7 +101,8 @@ export function generationBatchResult(gens) {
 /** A finished transcription: header line plus the transcript body. */
 export function transcriptResult(t) {
     const lang = t.language ? ` (${t.language})` : '';
-    const header = `Transcript${lang}, ${t.wordCount} words (outputId ${t.outputId}):`;
+    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). */
@@ -90,7 +128,7 @@ export function avatarResult(a) {
         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.imageUrl ?? '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'}`),
     ]));
 }
 /** List of saved voices. */
@@ -166,25 +204,85 @@ export function brandKnowledgeSearchResult(matches) {
 export function brandKnowledgeItemResult(item, verb = 'Added') {
     return text(`${verb} knowledge item: "${item.title ?? '(untitled)'}" [${item.sourceType ?? 'unknown'}] (id ${item.id}).`);
 }
-export function brandKitArchivedResult(kit) {
-    return text(`Archived brand kit "${kit.name}" (id ${kit.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 studio outputs (media). */
+/** 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) => {
-        const vars = m.variationCount > 1 ? ` | ${m.variationCount} variations` : '';
+        // 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}`
                 : '';
-        return `- [${m.type}] ${m.model ?? ''} (id ${m.id})${kindTag}${vars} | ${m.status}${promptStr}`;
+        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 = [
@@ -201,16 +299,103 @@ export function mediaResult(m) {
         m.script ? `script: ${m.script}` : null,
         specs || null,
         `status: ${m.status}${m.creditsUsed != null ? ` | ${m.creditsUsed} credits` : ''}`,
-        `variations (${m.variationCount}):`,
-        ...m.variations.map((v) => `  ${v.variation}. ${v.url ?? `(no url, ${v.status})`}${v.isFavorited ? ' [favorite]' : ''}`),
+        `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.
+ */
+export function mediaBatchResult(result, images) {
+    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 });
+            }
+        }
+    });
+    return { content };
+}
 /** 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 with the file's Content-Type (expires ${r.expiresAt}):`,
+        `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.',
     ]));
@@ -644,4 +829,262 @@ export function errorResult(err) {
     }
     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); wait_for_generation 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',
+    exportedPostId: 'omitted: publishing workflow, owned by the post 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 labelled, 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. */
+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