@cueframe/kernel 0.0.1

package/dist/_members/mcp/resources.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CueFrame MCP resources — the read side of the surface (no side effects).
+ *
+ * Every read endpoint is a URI-addressed MCP *resource*, executed through the
+ * transport's `Executor` (stdio: network; hosted: in-process) against the GET
+ * op's path from the generated manifest — the SAME single source of truth the
+ * tools use, so paths are never hand-maintained. Four templates (media,
+ * component, project, brand-kit) also carry a `list` callback so resources/list
+ * enumerates concrete instances via the matching list op.
+ *
+ * Fail-loud: a non-2xx read throws, which the MCP server surfaces as a JSON-RPC
+ * error (no try/catch swallow).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Executor } from './core.js';
+export declare function registerResources(server: McpServer, ex: Executor): void;

package/dist/_members/mcp/resources.js

@@ -0,0 +1,166 @@
+/**
+ * CueFrame MCP resources — the read side of the surface (no side effects).
+ *
+ * Every read endpoint is a URI-addressed MCP *resource*, executed through the
+ * transport's `Executor` (stdio: network; hosted: in-process) against the GET
+ * op's path from the generated manifest — the SAME single source of truth the
+ * tools use, so paths are never hand-maintained. Four templates (media,
+ * component, project, brand-kit) also carry a `list` callback so resources/list
+ * enumerates concrete instances via the matching list op.
+ *
+ * Fail-loud: a non-2xx read throws, which the MCP server surfaces as a JSON-RPC
+ * error (no try/catch swallow).
+ */
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { opById, buildPath, isOk, apiErrorFrom, fetchAsBase64, sniffImageMediaType, } from './core.js';
+/** GET a manifest op's path through the executor; throw on non-2xx (fail loud). Returns parsed JSON. */
+async function read(ex, operationId, mapArg) {
+    const op = opById(operationId);
+    const res = await ex.invoke({ method: 'GET', path: buildPath(op, mapArg) });
+    if (!isOk(res.status))
+        throw apiErrorFrom(res);
+    try {
+        return JSON.parse(res.text);
+    }
+    catch {
+        return res.text;
+    }
+}
+function jsonResource(uri, value) {
+    return {
+        contents: [{ uri: uri.toString(), mimeType: 'application/json', text: JSON.stringify(value, null, 2) }],
+    };
+}
+/**
+ * A JSON resource PLUS the poster frame, so a client reading a media item can
+ * see the footage instead of reading its filename and duration.
+ *
+ * MCP resource contents carry either `text` or a base64 `blob`; this appends a
+ * blob entry alongside the JSON rather than replacing it, matching the additive
+ * contract the tool surface uses (`withMedia`). No poster, or a poster that will
+ * not load, yields the JSON alone — never an error.
+ */
+async function jsonResourceWithPoster(uri, value) {
+    const base = jsonResource(uri, value);
+    const url = value?.thumbnail?.url;
+    if (!url)
+        return base;
+    const data = await fetchAsBase64(url);
+    if (!data)
+        return base;
+    return {
+        contents: [
+            ...base.contents,
+            { uri: url, mimeType: sniffImageMediaType(data), blob: data },
+        ],
+    };
+}
+/** Build a resources/list callback that enumerates `{ data: [{id,name?}] }` under a URI prefix. */
+function listFrom(ex, prefix, listOperationId) {
+    return async () => {
+        const res = (await read(ex, listOperationId, () => ''));
+        return {
+            resources: (res.data ?? []).map((item) => ({
+                uri: `${prefix}/${item.id}`,
+                name: item.name ?? item.id,
+                mimeType: 'application/json',
+            })),
+        };
+    };
+}
+/**
+ * FACET-BEARING resources/list for the component catalog. Unlike `listFrom`
+ * (which strips every entry to {uri,name}), this carries the discovery facets
+ * (source/category/kind/tier/useCase) + the placement hint into each entry's
+ * `description`, so an agent can CHOOSE a primitive from the list alone instead
+ * of round-tripping cueframe://component/{id} for all 87 entries to recover them.
+ */
+function listComponentsFrom(ex, prefix) {
+    return async () => {
+        // No `limit` → the route returns the WHOLE catalog (built-ins + installed)
+        // in one page, so resources/list enumerates every primitive, not a slice.
+        const res = (await read(ex, 'listCatalog', () => ''));
+        return {
+            resources: (res.data ?? []).map((e) => {
+                const facets = [
+                    e.source === 'installed' ? 'installed' : 'built-in',
+                    e.category,
+                    e.kind,
+                    e.tier,
+                    (e.useCase ?? []).length ? `useCase:${(e.useCase ?? []).join('/')}` : undefined,
+                    e.placement
+                        ? `place as {kind:'${e.placement.clipSourceKind}', ${e.placement.refField}:'${e.id}'}`
+                        : undefined,
+                ].filter(Boolean);
+                return {
+                    uri: `${prefix}/${e.id}`,
+                    name: e.name ?? e.id,
+                    description: facets.join(' · '),
+                    mimeType: 'application/json',
+                };
+            }),
+        };
+    };
+}
+export function registerResources(server, ex) {
+    // ── composition (per project) ────────────────────────────────────
+    server.registerResource('composition', new ResourceTemplate('cueframe://composition/{projectId}', { list: undefined }), {
+        title: 'Composition',
+        description: 'The saved composition for a project (tracks, clips, captions). Read it before editing with apply_composition. URI: cueframe://composition/{projectId}.',
+        mimeType: 'application/json',
+    }, async (uri, { projectId }) => jsonResource(uri, await read(ex, 'getComposition', () => String(projectId))));
+    // ── media (single + collection) ──────────────────────────────────
+    server.registerResource('media', new ResourceTemplate('cueframe://media/{mediaId}', { list: listFrom(ex, 'cueframe://media', 'listMedia') }), {
+        title: 'Media item',
+        description: 'A media item in the library (id, name, duration, processing status). resources/list enumerates the library. URI: cueframe://media/{mediaId}.',
+        mimeType: 'application/json',
+    }, async (uri, { mediaId }) => jsonResourceWithPoster(uri, await read(ex, 'getMedia', () => String(mediaId))));
+    server.registerResource('media-transcript', new ResourceTemplate('cueframe://media/{mediaId}/transcript', { list: undefined }), {
+        title: 'Media transcript',
+        description: 'The transcript (diarized words/segments) for a media item. URI: cueframe://media/{mediaId}/transcript.',
+        mimeType: 'application/json',
+    }, async (uri, { mediaId }) => jsonResource(uri, await read(ex, 'getMediaTranscript', () => String(mediaId))));
+    server.registerResource('media-context', new ResourceTemplate('cueframe://media/{mediaId}/context', { list: undefined }), {
+        title: 'Media authoring context',
+        description: 'Detected faces (subject boxes per frame) + transcript for a media item — the same payload as get_media_context. Use it to align crop intents, captions, timing. URI: cueframe://media/{mediaId}/context.',
+        mimeType: 'application/json',
+    }, async (uri, { mediaId }) => jsonResource(uri, await read(ex, 'getMediaContext', () => String(mediaId))));
+    // ── component (single + collection) ──────────────────────────────
+    server.registerResource('component', new ResourceTemplate('cueframe://component/{componentId}', {
+        list: listComponentsFrom(ex, 'cueframe://component'),
+    }), {
+        title: 'Component catalog',
+        description: "The component catalog: the FULL built-in primitive catalog (96 primitives + 7 scenes — lower-third, cinematic-title, color-grade, the scenes …) PLUS your org-installed custom components. This is 'discover what to build with'. resources/list enumerates EVERY entry with its discovery facets (source/category/kind/tier/useCase) and a placement hint; read one for its full prop schema. NOT only your authored components. URI: cueframe://component/{componentId}.",
+        mimeType: 'application/json',
+    }, async (uri, { componentId }) => jsonResource(uri, await read(ex, 'getComponent', () => String(componentId))));
+    // ── render (per project) ─────────────────────────────────────────
+    server.registerResource('render', new ResourceTemplate('cueframe://render/{projectId}/{renderId}', { list: undefined }), {
+        title: 'Render job',
+        description: 'The status + output of a render job (status, progress, download URL when complete). URI: cueframe://render/{projectId}/{renderId}.',
+        mimeType: 'application/json',
+    }, async (uri, { projectId, renderId }) => jsonResource(uri, await read(ex, 'getRender', (p) => (p === 'renderId' ? String(renderId) : String(projectId)))));
+    // ── brand-kit (single + collection) ──────────────────────────────
+    server.registerResource('brand-kit', new ResourceTemplate('cueframe://brand-kit/{brandKitId}', {
+        list: listFrom(ex, 'cueframe://brand-kit', 'listBrandKits'),
+    }), {
+        title: 'Brand kit',
+        description: 'A brand kit (fonts, colors, logos) bound at render time. resources/list enumerates brand kits. URI: cueframe://brand-kit/{brandKitId}.',
+        mimeType: 'application/json',
+    }, async (uri, { brandKitId }) => jsonResource(uri, await read(ex, 'getBrandKit', () => String(brandKitId))));
+    // ── project (single + collection) ────────────────────────────────
+    server.registerResource('project', new ResourceTemplate('cueframe://project/{projectId}', { list: listFrom(ex, 'cueframe://project', 'listProjects') }), {
+        title: 'Project',
+        description: 'A project (the unit you compose + render into). resources/list enumerates your projects. URI: cueframe://project/{projectId}.',
+        mimeType: 'application/json',
+    }, async (uri, { projectId }) => jsonResource(uri, await read(ex, 'getProject', () => String(projectId))));
+    // ── webhook contract (static reference) ──────────────────────────
+    // A fixed doc (no {id}) — the delivery envelope, Standard-Webhooks signing, the
+    // echo-the-token activation handshake, and every event's `data` shape. This is
+    // 'how do I build a receiver' as data, so an agent never has to guess the
+    // payload/signature/verification or ask a human. Proxies GET /webhooks/events.
+    server.registerResource('webhook-events', 'cueframe://webhook-events', {
+        title: 'Webhook delivery contract',
+        description: "The webhook delivery/signing/verification contract: the POST envelope { event, timestamp, projectId?, data }, the Standard-Webhooks headers + how to verify the secret, the synchronous echo-the-token ownership handshake (and how to recover a pending webhook with verify_webhook), and every subscribable event with its exact `data` fields. Read it BEFORE building a webhook receiver. URI: cueframe://webhook-events.",
+        mimeType: 'application/json',
+    }, async (uri) => jsonResource(uri, await read(ex, 'getWebhookEvents', () => '')));
+}

