@cueframe/kernel 0.1.1 → 0.1.3

package/dist/{chunk-HI4UTTPS.js → chunk-DJW3UGBH.js}

@@ -248,8 +248,6 @@ Call wait_job(kind="compose", id="${j.composeJobId}", projectId="${a.projectId}"
     operationId: "applyComposition",
     pathArgs: { projectId: "id" },
     description: 'Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Pass `if_match` for optimistic-concurrency control (409 stale_etag on mismatch) and `dry_run: true` to validate the batch without persisting. Use this to seed a composition (add media clips) or make targeted edits (set a crop intent, reorder clips, set the format). CAPTIONS: attach content with {type:"captions.fromTranscript", mediaId, window?} \u2014 the server slices the cached word-timed transcript, rebases times, and sentence-splits into segments (no pasting words; 422 media_no_transcript if the media has no speech); style it with {type:"setCaptionStyle", style}; or set explicit words with {type:"setCaptions", segments, style?} (e.g. translations or your own VO timings). Brand is NOT set here \u2014 it lives on the project (create_project / PATCH /projects/:id with brandKitId). CARDS: a {kind:"card", html, tokens} clip projects each `tokens` KEY `x` to the CSS custom property `--cf-x`, so the html must read it as `var(--cf-x)` \u2014 write `tokens:{"plate":"#0af"}` + `background:var(--cf-plate)`. Do NOT put dashes in the key: `"--plate"` becomes `--cf---plate` and your `var(--plate)` then resolves to NOTHING, which CSS silently degrades to a transparent background and black text. Responses carry `warnings[]` when a card reads a var nothing defines.',
-    // A dry_run returns HTTP 200 { valid, errors } — branch on it so a FAILED
-    // validation is never reported as "applied" (the route returns 200 either way).
     okFormat: (j, a) => {
       const warns = formatWarnings(j);
       if (j && typeof j.valid === "boolean") {
@@ -259,9 +257,6 @@ ${JSON.stringify(r.errors ?? [], null, 2)}${warns}`;
       }
       return `Ops applied${a.projectId ? ` to project ${a.projectId}` : ""}.${warns}`;
     },
-    // Teach the TARGETED patch: one clip, only the fields that change. The
-    // measured anti-pattern is re-emitting a whole card source per tweak
-    // (44-92s turns); a patch of position/opacity/params is seconds.
     inputExamples: [
       {
         input: {
@@ -299,59 +294,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).",
-    // The most-called visual tool, and it returned a JSON blob of presigned
-    // links: the agent was told to judge layout and copy it could not see.
-    preview: {
-      urls: (j) => (Array.isArray(j?.stills) ? j.stills : []).map((st) => st?.url),
-      kind: "image",
-      cap: 12
-    },
-    // WITHOUT THIS, THE PIXELS SHIP TWICE — ONCE AS TEXT.
-    //
-    // The generic path falls back to `res.text` when a spec has no okFormat, so
-    // the model saw the WHOLE response JSON, `stills[].url` included, ALONGSIDE
-    // the image blocks. On the cloud lane that is a presigned link per still —
-    // wasteful. On the desktop lane (LocalExecutor serves this route out of the
-    // webview and has no R2, so it answers with `data:` URLs carrying the bytes
-    // inline) it is the ENTIRE IMAGE duplicated as base64 TEXT: 12 stills ≈
-    // hundreds of thousands of junk tokens, and the text copy is the one the
-    // model cannot see.
-    //
-    // So: a `data:` url is DROPPED (the bytes are already arriving as a media
-    // block — the text copy is pure waste). A real http(s) url is KEPT, because
-    // there it is 200 characters and an MCP host can open it.
-    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 }
   },
   {
@@ -370,7 +334,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}
@@ -420,8 +384,6 @@ Call wait_job(kind="verify", id="${j.jobId}") to block until the scores + checkp
     operationId: "getCheckpoint",
     pathArgs: { checkpointId: "id" },
     description: "Read a checkpoint packet \u2014 the durable approval unit a held compose pauses at (wait_job reports awaiting_input with {checkpointId, stage, version}). Carries the stage artifact, presigned storyboard stills (REVIEW THE EVIDENCE, not raw JSON), critic verdicts, the money triple {thisStepUsd, jobSpendSoFarUsd, estimatedJourneyTotalUsd} to relay to your human, and the recorded decision once resolved. When the Brief's gates set reviewMode:'hosted' the packet also carries reviewUrl \u2014 a browser review page where your human decides directly (relay THAT link instead of raw stills; you learn the decision via checkpoint webhooks / wait_job). Answer an awaiting packet with resume(checkpointId, ...).",
-    // The packet grades stills the agent was never shown: it got a score and a
-    // text critique and was told to 'fix the lowest criterion' sight-unseen.
     preview: {
       urls: (j) => Array.isArray(j?.stillUrls) ? j.stillUrls : [],
       kind: "image",
@@ -451,12 +413,6 @@ Call wait_job(kind="verify", id="${j.jobId}") to block until the scores + checkp
     description: "Delete a brief. Compose jobs already run from it are unaffected (they snapshot)."
   },
   {
-    // A12 cutover note: 'adopt_candidate' is BURNED (tombstoned); the
-    // capability survives as select_candidate because consult(amend) proposals
-    // carry only a candidateIndex — without a curated select the amend mode is
-    // a dead-end (the exact defect plan-1 fixed). The full fold into the
-    // checkpoint review model (consult minting a score packet you resume) is
-    // plan-5 scope.
     name: "select_candidate",
     operationId: "selectComposeCandidate",
     pathArgs: { projectId: "id", composeJobId: "composeJobId" },
@@ -474,10 +430,6 @@ Call wait_job(kind="verify", id="${j.jobId}") to block until the scores + checkp
     description: "DISCOVER WHAT TO BUILD WITH \u2014 list the component catalog: the FULL built-in primitive catalog (text, effects, transitions, layouts, backgrounds, and scenes: lower-third, cinematic-title, color-grade, product-launch-trailer, \u2026) PLUS your org-installed components. Use it for UTILITY furniture (captions, grades, transitions, backgrounds, scenes) and as REFERENCE CODE (get_component_source) \u2014 for BRAND or text graphics, default to authoring your OWN `kind:'card'` clip (your HTML + tokens, poster-grade typography) shelled with `applyMotionPreset`; a catalog text primitive is the quick generic fallback, not the identity path. Narrow with filters: `category` (text|effects|transitions|layouts|backgrounds|ui-blocks|scenes), `kind` (component|transition|scene), `tier` (recommended|standard|niche), `useCase` (intro|outro|full-scene|title-over-footage|transition|background|grade|emphasis|explainer|social-cut), `mood`, or free-text `q`/`intent` (e.g. intent='intro'). When any filter is set, results are recommended-tier-first. With NO `limit` the whole filtered catalog returns in one page. Each entry carries a `placement` hint = exactly how to author it via apply_composition ({kind:'overlay'|'effect', primitiveId} for built-ins; {kind:'component', componentId} for installed), `tier`/`useCase` to pick by, and `fixedCopy` (on-screen strings it BAKES that no param changes \u2014 fork via get_component_source to edit). Read cueframe://component/{id} for the full prop schema.",
     okFormat: (j) => formatComponentList(j),
     annotations: { readOnlyHint: true },
-    // 103 visual primitives described in PROSE — an agent picked silk-flow-bg
-    // over vector-field from a sentence. The renders and the CDN have existed
-    // for a while; this is the join. Best-effort by design: org-installed
-    // components have no published preview, and a miss yields no thumbnail.
     preview: {
       urls: (j) => (Array.isArray(j?.data) ? j.data : []).map((e) => CATALOG_PREVIEWS[e?.id]),
       kind: "image",
@@ -502,6 +454,32 @@ ${j.tsxSource}`,
     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.",
     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",
@@ -573,12 +551,12 @@ 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 a media item from a prompt (generator: text-to-video | text-to-image | image-to-video | auto). Returns { id, status:"generating", 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 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 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",
@@ -589,22 +567,17 @@ Render it with create_render(projectId="${a.projectId}", body={ compositionId: "
     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).",
     okFormat: (j) => formatResourceCandidates(j),
-    // Stock was picked from resolution, duration and author name — eight
-    // near-identical clips in one session. Thumbnails end that. But ONLY when
-    // there is something to pick BETWEEN: see `attach` on CuratedTool.preview.
     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),
       kind: (j) => (j?.kind ?? j?.results?.[0]?.kind) === "sfx" ? "audio" : "image",
       cap: 12,
-      // A batch is by definition a comparison, so its previews are earned. A
-      // single-query search returning one candidate still gets none.
       attach: (j) => Array.isArray(j?.results) ? true : (Array.isArray(j?.candidates) ? j.candidates.length : 0) > 1
     },
     annotations: { readOnlyHint: true }
@@ -619,7 +592,7 @@ 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",
@@ -792,7 +765,6 @@ Call wait_job(kind="brand_kit_extract", id="${j.jobId}") for the tokens (re-call
   }
 ];
 var INTERNAL_EDITOR_TOOLS = [
-  // Read — orient, then look. get_context is the one-call opener.
   "get_context",
   "get_composition",
   "get_media_context",
@@ -805,17 +777,14 @@ var INTERNAL_EDITOR_TOOLS = [
   "score_composition",
   "validate_composition",
   "analyze_transcript",
-  // Mutate — the L1 op union is the ONLY way an edit happens.
   "apply_composition",
   "new_composition",
   "derive_composition",
-  // Assets
   "import_media",
   "import_resource",
   "create_component",
   "generate_media",
   "search_fonts",
-  // Jobs + account
   "create_render",
   "wait_job",
   "get_usage",