@cueframe/kernel 0.1.2 → 0.1.4

package/dist/{chunk-AO744WIK.js → chunk-PJ4R4N4Q.js}

@@ -209,7 +209,10 @@ function formatComposition(json) {
   ];
   if (json?.captions) {
     const segs = json.captions.segments?.length ?? 0;
-    const words = json.captions.words?.length ?? 0;
+    const words = Array.isArray(json.captions.segments) ? json.captions.segments.reduce(
+      (total, segment) => total + (Array.isArray(segment?.words) ? segment.words.length : 0),
+      0
+    ) : 0;
     lines.push(`captions: ${segs} segment(s), ${words} word(s) [text elided]`);
   }
   if (Array.isArray(json?.markers) && json.markers.length) {
@@ -228,16 +231,71 @@ function formatWarnings(json) {
 
 \u26A0 ${warns.join("\n\u26A0 ")}` : "";
 }
+var CONTEXT_WINDOW_CAP = 6;
+var CONTEXT_FACE_CAP = 3;
+var CONTEXT_SAMPLE_WORDS = 24;
+function formatMediaContext(json) {
+  const lines = [];
+  const dims = json?.width && json?.height ? `${json.width}\xD7${json.height}` : "unknown dimensions";
+  const duration = typeof json?.durationSec === "number" ? fmtClock(json.durationSec) : "unknown duration";
+  lines.push(`Media ${json?.mediaId ?? "?"} \u2014 ${dims}, ${duration}`);
+  if (json?.thumbnail?.url) lines.push(`thumbnail: ${json.thumbnail.url}`);
+  const windows = Array.isArray(json?.faces?.windows) ? json.faces.windows : [];
+  lines.push(`faces: ${json?.faces?.status ?? "unknown"} (${windows.length} source window(s))`);
+  for (const window of windows.slice(0, CONTEXT_WINDOW_CAP)) {
+    const faces = Array.isArray(window?.faces) ? window.faces : [];
+    const roster = faces.slice(0, CONTEXT_FACE_CAP).map((face) => {
+      const bbox = face?.bbox ?? {};
+      const box = [bbox.x, bbox.y, bbox.width, bbox.height].every((value) => typeof value === "number") ? ` bbox:${[bbox.x, bbox.y, bbox.width, bbox.height].map((n) => n.toFixed(3)).join(",")}` : "";
+      const speaking = typeof face?.speakingShare === "number" ? ` speaking:${Math.round(face.speakingShare * 100)}%` : "";
+      return `${face?.faceId ?? "?"}${box}${speaking}`;
+    });
+    lines.push(`- ${window?.window?.startSec ?? "?"}\u2192${window?.window?.endSec ?? "?"}s: ${roster.join(" | ") || "no usable subjects"}`);
+  }
+  if (windows.length > CONTEXT_WINDOW_CAP) lines.push(`- \u2026 ${windows.length - CONTEXT_WINDOW_CAP} more face windows elided`);
+  const transcript = json?.transcript;
+  const utterances = Array.isArray(transcript?.data?.utterances) ? transcript.data.utterances : Array.isArray(transcript?.data?.data) ? transcript.data.data : [];
+  const words = utterances.flatMap((utterance) => Array.isArray(utterance?.words) ? utterance.words : []);
+  const sample = words.slice(0, CONTEXT_SAMPLE_WORDS).map((word) => {
+    const start = typeof word?.start === "number" ? `@${word.start.toFixed(2)}s` : "";
+    return `${word?.word ?? word?.text ?? ""}${start}`;
+  }).filter(Boolean);
+  lines.push(`transcript: ${transcript?.status ?? "unknown"} (${utterances.length} utterance(s), ${words.length} word(s))`);
+  if (sample.length) lines.push(`sample: ${sample.join(" ")}`);
+  if (transcript?.status === "ready") {
+    lines.push("Use get_transcript(mediaItemId, limit, after/before) for exact paginated word timings.");
+  }
+  if (json?.beatGrid) {
+    const beats = Array.isArray(json.beatGrid.beatTimesMs) ? json.beatGrid.beatTimesMs : [];
+    lines.push(`beatGrid: ${json.beatGrid.bpm ?? "?"} bpm, ${beats.length} beats, ${json.beatGrid.method ?? "?"}${beats.length ? `; first ms: ${beats.slice(0, 12).join(",")}` : ""}`);
+  } else lines.push("beatGrid: none");
+  const wordTimes = Array.isArray(json?.wordGrid?.wordTimesMs) ? json.wordGrid.wordTimesMs : [];
+  lines.push(`wordGrid: ${wordTimes.length} onsets${wordTimes.length ? `; first ms: ${wordTimes.slice(0, 12).join(",")}` : ""}`);
+  lines.push(`audio: role=${json?.audioRole ?? "none"} envelope=${json?.envelope?.envelopeClass ?? "none"}`);
+  const facts = Array.isArray(json?.facts) ? json.facts : [];
+  const offers = Array.isArray(json?.offers) ? json.offers : [];
+  lines.push(`facts: ${facts.map((fact) => `${fact?.kind ?? "?"}:${fact?.status ?? "?"}`).join(", ") || "none"}`);
+  lines.push(`offers: ${offers.map((offer) => `${offer?.kind ?? "?"}${offer?.quotedUsd != null ? `($${offer.quotedUsd})` : ""}`).join(", ") || "none"}`);
+  return lines.join("\n");
+}
+function formatTranscriptPage(json) {
+  const utterances = Array.isArray(json?.data) ? json.data : Array.isArray(json?.utterances) ? json.utterances : [];
+  return JSON.stringify({
+    mediaItemId: json?.mediaItemId,
+    language: json?.language,
+    utterances,
+    ...json?.pagination ? { pagination: json.pagination } : {}
+  }, null, 2);
+}
 var CURATED_TOOLS = [
   {
     name: "compose",
     operationId: "compose",
     pathArgs: { projectId: "id" },
-    description: 'Start the async Director compose workflow: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): `briefId` \u2014 author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); `fromComposition: true` \u2014 author from the project\'s CURRENT composition (the GENERAL path: seed it with apply_composition first \u2014 your media clips are the intent, and any graphics you authored are CARRIED VERBATIM as locked clips the Director authors around, never re-authors or drops); or `suggestionId` \u2014 author from an AI clip suggestion (the CLIPPING path, paired with suggest_briefs). Returns { composeJobId, workflowId, status, streamUrl }. Then call wait_job(kind="compose", id=composeJobId, projectId=...) to block until the winner is selected.',
-    okFormat: (j, a) => `Compose workflow started.
+    description: 'Start an async Director compose job: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): `briefId` \u2014 author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); `fromComposition: true` \u2014 author from the project\'s CURRENT composition (the GENERAL path: seed it with apply_composition first \u2014 your media clips are the intent, and any graphics you authored are CARRIED VERBATIM as locked clips the Director authors around, never re-authors or drops); or `suggestionId` \u2014 author from an AI clip suggestion (the CLIPPING path, paired with suggest_briefs). Returns { composeJobId, status, streamUrl }. Then call wait_job(kind="compose", id=composeJobId, projectId=...) to block until the winner is selected.',
+    okFormat: (j, a) => `Compose job started.
 
 composeJobId: ${j.composeJobId}
-workflowId: ${j.workflowId}
 status: ${j.status}${j.streamUrl ? `
 streamUrl: ${j.streamUrl}` : ""}
 
@@ -294,43 +352,28 @@ Call wait_job(kind="render", id="${j.id}", projectId="${a.projectId}") to block
   },
   {
     name: "preview_frame",
-    operationId: "previewFrame",
+    operationId: "previewFrameJob",
     pathArgs: { projectId: "id" },
-    description: "Render presigned PNG still(s) of the composition at the given timestamps \u2014 the live preview for layout/copy judgment. STATELESS: nothing to open, warm, or close; concurrent previews don't contend. Defaults to the PERSISTED state: absent `body.composition` \u21D2 the project's ACTIVE composition \u2014 exactly what create_render will encode; pass `body.compositionId` to target a specific persisted composition (stale/foreign id \u21D2 404, never a silent fallback). The response's `previewed` field names what was rendered ({source: 'persisted'|'inline'|'scratch', compositionId?, etag?}) \u2014 trust a preview as render-truth ONLY when source is 'persisted'. `body.timestamps` = seconds to sample. A still cannot show motion \u2014 judge motion with preview_clip (a window of the composition) or preview_component (one graphic).",
-    preview: {
-      urls: (j) => (Array.isArray(j?.stills) ? j.stills : []).map((st) => st?.url),
-      kind: "image",
-      cap: 12
-    },
-    okFormat: (j, a) => {
-      const stills = Array.isArray(j?.stills) ? j.stills : [];
-      const p = j?.previewed ?? {};
-      const head = `Previewed ${stills.length} still(s) of project ${a.projectId}.
-source: ${p.source ?? "unknown"}${p.compositionId ? ` \xB7 compositionId: ${p.compositionId}` : ""}${p.etag ? ` \xB7 etag: ${p.etag}` : ""}${p.source !== "persisted" ? ' \u2014 NOT render-truth (only source "persisted" is what create_render will encode)' : ""}`;
-      const lines = stills.map((st, i) => {
-        const secs = typeof st?.beatSec === "number" ? st.beatSec : typeof st?.t === "number" ? st.t : typeof st?.timestamp === "number" ? st.timestamp : null;
-        const t = secs === null ? `#${i}` : `${secs.toFixed(2)}s`;
-        const url = typeof st?.url === "string" && !st.url.startsWith("data:") ? ` ${st.url}` : "";
-        return `  ${t}${url}`;
-      });
-      return `${head}
-${lines.join("\n")}
+    description: `Queue durable still-frame evidence for layout/copy judgment. Returns immediately with {jobId, kind:'preview_frame', status}; then call wait_job(kind="preview_frame", id=jobId) to receive every presigned frame as an image. The immutable snapshot records geometry, layers, warnings, and whether the target was persisted, inline, or session scratch. A still cannot prove motion \u2014 use preview_clip or preview_component for animation.`,
+    okFormat: (j) => `Preview-frame job queued.
 