package/dist/_members/mcp/server.d.ts

@@ -0,0 +1,92 @@
+/**
+ * CueFrame MCP — transport-agnostic core. NO transport import lives here, so
+ * both the stdio entry (index.ts) and the hosted Hono route
+ * (the hosted MCP route) build their server from this one module.
+ *
+ * Layers (all execute through the injected `Executor`, paths from the generated
+ * manifest — single source of truth, drift-gated):
+ *   - curated front-door  → registerCuratedTools  (hand-picked names + guidance)
+ *   - raw expert layer    → registerRawTools      (generic, one tool per op)
+ *   - read resources      → registerResources     (resources.ts)
+ *   - skills-as-prompts   → registerSkillPrompts   (prompts.ts; async, by caller)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Executor } from './core.js';
+export { registerSkillPrompts, __resetSkillCache } from './prompts.js';
+export { SERVER_INSTRUCTIONS } from './generated/harness.js';
+export type { Executor } from './core.js';
+/**
+ * Transport-agnostic telemetry contract. The core emits; the TRANSPORT decides
+ * where it lands (the hosted Convex route ships these to PostHog; stdio passes
+ * no sink and pays nothing). Keeping this a plain callback is what lets the
+ * package stay free of any analytics dependency.
+ */
+/**
+ * A completed tool call. No `errorKind`: every handler here already converts a
+ * throw into an `isError` result before the wrapper sees it, so a thrown-error
+ * class could never be populated — it would be a permanently-null column.
+ */
+export type McpTelemetryEvent = {
+    tool: string;
+    isError: boolean;
+    /**
+     * Preview-attachment outcome, when the tool carries media. `urls` is what the
+     * extractor found in the response; `fetched` is how many actually encoded.
+     *
+     * This rides the SINK, not console.log: the core stays transport-agnostic (it
+     * also ships as a stdio npm package with no Convex in scope), and the hosted
+     * route decides where it lands. urls>0 with fetched===0 is the signature of a
+     * runtime-level failure — it is how the Buffer-in-Convex crash was finally
+     * found, after being invisible behind a silent catch.
+     */
+    preview?: {
+        urls: number;
+        fetched: number;
+    };
+};
+export type McpTelemetrySink = (event: McpTelemetryEvent) => void;
+/**
+ * Operations the RAW expert layer must not register, even though they are in the
+ * manifest. This is a raw-layer property, not a manifest one: the manifest is the
+ * transport-agnostic op SSOT the CURATED layer resolves paths through (`opById`),
+ * so an op dropped from it becomes uncuratable.
+ *
+ * `searchLibrary` — the raw registrar builds its inputSchema from path params +
+ * the request body only, and every argument of GET /v1/media/search is a QUERY
+ * param. `q` is REQUIRED, so the raw tool could not send it and would 400 on
+ * every call — worse than absent, because an agent reads that 400 as "the
+ * feature is broken". The working surface is the curated `search_library`
+ * (internalLoopTools.ts) whose `queryArgs` the adapter threads onto the URL.
+ * DELETE this entry once the generator + this registrar thread query params
+ * (internal issue 2026-08-07 — the Executor
+ * already carries `query`).
+ */
+export declare const RAW_EXCLUDED_OPERATION_IDS: ReadonlySet<string>;
+export declare function registerRawTools(server: McpServer, ex: Executor, onEvent?: McpTelemetrySink): void;
+/** `create_render` → "Create Render". Default title for a curated tool. */
+export declare function titleCase(name: string): string;
+export declare function registerCuratedTools(server: McpServer, ex: Executor, opts?: {
+    waitCapMs?: number;
+    expert?: boolean;
+    onEvent?: McpTelemetrySink;
+}): void;
+export interface BuildServerOpts {
+    executor: Executor;
+    /** Expose the raw `cueframe_api_*` expert layer (one tool per operation). */
+    expert?: boolean;
+    /** SERVER_INSTRUCTIONS harness, if any. */
+    instructions?: string;
+    /** Cap wait_job blocking (ms). Hosted transports set this under the Convex
+     * httpAction limit; stdio leaves it unset (30-min default applies). */
+    waitCapMs?: number;
+    /** Optional telemetry sink. Omitted on stdio; the hosted route supplies one
+     * so agent discovery (initialize) and tool usage are measurable. */
+    onEvent?: McpTelemetrySink;
+}
+export declare function buildServer(opts: BuildServerOpts): McpServer;
+/**
+ * A12 burned names: each dead verb registers as a TOMBSTONE — calling it
+ * hard-errors with the replacement instead of a bare method-not-found, so an
+ * agent with a stale memory of the surface gets re-taught in one round-trip.
+ */
+export declare function registerBurnedTombstones(server: McpServer, onEvent?: McpTelemetrySink): void;

