@cueframe/kernel 0.0.1

package/dist/mcp/adapter.d.ts

@@ -0,0 +1 @@
+export * from "../_members/mcp/adapter.js";

package/dist/mcp/adapter.js

@@ -0,0 +1,670 @@
+import {
+  waitForJob
+} from "../chunk-MMEJ3Y7E.js";
+import {
+  apiErrorFrom,
+  bodySchemaFor,
+  fetchPreviews,
+  fmtErr,
+  invokeOp,
+  isOk,
+  opById,
+  safeParse,
+  sniffImageMediaType
+} from "../chunk-SIGGQRY2.js";
+import {
+  CURATED_TOOLS
+} from "../chunk-HI4UTTPS.js";
+import "../chunk-7GISRVON.js";
+import "../chunk-KF5ETMKB.js";
+import {
+  tool
+} from "../chunk-VIVQHIGZ.js";
+import "../chunk-2ESYSVXG.js";
+
+// ../mcp/src/adapter.ts
+import { z } from "zod";
+
+// ../mcp/src/internalLoopTools.ts
+var INTERNAL_LOOP_TOOLS = [
+  {
+    name: "render_frame",
+    // Sessionless — the same op the public `preview_frame` uses.
+    operationId: "previewFrame",
+    pathArgs: { projectId: "id" },
+    description: "Render still(s) of the WHOLE composition at the given timestamps, returning presigned image(s) \u2014 the in-loop full-composition preview. `body.timestamps` is an array of clip-relative SECONDS: pass EVERY beat you want to inspect in ONE call \u2014 a call is flat-cost and one budget unit however many timestamps it carries, and all render in a single pass (a contact sheet), so never spend calls one frame at a time. Stills are content-addressed: re-rendering an unchanged composition is free, and the judge grades the EXACT frames you looked at. (One component instead of the whole composition? use preview_component.)",
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "verify_composition",
+    operationId: "scoreComposition",
+    pathArgs: { projectId: "id" },
+    description: "Queue the server-side judge for this composition \u2014 ASYNC: returns a jobId (the judge samples eval beats, renders them, and grades editorial/spatial/brand/caption). The in-loop wrapper blocks until terminal and returns per-criterion scores 0\u201310, a weighted composite, and a worst-first critique; fix the lowest criterion via apply_composition and re-verify. Idempotent per composition state.",
+    annotations: { idempotentHint: true }
+  },
+  {
+    name: "preview_component",
+    operationId: "previewComponent",
+    pathArgs: { projectId: "id" },
+    description: "Queue a MOTION-clip render of ONE org-installed component \u2014 ASYNC; the in-loop wrapper blocks until terminal and returns the clip. It is the SAME content-addressed bake the production render composites, so what you preview is literally the object that ships, and previewing an unchanged component is free. Failures carry typed codes (component_does_not_compile / component_runtime_error) with the sanitized author-fixable message \u2014 read it, fix the tsxSource via create_component, and re-preview. Idempotent per (componentId, params, dims).",
+    annotations: { idempotentHint: true }
+  },
+  {
+    name: "commit_session",
+    operationId: "commitComposeSession",
+    pathArgs: { projectId: "id", sessionId: "sessionId" },
+    description: "Promote this run's scratch composition to the project's active composition. DENIED to ensemble author/designer candidates (only the WINNER saves downstream); buildable only via an explicit allowedNames."
+  },
+  {
+    // ADAPTER-ONLY (brand-kit-from-inspiration, spec D9: the public MCP gains NO
+    // new tools). The director's author/designer loops reach it via allowedNames
+    // + `opts.brandKitId` (the director injects the bound kit); a public hosted
+    // caller has no way to name a kit, so the {id} path param would resolve to
+    // String(undefined) → POST /v1/brand-kits/undefined/exemplars → always 404.
+    // Living here (not in CURATED_TOOLS) keeps it OFF the public server —
+    // server.ts:registerCuratedTools iterates CURATED_TOOLS only — while
+    // buildCuratedToolSet iterates INTERNAL_LOOP_TOOLS + CURATED_TOOLS, so the
+    // designer/author allow-lists still build it. The kit id comes from
+    // opts.brandKitId, never the LLM, so it has no path/query args here.
+    name: "view_style_reference",
+    operationId: "getBrandKitExemplars",
+    description: "SEE the brand kit's inspiration exemplar frames (the reference pixels). Call with {motifId} to see the frames a specific motif was observed in before authoring that graphic. Frames are the ground truth the judge grades against \u2014 match their language, not the house style."
+  },
+  // ── One-vocabulary merge (2026-08-07) ───────────────────────────────────
+  // `get_context`, `search_library` and `analyze_transcript` are the names the
+  // DESKTOP agent already speaks; the /v1 twins landed in tasks 2-4 so one tool
+  // vocabulary can serve local and cloud through one Executor seam. They live
+  // HERE, not in CURATED_TOOLS, on purpose: server.ts:registerCuratedTools
+  // iterates CURATED_TOOLS procedurally, so membership there IS publication on
+  // the hosted MCP server. These three are internal-lane only until the desktop
+  // merge lands and the surface is deliberately widened. `buildCuratedToolSet`
+  // iterates INTERNAL_LOOP_TOOLS + CURATED_TOOLS (adapter.ts), so the editor
+  // agent and the Director build them without server.ts changing at all.
+  {
+    name: "get_context",
+    operationId: "getProjectContext",
+    pathArgs: { projectId: "id" },
+    description: "OPEN THE PROJECT in one read: the active composition (format + markers hoisted), the org's media pool with a `hasTranscript` flag per item, the first transcribed item's word-timed transcript, and the brand kit bound to the project. Call it FIRST \u2014 it replaces the get_composition + get_media_context + get_profile opening sequence, so the whole orientation costs one round-trip. `composition: null` is the EMPTY STATE of a freshly created project, not an error (mint one with new_composition); 404 means no such project for your org. Transcript BODIES are not inlined per media item \u2014 for a second item read GET /v1/media/{id}/transcript, and its faces/beat grids with get_media_context.",
+    annotations: { readOnlyHint: true }
+  },
+  {
+    name: "search_library",
+    operationId: "searchLibrary",
+    // The op takes NO path params and NO body — `q`/`limit` are QUERY params,
+    // and `queryArgs` is the only mechanism that puts them on the wire (the raw
+    // registrar drops query params entirely, which is why its raw twin is
+    // excluded in server.ts). Without this block the tool would call
+    // GET /v1/media/search with no `q` and 400 on every invocation.
+    queryArgs: {
+      q: 'REQUIRED. What the moment should LOOK like, in plain language \u2014 describe the IMAGE, not the words spoken ("wide shot of a speaker at a whiteboard", "hands on a keyboard"). Omitting it is a 400.',
+      limit: "Maximum moments to return. Default 10, maximum 25."
+    },
+    description: "FIND MOMENTS IN YOUR OWN FOOTAGE by describing what they look like. The query is embedded with the same CLIP model that embedded every indexed frame, so it matches on VISUAL content \u2014 including shots nobody talks about, which is exactly where transcript search fails. Returns time-ranged moments best-first: feed `mediaId` + `startSec`/`endSec` straight into apply_composition as a clip. To SEE a hit rather than trust its score, place it and call preview_frame at its `startSec` \u2014 a result row carries the media item's poster, never a frame of the matched moment. `indexing` is COVERAGE, not emptiness \u2014 true whenever some of the org's footage is not in the visual index yet (media that predates it, or still processing), and it can be true ALONGSIDE results; read those as \"the best moments among what we have looked at so far\". Empty `results` with `indexing: true` is a state, not a failure. TIMING: the text encoder scales to zero, so the first search after an idle period can take up to ~90s while it cold-starts \u2014 a documented wait, not a hang. Reach for search_resources instead when you need STOCK rather than the org's own footage.",
+    annotations: { readOnlyHint: true }
+    // NO `preview` block, deliberately. `thumbUrl` is the ITEM's poster frame
+    // (schemas.ts: "the media item's poster"), not the matched moment's — and a
+    // result row is a CHUNK, so a 10-hit search over ONE video inlines the same
+    // unrelated poster ten times, uncaptioned. That is the confabulation class
+    // previews exist to fix, running backwards: the agent would judge moments
+    // against a frame none of them contains. The right eye on a hit is
+    // preview_frame at its startSec, which the description points at.
+  },
+  {
+    name: "analyze_transcript",
+    operationId: "analyzeTranscript",
+    pathArgs: { mediaItemId: "id" },
+    description: "Ask ONE editorial question of a media item's transcript and get the answer as text. `body.task`: 'summary' (what is actually said, plus the takeaways), 'chapters' (where the subject changes), or 'highlights' (the moments that stand alone as a short). Pass `body.window` {startSec, endSec} to analyse one slice; omit it for the whole thing. PRECISION \u2014 READ THIS BEFORE YOU CUT: timestamps are ABSOLUTE seconds from the start of the media and every one is verified against the transcript before you see it (a fabricated timestamp fails the call rather than shipping), but they are LINE-START markers roughly 15s apart, so a boundary can sit up to 15s BEFORE the moment you asked for. Treat every span as APPROXIMATE \u2014 use it to LOCATE the moment, then refine the in/out against the word timings from get_context / get_media_context. Feeding a raw span straight into a clip trim WILL start it mid-sentence. This is a METERED LLM call, not a read: it bills on measured token spend. 422 `transcript_too_long` (over ~100k characters, roughly two hours of speech) means narrow it with `window` \u2014 it refuses rather than silently summarising only the first half; 422 `media_no_transcript` means no speech on file (or none inside your window) \u2014 get_media_context shows the transcript state."
+  },
+  // `wait_job` is the ONE infrastructure verb on the adapter surface. The hosted
+  // MCP server registers its own copy procedurally (server.ts:registerWaitJob),
+  // so it must NEVER appear in CURATED_TOOLS — registerCuratedTools would then
+  // register the name twice and the whole server would fail to build. It lives
+  // here so `buildCuratedToolSet` can build it too: without it an allow-list
+  // carrying an ASYNC verb (create_render, score_composition, generate_media)
+  // hands the agent a receipt it can never resolve — the 2026-07-07 prod run
+  // that scored into the void. `operationId` is the representative status op;
+  // buildWaitJobTool resolves the real one PER KIND (wait.ts KINDS).
+  {
+    name: "wait_job",
+    operationId: "getJob",
+    title: "Wait for Job",
+    description: "Wait for a long-running job and return the resolved result \u2014 a BOUNDED long-poll. Polls the job status (render / compose / consult / clip-suggestions / verify / preview / brand-kit extract) and blocks up to the caller's window; if the job is still running when the window closes it returns a `Still running` continuation \u2014 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 create_render / compose / consult / suggest_briefs / score_composition / preview_component \u2014 the enqueue call returns only a receipt, and the RESULT (download URL, scores, critique) arrives here.",
+    annotations: { readOnlyHint: true }
+  }
+];
+
+// ../mcp/src/adapter.ts
+var INFRA_TOOL_ERROR_CODES = /* @__PURE__ */ new Set([
+  "scratch_not_found",
+  "session_not_found",
+  "session_not_ready",
+  // Version-gate timeout: the box's daemon/subscription is dead — no tool call
+  // can revive it (2026-07-12: 234 dead renders, two 24-min blind designer
+  // attempts before design-lock).
+  "session_version_timeout"
+]);
+var InfraToolError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "InfraToolError";
+  }
+  infra = true;
+};
+function isInfraToolError(v) {
+  return v instanceof Error && v.name === "InfraToolError" && v.infra === true && typeof v.code === "string";
+}
+function infraToolErrorFromResponse(res) {
+  if (isOk(res.status)) return null;
+  let code;
+  try {
+    code = JSON.parse(res.text)?.error?.code;
+  } catch {
+    return null;
+  }
+  if (typeof code !== "string" || !INFRA_TOOL_ERROR_CODES.has(code)) return null;
+  return new InfraToolError(code, fmtErr(apiErrorFrom(res)));
+}
+var DEFAULT_BUDGETS = { captures: 10, verifies: 3, styleViews: 4 };
+var JOB_POLL_MS = 4e3;
+var JOB_TIMEOUT_MS = 24e4;
+async function pollJobToTerminal(ex, jobId, jobPoll) {
+  const op = opById("getJob");
+  const sleep = jobPoll?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const pollMs = jobPoll?.pollMs ?? JOB_POLL_MS;
+  const timeoutMs = jobPoll?.timeoutMs ?? JOB_TIMEOUT_MS;
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const res = await invokeOp(ex, op, () => jobId, void 0);
+    if (!isOk(res.status)) {
+      if (res.status >= 400 && res.status < 500) {
+        return { outcome: "failed", pollError: fmtErr(apiErrorFrom(res)) };
+      }
+    } else {
+      const job = safeParse(res.text);
+      const s = String(job?.status ?? "");
+      if (s === "succeeded") return { outcome: "succeeded", job };
+      if (s === "failed") return { outcome: "failed", job };
+    }
+    if (Date.now() + pollMs >= deadline) return { outcome: "timeout" };
+    await sleep(pollMs);
+  }
+}
+function formatVerifyResult(job) {
+  const r = job?.result ?? {};
+  const lines = ["Verify complete."];
+  if (typeof r.composite === "number") lines.push(`Composite score: ${r.composite}`);
+  if (r.perCriterion && typeof r.perCriterion === "object") {
+    for (const [criterion, v] of Object.entries(r.perCriterion)) {
+      if (typeof v?.score === "number") {
+        lines.push(`- ${criterion}: ${v.score}${v?.critique ? ` \u2014 ${v.critique}` : ""}`);
+      }
+    }
+  }
+  if (typeof r.critique === "string" && r.critique.length > 0) {
+    lines.push(`
+Worst-first critique: ${r.critique}`);
+  }
+  lines.push("\nFix the lowest criterion via apply_composition, then re-verify.");
+  return lines.join("\n");
+}
+async function defaultFetchImage(url) {
+  const buf = await (await fetch(url)).arrayBuffer();
+  const bytes = new Uint8Array(buf);
+  const chunks = [];
+  for (let i = 0; i < bytes.length; i += 8192) {
+    chunks.push(String.fromCharCode(...bytes.subarray(i, i + 8192)));
+  }
+  return btoa(chunks.join(""));
+}
+var SESSION_PATH_ARGS = /* @__PURE__ */ new Set(["projectId", "sessionId"]);
+function sessionPathValue(friendly, opts) {
+  if (!opts?.session) return void 0;
+  if (friendly === "projectId") return opts.session.projectId;
+  if (friendly === "sessionId") return opts.session.sessionId;
+  return void 0;
+}
+var SESSION_STAMPED_TOOLS = /* @__PURE__ */ new Set(["apply_composition", "verify_composition"]);
+function injectSession(spec, args, opts) {
+  if (opts?.session && SESSION_STAMPED_TOOLS.has(spec.name)) {
+    return { ...args.body ?? {}, session_id: opts.session.sessionId };
+  }
+  return args.body;
+}
+async function inlineStillsOrNote(urls, fetchImage, emptyNote) {
+  const out = [];
+  for (const u of urls) if (u) out.push(await fetchImage(u));
+  if (out.length === 0) return JSON.stringify({ note: emptyNote });
+  return out;
+}
+function imageVisionModelOutput({ output }) {
+  return Array.isArray(output) ? {
+    type: "content",
+    value: output.map((data) => ({
+      type: "image-data",
+      mediaType: sniffImageMediaType(data),
+      data
+    }))
+  } : {
+    type: "text",
+    value: typeof output === "string" ? output : JSON.stringify(output)
+  };
+}
+function isPreviewAugmented(v) {
+  return !!v && typeof v === "object" && v.__preview === true;
+}
+function previewVisionModelOutput({ output }) {
+  if (isPreviewAugmented(output)) {
+    return {
+      type: "content",
+      value: [
+        { type: "text", text: output.text },
+        ...output.images.map((data) => ({
+          type: "image-data",
+          mediaType: sniffImageMediaType(data),
+          data
+        }))
+      ]
+    };
+  }
+  return {
+    type: "text",
+    value: typeof output === "string" ? output : JSON.stringify(output)
+  };
+}
+function buildRenderFrameTool(spec, ex, budget, opts) {
+  const op = opById(spec.operationId);
+  const fetchImage = opts?.fetchImage ?? defaultFetchImage;
+  const reverse = {};
+  for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
+    reverse[opParam] = friendly;
+  }
+  const mapArg = (p) => sessionPathValue(reverse[p], opts) ?? void 0;
+  return tool({
+    description: spec.description,
+    // composition is omitted; session_id (stamped below) makes the server render
+    // the session SCRATCH — the composition this agent is actually editing. The
+    // box cutover left this body bare and previewFrame fell back to the project's
+    // ACTIVE row, so the designer refined against stills WITHOUT its own edits
+    // until the capture budget refused (prod 2026-07-14, rs7fanev…).
+    inputSchema: z.object({ body: z.object({ timestamps: z.array(z.number()).min(1) }) }),
+    // K4: teach BATCHED inspection — several timestamps bracketing the edited
+    // window in ONE call (the measured anti-pattern: repeated single-frame
+    // renders, each costing a capture from the same budget).
+    inputExamples: [{ input: { body: { timestamps: [14.2, 14.8, 15.6] } } }],
+    execute: async (args) => {
+      if (++budget.used.captures > budget.caps.captures) {
+        return JSON.stringify({
+          error: `capture budget exhausted; you have used all ${budget.caps.captures} in-loop renders \u2014 finalize from your current composition.`
+        });
+      }
+      const res = await invokeOp(ex, op, mapArg, {
+        timestamps: args.body.timestamps,
+        // Vision-bound shrink (2026-07-17 trace audit): this tool is the AGENT's
+        // eyes — full-res PNG stills base64'd into context cost +10k tokens per
+        // look and slower renders. The judge grades jpeg/0.5/70; the agent sees
+        // the same. The PUBLIC preview_frame (human preview) stays full-res —
+        // this body rides the dedicated internal-loop builder only.
+        imageFormat: "jpeg",
+        scale: 0.5,
+        jpegQuality: 70,
+        ...opts?.session ? { session_id: opts.session.sessionId } : {}
+      });
+      const infra = infraToolErrorFromResponse(res);
+      if (infra) throw infra;
+      if (!isOk(res.status)) return JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
+      const json = safeParse(res.text);
+      return inlineStillsOrNote(
+        (json?.stills ?? []).map((s) => s.url),
+        fetchImage,
+        "no stills returned for the requested timestamps"
+      );
+    },
+    toModelOutput: imageVisionModelOutput
+  });
+}
+function buildPreviewComponentTool(spec, ex, opts) {
+  const op = opById(spec.operationId);
+  const fetchImage = opts?.fetchImage ?? defaultFetchImage;
+  const reverse = {};
+  for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
+    reverse[opParam] = friendly;
+  }
+  const shape = {};
+  for (const friendly of Object.keys(spec.pathArgs ?? {})) {
+    if (opts?.session && SESSION_PATH_ARGS.has(friendly)) continue;
+    shape[friendly] = z.string().describe(`${friendly} (path).`);
+  }
+  const bodySchema = bodySchemaFor(op);
+  if (bodySchema) shape.body = bodySchema;
+  return tool({
+    description: spec.description,
+    inputSchema: z.object(shape),
+    execute: async (args) => {
+      const res = await invokeOp(
+        ex,
+        op,
+        (p) => sessionPathValue(reverse[p], opts) ?? args[reverse[p]],
+        args.body
+      );
+      {
+        const infra = infraToolErrorFromResponse(res);
+        if (infra) throw infra;
+      }
+      if (!isOk(res.status)) return JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
+      const json = safeParse(res.text);
+      let url = json?.url;
+      if (!url && json?.jobId) {
+        const done = await pollJobToTerminal(ex, json.jobId, opts?.jobPoll);
+        if (done.outcome === "failed") {
+          const err = done.pollError ?? (done.job?.error ? `${done.job.error.code ?? "preview_failed"}: ${done.job.error.message ?? ""}` : "preview job failed");
+          return JSON.stringify({ error: err });
+        }
+        if (done.outcome === "timeout") {
+          return JSON.stringify({
+            note: `component preview still rendering after ${Math.round((opts?.jobPoll?.timeoutMs ?? JOB_TIMEOUT_MS) / 1e3)}s \u2014 proceed, or re-preview later`
+          });
+        }
+        url = done.job?.result?.url;
+      }
+      return inlineStillsOrNote(
+        [url],
+        fetchImage,
+        "component preview returned no still url"
+      );
+    },
+    toModelOutput: imageVisionModelOutput
+  });
+}
+function buildVerifyCompositionTool(spec, ex, budget, opts) {
+  const op = opById(spec.operationId);
+  const onProgress = opts?.onProgress;
+  const reverse = {};
+  for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
+    reverse[opParam] = friendly;
+  }
+  const shape = {};
+  for (const friendly of Object.keys(spec.pathArgs ?? {})) {
+    if (opts?.session && SESSION_PATH_ARGS.has(friendly)) continue;
+    shape[friendly] = z.string().describe(`${friendly} (path).`);
+  }
+  const bodySchema = bodySchemaFor(op);
+  if (bodySchema) shape.body = bodySchema;
+  return tool({
+    description: "Score the current composition on the judge's own rubric \u2014 BLOCKS until the scores are ready (1-3 min) and returns per-criterion scores 0-10 (editorial / spatial / brand / caption), the weighted composite, and a worst-first critique. Fix the lowest criterion via apply_composition, then re-verify. Do NOT apply/render while it runs.",
+    inputSchema: z.object(shape),
+    execute: async (args) => {
+      if (++budget.used.verifies > budget.caps.verifies) {
+        return JSON.stringify({
+          error: `verify budget exhausted; you have used all ${budget.caps.verifies} in-loop verifies \u2014 commit your best composition.`
+        });
+      }
+      const toolCallId = `tc_${crypto.randomUUID().slice(0, 8)}`;
+      onProgress?.({
+        type: "tool-call",
+        agent: "router",
+        toolName: spec.name,
+        args,
+        toolCallId,
+        timestamp: Date.now()
+      });
+      const finish = (output, ok) => {
+        onProgress?.({
+          type: "tool-result",
+          agent: "router",
+          toolName: spec.name,
+          success: ok,
+          message: output.slice(0, 200),
+          toolCallId,
+          timestamp: Date.now()
+        });
+        return output;
+      };
+      const res = await invokeOp(
+        ex,
+        op,
+        (p) => sessionPathValue(reverse[p], opts) ?? args[reverse[p]],
+        injectSession(spec, args, opts)
+      );
+      {
+        const infra = infraToolErrorFromResponse(res);
+        if (infra) throw infra;
+      }
+      if (!isOk(res.status)) {
+        return finish(JSON.stringify({ error: fmtErr(apiErrorFrom(res)) }), false);
+      }
+      const receipt = safeParse(res.text);
+      if (!receipt?.jobId) {
+        return finish(res.text || "verify returned no result", true);
+      }
+      const done = await pollJobToTerminal(ex, receipt.jobId, opts?.jobPoll);
+      if (done.outcome === "succeeded") return finish(formatVerifyResult(done.job), true);
+      if (done.outcome === "timeout") {
+        return finish(
+          JSON.stringify({
+            error: `verify still running after ${Math.round((opts?.jobPoll?.timeoutMs ?? JOB_TIMEOUT_MS) / 1e3)}s \u2014 proceed with your best judgment; the final judge scores the cut regardless.`
+          }),
+          false
+        );
+      }
+      const err = done.pollError ?? (done.job?.error ? `${done.job.error.code ?? "verify_failed"}: ${done.job.error.message ?? ""}` : "verify job failed");
+      return finish(JSON.stringify({ error: err }), false);
+    }
+  });
+}
+function buildViewStyleReferenceTool(spec, ex, budget, opts) {
+  const op = opById(spec.operationId);
+  const fetchImage = opts?.fetchImage ?? defaultFetchImage;
+  return tool({
+    description: spec.description,
+    inputSchema: z.object({
+      motifId: z.string().optional().describe("Filter to the frames this motif was observed in.")
+    }),
+    execute: async (args) => {
+      if (!opts?.brandKitId) {
+        return JSON.stringify({ note: "no brand kit bound to this project \u2014 no style reference available" });
+      }
+      if (++budget.used.styleViews > budget.caps.styleViews) {
+        return JSON.stringify({ error: `style-reference budget exhausted (${budget.caps.styleViews} views) \u2014 design from what you have seen` });
+      }
+      const res = await invokeOp(
+        ex,
+        op,
+        () => opts.brandKitId,
+        { ...args.motifId ? { motifId: args.motifId } : {}, limit: 6 }
+      );
+      {
+        const infra = infraToolErrorFromResponse(res);
+        if (infra) throw infra;
+      }
+      if (!isOk(res.status)) return JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
+      const json = safeParse(res.text);
+      return inlineStillsOrNote(
+        (json?.exemplars ?? []).map((e) => e.url),
+        fetchImage,
+        "kit has no exemplar frames"
+      );
+    },
+    toModelOutput: imageVisionModelOutput
+  });
+}
+var WAIT_KINDS = [
+  "render",
+  "compose",
+  "suggestions",
+  "verify",
+  "preview",
+  "brand_kit_extract",
+  "consult"
+];
+function buildWaitJobTool(spec, ex, opts) {
+  const onProgress = opts?.onProgress;
+  const capMs = opts?.jobPoll?.timeoutMs ?? JOB_TIMEOUT_MS;
+  const fetchImage = opts?.fetchImage;
+  return tool({
+    description: spec.description,
+    inputSchema: z.object({
+      kind: z.enum(WAIT_KINDS).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 \u2014 the kind is named in the enqueue receipt)."
+      ),
+      id: z.string().describe("The job id from the enqueue call (renderId / composeJobId / jobId / mediaItemId for suggestions)."),
+      projectId: z.string().optional().describe("Required for render / compose / consult (their status routes are project-scoped)."),
+      timeoutMs: z.number().optional().describe(`Maximum wait in ms. Capped at ${capMs}; a longer value is clamped, not honoured.`)
+    }),
+    execute: async (args) => {
+      const toolCallId = `tc_${crypto.randomUUID().slice(0, 8)}`;
+      onProgress?.({
+        type: "tool-call",
+        agent: "router",
+        toolName: spec.name,
+        args,
+        toolCallId,
+        timestamp: Date.now()
+      });
+      const finish = (output, ok) => {
+        onProgress?.({
+          type: "tool-result",
+          agent: "router",
+          toolName: spec.name,
+          success: ok,
+          message: output.slice(0, 200),
+          toolCallId,
+          timestamp: Date.now()
+        });
+        return output;
+      };
+      if (!args.projectId && (args.kind === "render" || args.kind === "compose" || args.kind === "consult")) {
+        return finish(
+          JSON.stringify({ error: `wait_job(kind="${args.kind}") requires a projectId.` }),
+          false
+        );
+      }
+      const deadline = Date.now() + Math.min(args.timeoutMs ?? capMs, capMs);
+      const res = await waitForJob(
+        ex,
+        args.kind,
+        args.id,
+        args.projectId,
+        deadline,
+        opts?.jobPoll?.sleep || opts?.jobPoll?.pollMs ? { ...opts.jobPoll?.sleep ? { sleep: opts.jobPoll.sleep } : {}, ...opts.jobPoll?.pollMs ? { pollMs: opts.jobPoll.pollMs } : {} } : void 0
+      );
+      if (res.mediaUrls?.length) {
+        const images = await fetchPreviews(
+          res.mediaUrls,
+          12,
+          fetchImage ? { fetchOne: fetchImage } : void 0
+        );
+        if (images.length) {
+          finish(res.text, res.ok);
+          return { __preview: true, text: res.text, images };
+        }
+      }
+      return finish(res.text, res.ok);
+    },
+    toModelOutput: previewVisionModelOutput
+  });
+}
+function buildOneTool(spec, ex, budget, opts) {
+  if (spec.name === "render_frame") return buildRenderFrameTool(spec, ex, budget, opts);
+  if (spec.name === "wait_job") return buildWaitJobTool(spec, ex, opts);
+  if (spec.name === "preview_component") return buildPreviewComponentTool(spec, ex, opts);
+  if (spec.name === "verify_composition") return buildVerifyCompositionTool(spec, ex, budget, opts);
+  if (spec.name === "view_style_reference") return buildViewStyleReferenceTool(spec, ex, budget, opts);
+  const op = opById(spec.operationId);
+  const onProgress = opts?.onProgress;
+  const reverse = {};
+  for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
+    reverse[opParam] = friendly;
+  }
+  const shape = {};
+  for (const friendly of Object.keys(spec.pathArgs ?? {})) {
+    if (opts?.session && SESSION_PATH_ARGS.has(friendly)) continue;
+    shape[friendly] = z.string().describe(`${friendly} (path).`);
+  }
+  for (const [qArg, qDesc] of Object.entries(spec.queryArgs ?? {})) {
+    shape[qArg] = z.string().optional().describe(qDesc);
+  }
+  const bodySchema = bodySchemaFor(op);
+  if (bodySchema) shape.body = bodySchema;
+  const exposedPathArgs = Object.keys(spec.pathArgs ?? {}).filter(
+    (friendly) => !(opts?.session && SESSION_PATH_ARGS.has(friendly))
+  );
+  const schemaSafeExamples = spec.inputExamples?.filter(
+    (exm) => exposedPathArgs.every((a) => exm.input[a] !== void 0)
+  );
+  return tool({
+    description: spec.description,
+    inputSchema: z.object(shape),
+    // K4: worked examples from the curated spec (apply_composition teaches the
+    // targeted patch). Serialized as Anthropic input_examples; the provider
+    // adds the advanced-tool-use beta itself.
+    ...schemaSafeExamples?.length ? { inputExamples: schemaSafeExamples } : {},
+    execute: async (args) => {
+      const toolCallId = `tc_${crypto.randomUUID().slice(0, 8)}`;
+      onProgress?.({
+        type: "tool-call",
+        agent: "router",
+        toolName: spec.name,
+        args,
+        toolCallId,
+        timestamp: Date.now()
+      });
+      const queryPairs = Object.keys(spec.queryArgs ?? {}).filter((qArg) => args[qArg] !== void 0 && args[qArg] !== null && args[qArg] !== "").map((qArg) => `${encodeURIComponent(qArg)}=${encodeURIComponent(String(args[qArg]))}`);
+      const res = await invokeOp(
+        ex,
+        op,
+        (p) => sessionPathValue(reverse[p], opts) ?? args[reverse[p]],
+        injectSession(spec, args, opts),
+        void 0,
+        queryPairs.length > 0 ? queryPairs.join("&") : void 0
+      );
+      const ok = isOk(res.status);
+      const json = ok && res.text ? safeParse(res.text) : void 0;
+      const output = ok ? spec.okText ? spec.okText(args) : spec.okFormat ? spec.okFormat(json ?? {}, args) : res.text || `${op.method} \u2192 ${res.status}` : JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
+      onProgress?.({
+        type: "tool-result",
+        agent: "router",
+        toolName: spec.name,
+        success: ok,
+        message: output.slice(0, 200),
+        toolCallId,
+        timestamp: Date.now()
+      });
+      if (ok && spec.preview && json && (spec.preview.attach?.(json) ?? true)) {
+        const kind = typeof spec.preview.kind === "function" ? spec.preview.kind(json) : spec.preview.kind ?? "image";
+        if (kind === "image") {
+          const images = await fetchPreviews(
+            spec.preview.urls(json),
+            spec.preview.cap ?? 12,
+            opts?.fetchImage ? { fetchOne: opts.fetchImage } : void 0
+          );
+          if (images.length) return { __preview: true, text: output, images };
+        }
+      }
+      return output;
+    },
+    ...spec.preview ? { toModelOutput: previewVisionModelOutput } : {}
+  });
+}
+function buildCuratedToolSet(ex, opts) {
+  const allowed = new Set(opts.allowedNames);
+  const budget = {
+    caps: opts?.budgets ?? DEFAULT_BUDGETS,
+    used: { captures: 0, verifies: 0, styleViews: 0 }
+  };
+  const tools = {};
+  for (const spec of [...INTERNAL_LOOP_TOOLS, ...CURATED_TOOLS]) {
+    if (!allowed.has(spec.name)) continue;
+    if (tools[spec.name]) continue;
+    tools[spec.name] = buildOneTool(spec, ex, budget, opts);
+  }
+  return tools;
+}
+export {
+  CURATED_TOOLS,
+  INTERNAL_LOOP_TOOLS,
+  InfraToolError,
+  buildCuratedToolSet,
+  infraToolErrorFromResponse,
+  isInfraToolError
+};

package/dist/mcp/core.d.ts

@@ -0,0 +1 @@
+export * from "../_members/mcp/core.js";