-The frames ride with this result as images \u2014 judge the layout from the pixels, not from this text.`;
-    },
-    annotations: { readOnlyHint: true }
+jobId: ${j.jobId}
+status: ${j.status}
+
+Call wait_job(kind="preview_frame", id="${j.jobId}") for the rendered images.`,
+    annotations: { idempotentHint: true }
   },
   {
     name: "preview_component",
     operationId: "previewComponent",
     pathArgs: { projectId: "id" },
-    description: 'Queue a MOTION-clip render of ONE org-installed component \u2014 ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId) for a presigned short clip (VP9-alpha webm, ~3s \u2014 the SAME alpha bake the production render composites, so what you preview is what ships). Motion is the point of components; a still is one frame and lies about animation (A8). The author\u2192preview\u2192fix loop for a graphic. SESSIONLESS: the warm box is a server detail (a cold first call returns 409 box_warming \u2014 retry in a few seconds). `body.componentId` selects the component; pass `body.params` to render it with props. Failures land on the job terminal with typed codes: component_does_not_compile / component_runtime_error carry the sanitized author-fixable message \u2014 read it, fix the tsxSource via create_component, and re-preview. Idempotent per (componentId, params, dims).',
+    description: 'Queue a typed preview artifact for ONE org-installed component \u2014 ASYNC: returns a jobId immediately; then wait_job(kind="preview", id=jobId). Live components return artifactKind="image" with image/png or image/jpeg still evidence; baked components return artifactKind="motion" with the SAME content-addressed video/webm VP9-alpha object the production render composites. `body.componentId` selects the component; pass `body.params` to render it with props. Compile/runtime failures land on the job terminal with sanitized author-fixable messages. Idempotent per (componentId, params, dims).',
     okFormat: (j) => `Preview job queued.
 
 jobId: ${j.jobId}
 status: ${j.status}
 
-Call wait_job(kind="preview", id="${j.jobId}") for the presigned motion clip (re-call it if it returns still-running).`,
+Call wait_job(kind="preview", id="${j.jobId}") for the typed preview artifact (live=image, baked=motion; re-call it if it returns still-running).`,
     annotations: { idempotentHint: true }
   },
   {
@@ -349,7 +392,7 @@ wait_job(kind="render", id="${j.renderId ?? j.id}", projectId=...) for the watch
     name: "score_composition",
     operationId: "scoreComposition",
     pathArgs: { projectId: "id" },
-    description: `Queue the server-side judge \u2014 the standalone sighted check. ASYNC: returns a jobId (the judge takes minutes: it samples eval beats, renders them in a server-managed warm box, and grades editorial/spatial/brand/caption). Then wait_job(kind="verify", id=jobId) for per-criterion scores 0\u201310, a weighted composite, a worst-first critique, AND a checkpointId \u2014 the verdicts mint a durable kind:'score' Checkpoint, the same evidence noun the Director's gates produce (get_checkpoint re-reads it later). SESSIONLESS: a cold first call returns 409 box_warming \u2014 retry in a few seconds. \`body.composition\` optional (absent \u21D2 the ACTIVE composition). Fix the lowest criterion via apply_composition and re-score. Score answers "how good IS this" (grounded numbers); consult answers "what SHOULD I change" (advice + a fix candidate). Idempotent per composition state; the compose_verify meter fires on the job's success terminal.`,
+    description: 'Queue the durable server-side judge \u2014 it snapshots the exact authored target, samples eval beats, captures frames asynchronously, and grades editorial/spatial/brand/caption. Then wait_job(kind="verify", id=jobId) for per-criterion scores, weighted composite, worst-first critique, and checkpointId. `body.composition` is optional (absent \u21D2 ACTIVE). Fix the lowest criterion via apply_composition and re-score. Idempotent per immutable snapshot; compose_verify bills only on the guarded success terminal.',
     okFormat: (j) => `Score job queued.
 
 jobId: ${j.jobId}
@@ -466,9 +509,49 @@ ${j.tsxSource}`,
     name: "get_media_context",
     operationId: "getMediaContext",
     pathArgs: { mediaItemId: "id" },
-    description: "Fetch the authoring context for a media item: detected faces (subject boxes per frame) and the transcript. Use this before composing/applying so your crop intents, captions, and timing line up with what is actually in the footage.",
+    description: "Fetch bounded authoring context for a media item: dimensions/thumbnail, compact face roster, transcript counts/sample, temporal grids, and fact readiness. The full transcript body is deliberately elided so this read cannot overflow MCP; follow with get_transcript for exact paginated word timings.",
+    okFormat: (j) => formatMediaContext(j),
     annotations: { readOnlyHint: true }
   },
+  {
+    name: "get_transcript",
+    operationId: "getMediaTranscript",
+    pathArgs: { mediaItemId: "id" },
+    queryArgs: {
+      after: "Zero-based utterance cursor returned as pagination.nextCursor.",
+      before: "Zero-based utterance cursor for a backward page; do not combine with after.",
+      limit: "Utterances per page (1\u2013100). Use 20 by default."
+    },
+    description: "Read exact source-time transcript words in bounded utterance pages. Word start/end values are seconds from the source media start. Pass limit (20 recommended), then pagination.nextCursor as after; the formatter omits the unbounded fullText duplicate.",
+    okFormat: (j) => formatTranscriptPage(j),
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "prepare_media",
+    operationId: "purchaseMediaFact",
+    pathArgs: { mediaItemId: "id" },
+    description: 'Prepare the perception artifact an authored edit needs BEFORE sighted review. Pass body.kind="subjectTrack" for face/active-speaker reframing, or body.kind="matte" for a true zPlane:"behind-subject" graphic. Pass body.intent {startSec,endSec} using SOURCE time (the media trim, not timeline time); it is required for mattes and strongly recommended for subject tracks so the prepared fact exactly matches the clip and quote. This is the supported product path \u2014 never accept a preview that silently flattens depth or ignores speaker tracking. Returns a fact receipt; poll get_media_facts with the same kind/window until exact.state is ready (failed is terminal). Existing pending/ready facts are reused without another charge.',
+    okFormat: (j, a) => `Media preparation ${j.alreadyExisted ? "reused" : "started"}.
+
+factId: ${j.factId}
+status: ${j.status}
+quotedUsd: ${j.quotedUsd}
+
+Poll get_media_facts(mediaItemId="${a.mediaItemId}", kind="${a.body?.kind}", startSec="${a.body?.intent?.startSec}", endSec="${a.body?.intent?.endSec}") until exact.state is ready before preview_frame or score_composition.`,
+    annotations: { idempotentHint: true }
+  },
+  {
+    name: "get_media_facts",
+    operationId: "listMediaFacts",
+    pathArgs: { mediaItemId: "id" },
+    queryArgs: {
+      kind: "Optional exact fact kind: subjectTrack | matte. Requires startSec and endSec.",
+      startSec: "Source-window start in seconds. Send together with kind and endSec.",
+      endSec: "Source-window end in seconds. Send together with kind and startSec."
+    },
+    description: "Read prepared subject tracks and behind-subject mattes for one media item. For an exact readiness check, pass kind + startSec + endSec together using the same SOURCE window sent to prepare_media; exact.state is pending | ready | failed | available | unavailable. Use this after prepare_media and do not call preview_frame / score_composition until the required exact fact is ready.",
+    annotations: { readOnlyHint: true, idempotentHint: true }
+  },
   {
     name: "list_media",
     operationId: "listMedia",
@@ -540,28 +623,28 @@ Render it with create_render(projectId="${a.projectId}", body={ compositionId: "
   {
     name: "import_media",
     operationId: "importMedia",
-    description: 'Import a media item into your library from a public URL \u2014 the agent-friendly ingest path (single call, no upload protocol). Pass url (https) + filename (+ optional contentType). Returns { id, status:"importing" }. Processing is async: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed \u2014 status: complete|failed rides the payload). Use the returned id with get_media_context, suggest_briefs, or as a composition source.'
+    description: 'Import a media item into your library from a public URL \u2014 the agent-friendly ingest path (single call, no upload protocol). Pass url (https) + filename (+ optional contentType). Returns { id, status:"importing" }. Processing is async: call wait_job(kind="media", id=mediaItemId), or register a webhook (create_webhook on media.completed \u2014 status: complete|failed rides the payload). Use the returned id with get_media_context, suggest_briefs, or as a composition source.'
   },
   {
     name: "generate_media",
     operationId: "generateMedia",
-    description: 'Generate one first-class Library media item from a prompt. Choose generator: text-to-video | text-to-image | image-to-video | text-to-music | text-to-speech | text-to-sfx | auto. Put aspect/duration/voice/model controls in body.style and first/last/image references in body.refs. Returns { id, status:"generating", workflowId?, estimateUsd? }; returns 402 if the estimate exceeds the per-call ceiling. Async \u2014 poll list_media or use a webhook (media.completed \u2014 status rides the payload). Use the returned id like any other media item.'
+    description: 'Generate one first-class Library media item from a prompt. Choose generator: text-to-video | text-to-image | image-to-video | text-to-music | text-to-speech | text-to-sfx | auto. Put supported presentation controls in body.style and first/last/image references in body.refs. Returns { id, status:"generating", estimateUsd? }; returns 402 if the estimate exceeds the per-call ceiling. Async \u2014 call wait_job(kind="media", id=mediaItemId) or use a webhook (media.completed \u2014 status rides the payload). Use the returned id like any other media item.'
   },
   {
     name: "create_upload",
     operationId: "createMediaUpload",
-    description: "Ingest a LOCAL file \u2014 bytes you hold, when there is no public URL to hand import_media (prefer import_media whenever the bytes already sit at an https URL). TWO steps: (1) this tool reserves a media row and returns { id, uploadUrl, expiresAt } \u2014 a short-lived presigned PUT URL. PUT the raw file bytes straight to uploadUrl over HTTPS with your declared Content-Type (the bytes go direct to R2, never through MCP; \u2264 ~5 GB per PUT). (2) call finalize_upload({ mediaItemId: id }) to start processing. Body: filename, contentType (allowed enum), size (bytes). Thereafter it is async exactly like import_media: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed). Use the returned id with get_media_context, suggest_briefs, or as a composition source."
+    description: "Ingest a LOCAL file \u2014 bytes you hold, when there is no public URL to hand import_media (prefer import_media whenever the bytes already sit at an https URL). TWO steps: (1) this tool reserves a media item and returns { id, uploadUrl, expiresAt } \u2014 a short-lived PUT URL. PUT the raw file bytes to uploadUrl over HTTPS with your declared Content-Type (\u2264 ~5 GB per PUT). (2) call finalize_upload({ mediaItemId: id }) to start processing. Body: filename, contentType (allowed enum), size (bytes). Thereafter it is async exactly like import_media: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed). Use the returned id with get_media_context, suggest_briefs, or as a composition source."
   },
   {
     name: "finalize_upload",
     operationId: "finalizeMedia",
     pathArgs: { mediaItemId: "id" },
-    description: 'Finalize a direct upload once you have PUT the bytes to the uploadUrl from create_upload. Confirms the bytes landed and starts ingest: image/asset become ready immediately (status "complete"); audio/video enter processing (status "processing"). Returns { id, status, processingPhase }. 400 if no bytes were uploaded (PUT first) or the item is not awaiting finalize; 404 if the id is not yours. Then poll list_media / get_media_context, or use a media.completed webhook.'
+    description: 'Finalize a direct upload once you have PUT the bytes to the uploadUrl from create_upload. Confirms the bytes landed and starts ingest: image/asset become ready immediately (status "complete"); audio/video enter processing (status "processing"). Returns { id, status, processingPhase }. 400 if no bytes were uploaded (PUT first) or the item is not yours. Then call wait_job(kind="media", id=mediaItemId), or use a media.completed webhook.'
   },
   {
     name: "search_resources",
     operationId: "searchResources",
-    description: "Search licensed STOCK media to compose with \u2014 video/photo (Pexels + Pixabay fallback), sfx (Freesound, CC0-only), gif (Klipy). Pass query for ONE search, or queries[] (\u226410) to run them all in a SINGLE call \u2014 strongly prefer the batch when you know several things you need (a 64-search session spent 5m10s on serial round-trips). A batch returns results[], one per query in order, each with its own candidates; a query that fails carries an error and never discards the others. Optional kind [default video], provider pin, limit \u226450 apply to every query in the batch. Returns ranked candidates, each with an opaque candidateId + attribution (author, assetUrl) + license, and a preview URL in the text. FREE + rate-limited + 7-day cached \u2014 reach for this before generate_media when real footage beats synthesis. TO SEE the candidates rather than read about them, pass limit \u22652: thumbnails/audio are attached only when you asked for options to compare, because a preview of a single forced choice is pure cost. Import a chosen candidate into a project with import_resource. Candidates expire after 7 days (re-search to refresh a candidateId).",
+    description: "Search licensed stock media to compose with across video, photo, sound effects, and GIFs. Pass query for ONE search, or queries[] (\u226410) to run them all in a SINGLE call \u2014 strongly prefer the batch when you know several things you need. A batch returns results[], one per query in order, each with its own candidates; a query that fails carries an error and never discards the others. Optional kind [default video], provider pin, and limit \u226450 apply to every query in the batch. Returns ranked candidates, each with an opaque candidateId + attribution (author, assetUrl) + license, and a preview URL in the text. FREE + rate-limited + cached \u2014 reach for this before generate_media when real footage beats synthesis. TO SEE the candidates rather than read about them, pass limit \u22652: thumbnails/audio are attached only when you asked for options to compare. Import a chosen candidate into a project with import_resource. Candidate handles expire; re-search to refresh one.",
     okFormat: (j) => formatResourceCandidates(j),
     preview: {
       urls: (j) => (Array.isArray(j?.results) ? j.results.flatMap((r) => Array.isArray(r?.candidates) ? r.candidates : []) : Array.isArray(j?.candidates) ? j.candidates : []).map((c) => c?.previewUrl),
@@ -581,13 +664,13 @@ Render it with create_render(projectId="${a.projectId}", body={ compositionId: "
   {
     name: "import_resource",
     operationId: "importResource",
-    description: 'Import a stock candidate (candidateId from search_resources) into a project as an ORG-OWNED media item \u2014 provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async \u2014 poll list_media / get_media_context, then use the returned id as a composition source. Gated on the resource_import plan feature (402 billing_required if your plan lacks it). 422 candidate_mismatch if the candidate expired \u2014 re-run search_resources.'
+    description: 'Import a stock candidate (candidateId from search_resources) into a project as an ORG-OWNED media item \u2014 provider/externalId/license provenance preserved, bytes deduped across orgs. Pass projectId + candidateId. Returns { id, status:"importing"|"ready" }; processing is async \u2014 call wait_job(kind="media", id=mediaItemId), then use the returned id as a composition source. Gated on the resource_import plan feature (402 billing_required if your plan lacks it). 422 candidate_mismatch if the candidate expired \u2014 re-run search_resources.'
   },
   {
     name: "suggest_briefs",
     operationId: "suggestBriefs",
     pathArgs: { mediaItemId: "id" },
-    description: `Run AI clip-suggestion analysis on a long-form media item \u2014 the CLIPPING path (find the best short-form moments). Returns { workflowId, status }; then wait_job(kind="suggestions", id=mediaItemId) \u2014 its terminal lists each suggestion WITH its briefId. When the media belongs to a PROJECT, each finalized suggestion is promoted to a kind-'clip' BRIEF (its window pinned as a beat) \u2014 list_briefs {kind:"clip"} shows them and compose({ briefId }) runs the flagship path from one. Project-less media: pass the suggestion id to compose({ suggestionId }) directly. Clipping is a vertical, NOT the general path.`
+    description: `Run AI clip-suggestion analysis on a long-form media item \u2014 the CLIPPING path (find the best short-form moments). Returns { status, alreadyRunning? }; then wait_job(kind="suggestions", id=mediaItemId) \u2014 its terminal lists each suggestion WITH its briefId. When the media belongs to a PROJECT, each finalized suggestion is promoted to a kind-'clip' BRIEF (its window pinned as a beat) \u2014 list_briefs {kind:"clip"} shows them and compose({ briefId }) runs the flagship path from one. Project-less media: pass the suggestion id to compose({ suggestionId }) directly. Clipping is a vertical, NOT the general path.`
   },
   {
     name: "create_webhook",
@@ -905,6 +988,8 @@ export {
   formatResourceCandidates,
   formatComposition,
   formatWarnings,
+  formatMediaContext,
+  formatTranscriptPage,
   CURATED_TOOLS,
   INTERNAL_EDITOR_TOOLS,
   KNOWN_BACKEND_GAPS,

package/dist/{chunk-VFMW3JUY.js → chunk-QSDFTYKV.js}

@@ -1,6 +1,6 @@
 import {
   resolveBookendTimeline
-} from "./chunk-VHF66LCQ.js";
+} from "./chunk-RXCEPCAQ.js";
 
 // ../execution/compose/src/tokenResolver.ts
 var DEFAULTS = {

package/dist/{chunk-LLUW26BS.js → chunk-R5BMJ2NX.js}

@@ -86,7 +86,7 @@ var ERROR_CODES = {
   selector_speaking_double_count: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   selector_identity_detector_version_mismatch: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   variant_not_baked: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
-  behind_matte_unresolved: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
+  behind_matte_unresolved: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   render_output_invalid: { stage: "render", category: "internal", retryable: false, httpStatus: 422 },
   audio_sync_invalid: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   generation_output_invalid: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
@@ -96,16 +96,35 @@ var ERROR_CODES = {
   brand_kit_unresolved: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   unknown_format: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   render_not_cancellable: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
+  render_not_found: { stage: "render", category: "authoring", retryable: false, httpStatus: 404 },
   compose_not_cancellable: { stage: "system", category: "authoring", retryable: false, httpStatus: 422 },
   job_not_cancellable: { stage: "system", category: "authoring", retryable: false, httpStatus: 422 },
   export_not_cancellable: { stage: "export", category: "authoring", retryable: false, httpStatus: 422 },
   render_not_complete: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   lambda_infra_failed: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  render_provider_unreachable: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  render_provider_start_failed: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  behind_split_unsupported: { stage: "validate", category: "authoring", retryable: false, httpStatus: 422 },
+  render_pipeline_unavailable: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  render_route_missing: { stage: "render", category: "internal", retryable: true, httpStatus: 503 },
+  render_pipeline_failed: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  render_stage_timeout: { stage: "render", category: "transient", retryable: true, httpStatus: 504 },
+  render_promotion_failed: { stage: "render", category: "internal", retryable: true, httpStatus: 500 },
+  render_execution_failed: { stage: "render", category: "internal", retryable: false, httpStatus: 500 },
+  invalid_render_terminal: { stage: "render", category: "internal", retryable: false, httpStatus: 500 },
+  sighted_dispatch_failed: { stage: "system", category: "transient", retryable: true, httpStatus: 503 },
+  sighted_stage_timeout: { stage: "render", category: "transient", retryable: true, httpStatus: 504 },
+  sighted_provider_unreachable: { stage: "render", category: "transient", retryable: true, httpStatus: 503 },
+  sighted_artifact_missing: { stage: "render", category: "internal", retryable: true, httpStatus: 500 },
+  sighted_execution_failed: { stage: "render", category: "internal", retryable: false, httpStatus: 500 },
+  sighted_snapshot_missing: { stage: "system", category: "internal", retryable: false, httpStatus: 500 },
   render_stalled: { stage: "render", category: "transient", retryable: true, httpStatus: 500 },
   render_unknown_primitive: { stage: "render", category: "authoring", retryable: false, httpStatus: 422 },
   session_in_use: { stage: "export", category: "authoring", retryable: false, httpStatus: 422 },
   transcript_unavailable: { stage: "export", category: "transient", retryable: true, httpStatus: 503 },
   service_unavailable: { stage: "system", category: "transient", retryable: true, httpStatus: 503 },
+  operation_moved_async: { stage: "system", category: "authoring", retryable: false, httpStatus: 410 },
+  active_composition_invariant: { stage: "system", category: "internal", retryable: false, httpStatus: 500 },
   internal_error: { stage: "system", category: "internal", retryable: false, httpStatus: 500 }
 };
 var CueframeError = class extends Error {
@@ -191,7 +210,24 @@ var FIX_ALLOW = [
   "typeMismatches",
   "constraintViolations"
 ];
-var LOCATOR_ALLOW = ["projectId", "renderId", "requestId", "clipId", "trackId", "compositionPath"];
+var LOCATOR_ALLOW = [
+  "projectId",
+  "compositionId",
+  "renderId",
+  "jobId",
+  "requestId",
+  "workflowId",
+  "activityId",
+  "stage",
+  "clipId",
+  "trackId",
+  "mediaId",
+  "componentId",
+  "outputFrame",
+  "timecodeMs",
+  "providerRequestId",
+  "compositionPath"
+];
 var GENERIC = {
   transient: "A temporary error occurred; retry.",
   internal: "An unexpected error occurred."