package/dist/_members/mcp/server.js

@@ -0,0 +1,340 @@
+/**
+ * CueFrame MCP — transport-agnostic core. NO transport import lives here, so
+ * both the stdio entry (index.ts) and the hosted Hono route
+ * (services/convex/api/routes/mcp.ts) build their server from this one module.
+ *
+ * Layers (all execute through the injected `Executor`, paths from the generated
+ * manifest — single source of truth, drift-gated):
+ *   - curated front-door  → registerCuratedTools  (hand-picked names + guidance)
+ *   - raw expert layer    → registerRawTools      (generic, one tool per op)
+ *   - read resources      → registerResources     (resources.ts)
+ *   - skills-as-prompts   → registerSkillPrompts   (prompts.ts; async, by caller)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { text, errText, fmtErr, safeParse, withMedia, fetchPreviews, opById, bodySchemaFor, dispatchOp, } from './core.js';
+import { GENERATED_OPERATIONS } from './generated/operations.js';
+import { CURATED_TOOLS } from './curation.js';
+import { registerResources } from './resources.js';
+import { BURNED_NAMES, burnedNameError } from './burnedNames.js';
+import { waitForJob } from './wait.js';
+// Re-exports so a transport (stdio index.ts, or the hosted Convex route) has a
+// single stdio-free import surface: `@cueframe/mcp/server`.
+export { registerSkillPrompts, __resetSkillCache } from './prompts.js';
+export { SERVER_INSTRUCTIONS } from './generated/harness.js';
+/** Emit without ever letting instrumentation surface to the agent. */
+function emit(sink, event) {
+    if (!sink)
+        return;
+    try {
+        sink(event);
+    }
+    catch {
+        /* telemetry is never worth failing a tool call over */
+    }
+}
+/**
+ * Time a tool handler and report the outcome. Returns the handler's result
+ * untouched — an `isError` result is a normal MCP return, not a throw, so both
+ * paths are recorded.
+ */
+async function timed(sink, tool, run) {
+    let isError = false;
+    let extra = {};
+    // A handler enriches the SINGLE event this wrapper emits. Emitting a second
+    // event instead does not work: the hosted route's telemetry is request-scoped
+    // and captures once per call, so the extra one is silently dropped — verified
+    // in PostHog, where preview_urls/preview_fetched came back null on every row
+    // while the images themselves were arriving fine.
+    const report = (e) => {
+        extra = { ...extra, ...e };
+    };
+    try {
+        const res = await run(report);
+        isError = Boolean(res?.isError);
+        return res;
+    }
+    catch (err) {
+        isError = true;
+        throw err;
+    }
+    finally {
+        emit(sink, { tool, isError, ...extra });
+    }
+}
+/**
+ * Operations the RAW expert layer must not register, even though they are in the
+ * manifest. This is a raw-layer property, not a manifest one: the manifest is the
+ * transport-agnostic op SSOT the CURATED layer resolves paths through (`opById`),
+ * so an op dropped from it becomes uncuratable.
+ *
+ * `searchLibrary` — the raw registrar builds its inputSchema from path params +
+ * the request body only, and every argument of GET /v1/media/search is a QUERY
+ * param. `q` is REQUIRED, so the raw tool could not send it and would 400 on
+ * every call — worse than absent, because an agent reads that 400 as "the
+ * feature is broken". The working surface is the curated `search_library`
+ * (internalLoopTools.ts) whose `queryArgs` the adapter threads onto the URL.
+ * DELETE this entry once the generator + this registrar thread query params
+ * (~/brain/Issues/2026-08-07-raw-mcp-tools-drop-query-params.md — the Executor
+ * already carries `query`).
+ */
+export const RAW_EXCLUDED_OPERATION_IDS = new Set(['searchLibrary']);
+export function registerRawTools(server, ex, onEvent) {
+    for (const op of GENERATED_OPERATIONS) {
+        if (RAW_EXCLUDED_OPERATION_IDS.has(op.operationId))
+            continue;
+        const inputSchema = {};
+        for (const p of op.pathParams)
+            inputSchema[p] = z.string().describe(`Path parameter \`${p}\``);
+        const bodySchema = bodySchemaFor(op);
+        if (bodySchema)
+            inputSchema.body = bodySchema.optional().describe('Request body — typed from the OpenAPI spec.');
+        server.registerTool(op.toolName, { title: op.title, description: op.description, inputSchema, annotations: op.annotations }, async (args, extra) => timed(onEvent, op.toolName, async () => {
+            try {
+                return await dispatchOp(ex, op, (p) => args[p], args.body, extra, op.toolName, (res) => text(res.text || `${op.method} ${op.pathTemplate} → ${res.status}`));
+            }
+            catch (err) {
+                return errText(`${op.toolName} failed: ${fmtErr(err)}`);
+            }
+        }));
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Curated front-door — hand-picked names + agent guidance, paths from the
+// manifest, executed through the Executor. `pathArgs` maps friendly arg names
+// to the op's path params; `okFormat`/`okText` shape the success result.
+// The curated tool set itself is the SSOT in curation.ts (drift-gated against
+// the generated manifest by curation.test.ts).
+// ─────────────────────────────────────────────────────────────────────────
+/** `create_render` → "Create Render". Default title for a curated tool. */
+export function titleCase(name) {
+    return name
+        .split('_')
+        .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+        .join(' ');
+}
+export function registerCuratedTools(server, ex, opts) {
+    for (const spec of CURATED_TOOLS) {
+        // Maturity visibility mirror (spec 2026-07-20 §2.0): 'expert'-flagged
+        // entries are hidden from the public listing. Execution gating lives
+        // server-side (capabilities.ts) — this only controls what an agent SEES.
+        if ((spec.maturity ?? 'stable') === 'expert' && !opts?.expert)
+            continue;
+        const op = opById(spec.operationId);
+        const reverse = {};
+        for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {}))
+            reverse[opParam] = friendly;
+        const inputSchema = {};
+        for (const friendly of Object.keys(spec.pathArgs ?? {})) {
+            inputSchema[friendly] = z.string().describe(`${friendly} (path).`);
+        }
+        const bodySchema = bodySchemaFor(op);
+        if (bodySchema)
+            inputSchema.body = bodySchema;
+        // title/annotations: the curated entry overrides the op's method-derived
+        // values PER FIELD, not wholesale. Spreading matters — most curated entries
+        // set only one hint (`{ idempotentHint: true }` on the cancels), and a `??`
+        // would let that partial object replace the derived base, leaving
+        // readOnly/destructive unset. Unset is NOT neutral: the MCP schema defaults
+        // destructiveHint and openWorldHint to TRUE. Gated by index.test.ts.
+        const annotations = { ...op.annotations, ...spec.annotations };
+        server.registerTool(spec.name, { title: spec.title ?? titleCase(spec.name), description: spec.description, inputSchema, annotations }, async (args, extra) => timed(opts?.onEvent, spec.name, async (report) => {
+            const a = args;
+            try {
+                return await dispatchOp(ex, op, (p) => a[reverse[p]], a.body, extra, spec.name, async (res) => {
+                    if (spec.okText)
+                        return text(spec.okText(a));
+                    const json = res.text ? safeParse(res.text) : undefined;
+                    // Pass {} when the response had no body (e.g. a 204) so okFormat is
+                    // null-safe; the bodied tools always return JSON.
+                    const payload = spec.okFormat
+                        ? spec.okFormat(json ?? {}, a)
+                        : res.text || `${op.method} → ${res.status}`;
+                    // Give the agent eyes and ears (spec.preview). Media is ADDITIVE:
+                    // `payload` is the same text block it has always been, so nothing
+                    // downstream changes, and zero usable previews emits no media block at
+                    // all. A preview fetch that fails is dropped silently — a dead
+                    // thumbnail must never fail the tool call it decorates.
+                    // `attach` gates on the response BEFORE any bytes are fetched — a
+                    // withheld preview costs no egress, not just no context.
+                    if (spec.preview && json && (spec.preview.attach?.(json) ?? true)) {
+                        const kind = typeof spec.preview.kind === 'function'
+                            ? spec.preview.kind(json)
+                            : spec.preview.kind ?? 'image';
+                        const urls = spec.preview.urls(json).filter(Boolean);
+                        const data = await fetchPreviews(urls, spec.preview.cap ?? 12);
+                        report({ preview: { urls: urls.length, fetched: data.length } });
+                        if (data.length)
+                            return withMedia(payload, data.map((d) => ({ data: d, kind })));
+                    }
+                    return text(payload);
+                });
+            }
+            catch (err) {
+                return errText(`${spec.name} failed: ${fmtErr(err)}`);
+            }
+        }));
+    }
+    registerWaitJob(server, ex, opts?.waitCapMs, opts?.onEvent);
+    registerPreviewCard(server, ex, opts?.onEvent);
+}
+/**
+ * `preview_card` — see ONE authored card before it goes anywhere near a composition.
+ *
+ * There was no way to look at a card without adding it to a composition, shelling
+ * it with a motion preset, and previewing the whole frame. Twenty cards were
+ * authored blind in a single session; type overflowing the frame edge was the
+ * direct result — nobody could see it until the final render.
+ *
+ * It needs NO new endpoint. `preview_frame` already accepts an INLINE composition
+ * (`PreviewFrameRequest.composition`, evidence.ts:66), so this synthesizes the
+ * smallest legal one-card composition and reuses that op — same billing, same
+ * bake→capture seam, same content-addressed stills.
+ */
+function registerPreviewCard(server, ex, onEvent) {
+    const op = opById('previewFrame');
+    server.registerTool('preview_card', {
+        title: 'Preview Card',
+        description: 'Render ONE authored card on its own and SEE it, before placing it in a composition. Pass the same `html` (+ optional `tokens`) you would put in a {kind:"card"} clip; you get the still back as an image. Use this while writing a card — it is the fast loop for catching type that overflows the frame, a headline that collides with a logo, or tokens that did not resolve. Sized to the format you name, so what you see is what that aspect ratio will show. To judge MOTION rather than layout, shell the card with a motion preset and use preview_clip.',
+        inputSchema: {
+            projectId: z.string().describe('projectId (path) — the card is rendered inline; nothing is persisted to the project.'),
+            html: z.string().min(1).describe('The card markup, exactly as it would appear in a {kind:"card"} clip source.'),
+            tokens: z
+                .record(z.string())
+                .optional()
+                .describe('Token substitutions the html references (e.g. brand colours, fonts). Same shape as the clip source `tokens`.'),
+            aspectRatio: z
+                .enum(['16:9', '9:16', '1:1', '4:5'])
+                .optional()
+                .describe('Frame to size the card into. Default 9:16 — a card that fits 16:9 often overflows vertical.'),
+        },
+        // Renders inline and persists nothing — the read-only stance curation.ts
+        // already takes for preview_frame. Stated in full: an omitted hint is not
+        // neutral (destructiveHint/openWorldHint default TRUE in the schema).
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args, extra) => timed(onEvent, 'preview_card', async (report) => {
+        const a = args;
+        // The smallest legal composition (Composition.required = v/format/tracks;
+        // clip.required = id/startTime/duration/source; card source needs kind+html).
+        const composition = {
+            v: 1,
+            format: { aspectRatio: a.aspectRatio ?? '9:16', fps: 30, resolution: 'fhd' },
+            tracks: [
+                {
+                    id: 'card',
+                    kind: 'overlay',
+                    contents: [
+                        {
+                            id: 'card-1',
+                            startTime: 0,
+                            duration: 2,
+                            source: { kind: 'card', html: a.html, ...(a.tokens ? { tokens: a.tokens } : {}) },
+                        },
+                    ],
+                },
+            ],
+        };
+        try {
+            return await dispatchOp(ex, op, () => a.projectId, { composition, timestamps: [1] }, extra, 'preview_card', async (res) => {
+                const json = res.text ? safeParse(res.text) : undefined;
+                const urls = (Array.isArray(json?.stills) ? json.stills : []).map((st) => st?.url);
+                const data = await fetchPreviews(urls, 2);
+                report({ preview: { urls: urls.filter(Boolean).length, fetched: data.length } });
+                const payload = res.text || `previewed card (${a.aspectRatio ?? '9:16'})`;
+                return data.length
+                    ? withMedia(payload, data.map((d) => ({ data: d, kind: 'image' })))
+                    : text(payload);
+            });
+        }
+        catch (err) {
+            return errText(`preview_card failed: ${fmtErr(err)}`);
+        }
+    }));
+}
+function registerWaitJob(server, ex, waitCapMs, onEvent) {
+    server.registerTool('wait_job', {
+        title: 'Wait for Job',
+        // Polls status; changes nothing. Idempotent by construction — the whole
+        // continuation contract is "call again with the same arguments".
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Wait for a long-running job and return the resolved result — a BOUNDED long-poll. Polls the job status (render / compose / consult / clip-suggestions / verify) and blocks up to the transport window (30s on the hosted transport); if the job is still running at the window it returns a `Still running` continuation — call wait_job again with the same arguments to keep waiting (the job keeps executing server-side; nothing is lost between calls). Call this right after compose / create_render / consult / suggest_briefs / score_composition / preview_component. For event-driven fan-out, create_webhook delivers the terminal instead.',
+        inputSchema: {
+            kind: z
+                .enum(['render', 'suggestions', 'compose', 'verify', 'preview', 'brand_kit_extract', 'consult'])
+                .describe('What to wait on: a render job, a compose job, a consult advisory, AI clip-suggestion analysis, or a generic async job (verify / preview / brand-kit extract — the kind is named in the enqueue receipt).'),
+            id: z
+                .string()
+                .describe('kind="render": renderId. kind="compose": composeJobId. kind="consult": the consultJobId from the consult receipt (surfaces the advisory envelope — assessment, proposals, principles). kind="suggestions": mediaItemId. kind="verify"/"preview"/"brand_kit_extract": the jobId from the enqueue receipt.'),
+            projectId: z
+                .string()
+                .optional()
+                .describe('Required when kind="render", "compose", or "consult".'),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(1000)
+                .max(30 * 60 * 1000)
+                .optional()
+                .describe('Maximum wait in ms (default 30 min for render/compose, 5 min for suggestions).'),
+        },
+    }, async (args) => timed(onEvent, 'wait_job', async (report) => {
+        const kind = args.kind;
+        if ((kind === 'render' || kind === 'compose' || kind === 'consult') && !args.projectId) {
+            return errText(`wait_job(kind="${kind}") requires a projectId.`);
+        }
+        const defaultCap = kind === 'suggestions' ? 5 * 60 * 1000 : 30 * 60 * 1000;
+        // waitCapMs caps the hosted transport well under Convex's httpAction time
+        // limit (a 30-min synchronous poll would be killed mid-wait); the agent's
+        // own timeoutMs still applies below it. Unset (stdio) → no extra cap.
+        const requested = args.timeoutMs ?? defaultCap;
+        const deadline = Date.now() + (waitCapMs ? Math.min(requested, waitCapMs) : requested);
+        const res = await waitForJob(ex, kind, args.id, args.projectId, deadline);
+        if (!res.ok)
+            return errText(res.text);
+        // An async tool's pixels arrive HERE, not at the enqueue call:
+        // preview_component's 202 carries only a jobId, so the still it produces
+        // has to surface on the wait. Same url adapter.ts:578 inlines as an image.
+        if (res.mediaUrls?.length) {
+            const data = await fetchPreviews(res.mediaUrls, 4);
+            report({ preview: { urls: res.mediaUrls.length, fetched: data.length } });
+            if (data.length)
+                return withMedia(res.text, data.map((d) => ({ data: d, kind: 'image' })));
+        }
+        return text(res.text);
+    }));
+}
+export function buildServer(opts) {
+    const server = new McpServer({ name: 'cueframe', version: '0.1.0' }, opts.instructions ? { instructions: opts.instructions } : undefined);
+    registerCuratedTools(server, opts.executor, {
+        waitCapMs: opts.waitCapMs,
+        expert: opts.expert,
+        onEvent: opts.onEvent,
+    });
+    registerBurnedTombstones(server, opts.onEvent);
+    registerResources(server, opts.executor);
+    if (opts.expert)
+        registerRawTools(server, opts.executor, opts.onEvent);
+    // NOTE: protocol-level traffic (initialize / tools-list / prompts / resources)
+    // is NOT observed here. It is captured once at the transport via the public
+    // `onmessage` hook, which sees every inbound JSON-RPC method without reaching
+    // into SDK internals. This function only instruments what the transport
+    // cannot see: per-tool duration and outcome.
+    return server;
+}
+/**
+ * A12 burned names: each dead verb registers as a TOMBSTONE — calling it
+ * hard-errors with the replacement instead of a bare method-not-found, so an
+ * agent with a stale memory of the surface gets re-taught in one round-trip.
+ */
+export function registerBurnedTombstones(server, onEvent) {
+    for (const b of BURNED_NAMES) {
+        server.registerTool(b.name, {
+            title: `${titleCase(b.name)} (retired)`,
+            description: `RETIRED (2026-07 verb cutover) — use ${b.replacement}. ${b.reason}`,
+            // A tombstone only ever throws. Announcing it as read-only and
+            // closed-world keeps a stale agent from being made to confirm a
+            // "destructive" call that does nothing (schema defaults both to true).
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async () => timed(onEvent, b.name, async () => errText(burnedNameError(b))));
+    }
+}

package/dist/_members/mcp/wait.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `wait_job` — block until a long-running job reaches a terminal state, by
+ * POLLING its status endpoint through the Executor. Unified across transports:
+ * the same poll loop works for stdio (network) and hosted (in-process), so the
+ * blocking-SSE path is gone (the agent only ever sees the terminal result, so
+ * polling is functionally equivalent; `create_webhook` is the event-driven path
+ * for fan-out). Pure + side-effect-free (clock/sleep injectable) so it unit-tests
+ * without a server.
+ */
+import { type Executor } from './core.js';
+export type WaitResult = {
+    ok: boolean;
+    text: string;
+    /** True when the wait window expired with the job still running — a
+     *  CONTINUATION, not an error: the caller re-invokes wait_job to keep
+     *  waiting (bounded long-poll; plan 2026-07-06-bounded-api-jobs). */
+    stillRunning?: boolean;
+    /** Image urls to attach as MCP image blocks. An async tool's pixels arrive at
+     *  wait_job, not at the enqueue call, so this is where they must surface —
+     *  preview_component's own 202 carries only a jobId. Same treatment
+     *  adapter.ts:578 already gives this url on the ai-SDK path. */
+    mediaUrls?: string[];
+};
+export type WaitKind = 'render' | 'compose' | 'suggestions' | 'verify' | 'preview' | 'brand_kit_extract' | 'consult';
+export interface WaitDeps {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Poll interval; overridable for fast tests. */
+    pollMs?: number;
+    /** Reserved headroom for one status invoke (overshoot guard); test override. */
+    invokeBudgetMs?: number;
+}
+/**
+ * Poll a job's status op until terminal or the deadline. 4xx → fail loud
+ * immediately; 5xx/transient → keep polling; 2xx non-terminal → sleep + retry.
+ */
+export declare function waitForJob(ex: Executor, kind: WaitKind, id: string, projectId: string | undefined, deadline: number, deps?: WaitDeps): Promise<WaitResult>;