@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/mcp/adapter.js

@@ -1,771 +0,0 @@
-/**
- * Director-onto-MCP adapter — turns the curated SSOT (curation.ts) into an
- * `ai`-SDK `ToolSet` the Director's author LLM can drive over the real `/v1`
- * network surface (the dogfood), instead of the in-process `buildDirectorTools`
- * store. One `ai` `tool()` per phase-1 curated name; each `execute()` runs the
- * op through the injected `Executor` (server.ts:registerCuratedTools is the
- * parallel SSOT consumer for the MCP-server transport).
- *
- * Correctness contracts preserved from buildTools.ts:107-200:
- *   (a) execute() returns errors as a JSON-STRING tool output, never throws —
- *       the LLM must SEE the error as tool output.
- *   (b) images never leave execute() as content-shaped objects (T4).
- *   (c/d) role filtering + dedup/progress/heartbeat stay external to tool-building.
- */
-import { z } from 'zod';
-import { tool } from 'ai';
-import { invokeOp, opById, bodySchemaFor, isOk, apiErrorFrom, fmtErr, safeParse, sniffImageMediaType, fetchPreviews, } from './core.js';
-import { CURATED_TOOLS } from './curation.js';
-import { INTERNAL_LOOP_TOOLS } from './internalLoopTools.js';
-import { waitForJob } from './wait.js';
-// Re-exported for surface MIRRORS (e.g. @cueframe/local-harness's
-// buildLocalToolSet): a mirror must serve the SAME names, descriptions and
-// operationIds as this adapter — importing the specs is the only non-drifting
-// way to do that.
-export { CURATED_TOOLS } from './curation.js';
-export { INTERNAL_LOOP_TOOLS } from './internalLoopTools.js';
-/**
- * B6 (spec 2026-07-11-preview-capture-unification §B6): INFRA-class error codes
- * the author/designer LLM cannot fix — there is no tool it could call to create
- * a missing scratch or revive a dead session. Returning these as Contract-3(a)
- * tool output makes the model flail (prod dogfood: ×49 scratch_not_found renders
- * ending in design-lock, 49 calls from the cause). A CLOSED set: adaptable
- * errors (bad params, over budget, timestamp_out_of_bounds, component compile
- * errors) keep the tool-output contract.
- */
-const INFRA_TOOL_ERROR_CODES = 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',
-]);
-/**
- * The typed sentinel for infra-class tool failures. Thrown from a curated
- * tool's execute(); the AI SDK catches it into a `tool-error` step part, so the
- * throw ALONE changes nothing — the agent loop (authoring/agent.ts) detects the
- * sentinel STRUCTURALLY (name+infra, no package import — mcp↔authoring stay
- * decoupled per Constraint 3(d)), halts the run, and rethrows; the director
- * (mcpSurface) maps it to a nonRetryable ApplicationFailure so the candidate
- * fails loud with the REAL code instead of a design-lock 49 renders later.
- */
-export class InfraToolError extends Error {
-    code;
-    infra = true;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'InfraToolError';
-    }
-}
-/** Structural guard (mirror of the authoring-side local guard). */
-export function isInfraToolError(v) {
-    return (v instanceof Error &&
-        v.name === 'InfraToolError' &&
-        v.infra === true &&
-        typeof v.code === 'string');
-}
-/**
- * Classify a non-2xx op response: an infra-class code returns the sentinel to
- * THROW; anything else returns null (caller keeps the Contract-3(a) JSON-string
- * return). Pure + exported for tests. Parses the error envelope itself so it
- * has no dependency on ApiError's shape.
- */
-export 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)));
-}
-/** Default per-run in-loop budget — mirrors director.ts:282/290. */
-const DEFAULT_BUDGETS = { captures: 10, verifies: 3, styleViews: 4 };
-/** Async-job poll defaults: a verify renders eval beats + runs the vision judge
- *  (~1-3 min); a preview is one still (~10-60s). One generous ceiling for both. */
-const JOB_POLL_MS = 4_000;
-const JOB_TIMEOUT_MS = 240_000;
-/**
- * Poll the generic jobs resource (GET /v1/jobs/{id}) until terminal or the
- * deadline. Mirrors wait.ts's loop, but returns the RAW job JSON so each
- * caller formats its own kind-specific result (verify → scores text,
- * preview → result.url still). 4xx while polling → failed (fail loud);
- * transient 5xx → keep polling.
- */
-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, undefined);
-        if (!isOk(res.status)) {
-            if (res.status >= 400 && res.status < 500) {
-                return { outcome: 'failed', pollError: fmtErr(apiErrorFrom(res)) };
-            }
-            // transient 5xx: fall through to sleep + retry
-        }
-        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);
-    }
-}
-/** Format a terminal verify job as the scores text the author acts on —
- *  mirrors wait.ts's verify terminal formatting. */
-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 ? ` — ${v.critique}` : ''}`);
-            }
-        }
-    }
-    if (typeof r.critique === 'string' && r.critique.length > 0) {
-        lines.push(`\nWorst-first critique: ${r.critique}`);
-    }
-    lines.push('\nFix the lowest criterion via apply_composition, then re-verify.');
-    return lines.join('\n');
-}
-/**
- * Stream a presigned still to base64 — mirrors inLoopCapture.ts:173-174.
- *
- * `btoa` + chunking rather than `Buffer.from(buf).toString('base64')`: this
- * adapter now also builds tool sets inside the DESKTOP WEBVIEW (the local /v1
- * lane), where `Buffer` does not exist. `btoa` is present in Node ≥16, the
- * Convex isolate and every browser; the 8k chunk keeps `String.fromCharCode`
- * under its argument limit on multi-MB stills. Byte-identical output.
- */
-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(''));
-}
-/**
- * Friendly path-arg names the adapter injects from `opts.session` and strips from
- * the tool schema. Any other path arg (e.g. `mediaItemId`) stays LLM-supplied.
- */
-const SESSION_PATH_ARGS = new Set(['projectId', 'sessionId']);
-/** Resolve a session-managed path arg from opts.session, else undefined. */
-function sessionPathValue(friendly, opts) {
-    if (!opts?.session)
-        return undefined;
-    if (friendly === 'projectId')
-        return opts.session.projectId;
-    if (friendly === 'sessionId')
-        return opts.session.sessionId;
-    return undefined;
-}
-/**
- * Compute the effective request body for a tool. Under a session, every tool
- * that reads or writes "the composition being worked on" stamps
- * `body.session_id` so the op targets the session SCRATCH:
- *  - `apply_composition` writes the scratch;
- *  - `verify_composition` judges it. Before this, verifies resolved the
- *    project's ACTIVE row — the session author's edits were invisible to its
- *    own in-loop judge (the scratch-blind class, prod 2026-07-14; render_frame
- *    had the same hole and stamps in buildRenderFrameTool).
- * Every other tool passes its body through untouched (bodyless stay bodyless).
- */
-const SESSION_STAMPED_TOOLS = 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;
-}
-/**
- * Vision inlining, shared by `render_frame` (whole-composition stills) and
- * `preview_component` (one graphic still). Fetch each presigned PNG url → base64
- * and return them RAW as `string[]`. Finding 3: a 2xx that yields ZERO usable
- * urls must NOT return an empty `string[]` — that becomes an empty
- * `{type:'content', value:[]}` block the model API can reject — so return a
- * JSON-string `{note}` (a TEXT tool result) instead. The base64 bytes never leave
- * execute() content-shaped (Constraint 3(b)); they become a vision block only in
- * `imageVisionModelOutput`.
- */
-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;
-}
-/**
- * The `toModelOutput` shared by the vision tools: a base64 `string[]` becomes
- * image content blocks (the pixels the model SEES); anything else (an
- * `{error}` / `{note}` JSON string) renders as TEXT. The media type is SNIFFED
- * per image from its magic bytes (`sniffImageMediaType`), not hardcoded — PNG
- * stills stay png, JPEG exemplars label jpeg, so the adapter never mislabels the
- * bytes it inlines (and does not inherit buildTools.ts:37's hardcoded image/jpeg).
- */
-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),
-    };
-}
-/**
- * `render_frame` vision special-case (T4). Renders whole-composition still(s) in
- * the warm box, fetches each presigned PNG, and inlines it as base64. The bytes
- * are returned RAW as `string[]` from execute() and only become a vision block in
- * `toModelOutput` — a content-shaped object leaving execute() would be JSON-
- * stringified by the AI SDK (~50k text tokens/image → window overflow) AND the
- * model still couldn't see the pixels (Constraint 3(b)).
- */
-function buildRenderFrameTool(spec, ex, budget, opts) {
-    const op = opById(spec.operationId);
-    const fetchImage = opts?.fetchImage ?? defaultFetchImage;
-    // Path args (projectId/sessionId) come from the scratch session — never LLM-managed.
-    const reverse = {};
-    for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
-        reverse[opParam] = friendly;
-    }
-    const mapArg = (p) => sessionPathValue(reverse[p], opts) ?? undefined;
-    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) => {
-            // Budget (T5): a capture costs COGS — over budget returns a tool-output error, never throws.
-            if (++budget.used.captures > budget.caps.captures) {
-                return JSON.stringify({
-                    error: `capture budget exhausted; you have used all ${budget.caps.captures} in-loop renders — 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 } : {}),
-            });
-            // B6: an INFRA-class code (dead scratch/session) is unfixable by the model —
-            // throw the sentinel (loop-halt + loud candidate failure), never tool output.
-            const infra = infraToolErrorFromResponse(res);
-            if (infra)
-                throw infra;
-            // Contract 3(a): any OTHER non-2xx is RETURNED as a JSON-string, never thrown / never an image.
-            if (!isOk(res.status))
-                return JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
-            const json = safeParse(res.text);
-            // The capture budget was already charged above; a zero-still 2xx returns a
-            // {note} (charge stands) rather than an empty content block (Finding 3).
-            return inlineStillsOrNote((json?.stills ?? []).map((s) => s.url), fetchImage, 'no stills returned for the requested timestamps');
-        },
-        toModelOutput: imageVisionModelOutput,
-    });
-}
-/**
- * `preview_component` vision special-case. Renders ONE org-installed component as
- * a single still in the warm box and returns a presigned PNG `{ url }` — the
- * designer's author→preview→fix loop for a graphic. WITHOUT this the generic tool
- * path returns the `{url}` JSON as TEXT and the designer LLM never SEES the
- * pixels; here we inline it exactly like render_frame (base64 `string[]` from
- * execute → a vision block only in `toModelOutput`). Un-budgeted (a preview is not
- * charged against the in-loop capture cap; the agent's step cap is the backstop).
- * A non-2xx — the 422 `component_does_not_compile` / `component_runtime_error` the
- * designer self-fixes from — is RETURNED as a JSON `{error}` string, never thrown, never an image
- * (Constraint 3(a)); a 2xx with no url returns a `{note}` (Finding 3), never an
- * empty content block. The body schema (componentId + params/width/height) comes
- * from the manifest, so a param rename fails loud at codegen, not at runtime.
- */
-function buildPreviewComponentTool(spec, ex, opts) {
-    const op = opById(spec.operationId);
-    const fetchImage = opts?.fetchImage ?? defaultFetchImage;
-    // Path args (projectId/sessionId) come from the scratch session — never LLM-managed.
-    const reverse = {};
-    for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
-        reverse[opParam] = friendly;
-    }
-    const shape = {};
-    for (const friendly of Object.keys(spec.pathArgs ?? {})) {
-        // Session-managed path args are injected from opts.session — never exposed.
-        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);
-            // Contract 3(a): a non-2xx (422 component_does_not_compile /
-            // component_runtime_error / 5xx) is RETURNED as a JSON-string {error}, never
-            // thrown / never an image — the designer reads the compile-or-runtime error
-            // message and fixes the source via create_component. EXCEPT infra-class
-            // codes (B6): a dead session is not author-fixable — sentinel throw.
-            {
-                const infra = infraToolErrorFromResponse(res);
-                if (infra)
-                    throw infra;
-            }
-            if (!isOk(res.status))
-                return JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
-            const json = safeParse(res.text);
-            // Async-jobs migration: the op ENQUEUES a preview job and returns a
-            // receipt. The designer has no wait_job, so BLOCK here until terminal and
-            // inline the resulting still (a sync {url} response — older API — still
-            // takes the fast path).
-            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');
-                    // The author-fixable compile/runtime message rides job.error — return
-                    // it as {error} text so the designer fixes the source via create_component.
-                    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) / 1000)}s — proceed, or re-preview later`,
-                    });
-                }
-                url = done.job?.result?.url;
-            }
-            return inlineStillsOrNote([url], fetchImage, 'component preview returned no still url');
-        },
-        toModelOutput: imageVisionModelOutput,
-    });
-}
-/**
- * `verify_composition` blocking special-case. The API op ENQUEUES the judge and
- * returns a receipt ("call wait_job…") — but wait_job is NOT on the curated
- * author/designer surface, so via the generic tool path the agent can never
- * read its own score (the 2026-07-07 prod LBO run called verify once and the
- * verdict evaporated). Here the tool blocks until the verify job is terminal
- * and returns the per-criterion scores + worst-first critique as TEXT — one
- * call, one verdict, same contract as the in-process score_composition.
- * Budgeted (a verify = eval-beat renders + the vision judge).
- */
-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 — 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 — 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));
-            {
-                // B6: infra-class enqueue failure (dead session) — sentinel throw.
-                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) {
-                // Older sync API shape (scores inline) — pass it through unchanged.
-                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) / 1000)}s — 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);
-        },
-    });
-}
-/**
- * `view_style_reference` vision special-case (T3, brand-kit-from-inspiration).
- * Presigns the BOUND brand kit's inspiration exemplar frames (optionally scoped to
- * one motif) and inlines them as base64 `string[]` — the reference pixels the maker
- * conditions on and the judge grades against. The kit id comes from `opts.brandKitId`
- * (the project's bound kit, threaded by the director), NEVER the LLM — so the tool
- * cannot peek at another project's kit. No kit bound ⇒ a `{note}` (not an error: the
- * kit is optional). Budgeted (`styleViews`): the vision window is finite, so past the
- * cap it returns a tool-output error (never throws — Constraint 3(a)) so the maker
- * designs from what it has already seen. Same base64→vision contract as render_frame.
- */
-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 — no style reference available' });
-            }
-            if (++budget.used.styleViews > budget.caps.styleViews) {
-                return JSON.stringify({ error: `style-reference budget exhausted (${budget.caps.styleViews} views) — 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,
-    });
-}
-const WAIT_KINDS = [
-    'render',
-    'compose',
-    'suggestions',
-    'verify',
-    'preview',
-    'brand_kit_extract',
-    'consult',
-];
-/**
- * `wait_job` — the adapter twin of server.ts:registerWaitJob, over the SAME
- * `waitForJob` poll loop (one implementation, two transports). It is not a
- * generic single-op tool: `waitForJob` picks the status op PER KIND (wait.ts
- * `KINDS`), so `spec.operationId` is representative only and is never invoked
- * here.
- *
- * BOUNDED on purpose. The MCP transport caps this with `waitCapMs` because a
- * 30-minute synchronous poll outlives the request; the adapter's callers are
- * Convex actions and Temporal activities with the same problem, so the ceiling
- * is `opts.jobPoll.timeoutMs` (default `JOB_TIMEOUT_MS`) and the caller's own
- * `timeoutMs` may only lower it. Hitting the window is a CONTINUATION, not a
- * failure — the returned text says to call again with the same arguments.
- */
-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 — 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;
-            };
-            // The project-scoped kinds cannot be polled without a projectId — say so
-            // instead of issuing a request to `/projects/undefined/...`.
-            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 } : {}) }
-                : undefined);
-            // An async tool's PIXELS arrive here, not at the enqueue call (a 202 carries
-            // only a jobId). Inline them the same way spec.preview does on the generic
-            // path, or the agent judges a preview it was only told about.
-            if (res.mediaUrls?.length) {
-                const images = await fetchPreviews(res.mediaUrls, 12, fetchImage ? { fetchOne: fetchImage } : undefined);
-                if (images.length) {
-                    finish(res.text, res.ok);
-                    return { __preview: true, text: res.text, images };
-                }
-            }
-            return finish(res.text, res.ok);
-        },
-        toModelOutput: previewVisionModelOutput,
-    });
-}
-/** Build one `ai` tool from a curated spec, executing through `ex`. */
-function buildOneTool(spec, ex, budget, opts) {
-    if (spec.name === 'render_frame')
-        return buildRenderFrameTool(spec, ex, budget, opts);
-    // wait_job polls a DIFFERENT status op per kind — it has no single op to
-    // dispatch, so the generic path cannot build it.
-    if (spec.name === 'wait_job')
-        return buildWaitJobTool(spec, ex, opts);
-    // preview_component returns a presigned PNG `{ url }`; inline it so the designer
-    // LLM SEES the graphic (the generic path below would return the url as TEXT).
-    if (spec.name === 'preview_component')
-        return buildPreviewComponentTool(spec, ex, opts);
-    // verify_composition enqueues the judge; block until terminal and return the
-    // SCORES (the surface has no wait_job — a receipt is a verdict the LLM can
-    // never read).
-    if (spec.name === 'verify_composition')
-        return buildVerifyCompositionTool(spec, ex, budget, opts);
-    // view_style_reference presigns the BOUND kit's exemplar frames and inlines
-    // them as vision blocks (the reference pixels) — the generic path would return
-    // the {exemplars:[{url}]} JSON as TEXT and the maker would never SEE the frames.
-    if (spec.name === 'view_style_reference')
-        return buildViewStyleReferenceTool(spec, ex, budget, opts);
-    const op = opById(spec.operationId);
-    const onProgress = opts?.onProgress;
-    // friendly input arg name → op path-param name, reversed for mapArg lookup.
-    const reverse = {};
-    for (const [friendly, opParam] of Object.entries(spec.pathArgs ?? {})) {
-        reverse[opParam] = friendly;
-    }
-    const shape = {};
-    for (const friendly of Object.keys(spec.pathArgs ?? {})) {
-        // Session-managed path args are injected from opts.session — never exposed.
-        if (opts?.session && SESSION_PATH_ARGS.has(friendly))
-            continue;
-        shape[friendly] = z.string().describe(`${friendly} (path).`);
-    }
-    // Query filters (curation queryArgs): optional strings threaded onto the
-    // request URL — the arg name IS the query-param name. Without this a
-    // description teaching a filter returned the UNFILTERED page silently.
-    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;
-    // K4 examples are authored for the SESSION-injected surface (path args
-    // hidden). On a sessionless build the path args are part of the schema, and
-    // Anthropic VALIDATES every example against input_schema — one example
-    // missing a required `projectId` 400s the entire request ("tools.N.custom:
-    // Example at index 0 is invalid"). Keep only examples that carry every
-    // exposed path arg; with a session none are exposed, so all examples pass
-    // through unchanged (the Director path is unaffected).
-    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] !== undefined));
-    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) => {
-            // Budgets live in the special-cased tools (render_frame / verify_composition);
-            // every generic read/mutate tool (apply_composition, get_media_context, …) is
-            // un-budgeted.
-            const toolCallId = `tc_${crypto.randomUUID().slice(0, 8)}`;
-            // Progress: tool-call (before the network op — buildTools.ts:131-134).
-            onProgress?.({
-                type: 'tool-call',
-                agent: 'router',
-                toolName: spec.name,
-                args,
-                toolCallId,
-                timestamp: Date.now(),
-            });
-            const queryPairs = Object.keys(spec.queryArgs ?? {})
-                .filter((qArg) => args[qArg] !== undefined && 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), undefined, queryPairs.length > 0 ? queryPairs.join('&') : undefined);
-            const ok = isOk(res.status);
-            const json = ok && res.text ? safeParse(res.text) : undefined;
-            // Contract 3(a): a non-2xx is RETURNED as a JSON-string tool output, NOT thrown.
-            const output = ok
-                ? spec.okText
-                    ? spec.okText(args)
-                    : spec.okFormat
-                        ? spec.okFormat(json ?? {}, args)
-                        : res.text || `${op.method} → ${res.status}`
-                : JSON.stringify({ error: fmtErr(apiErrorFrom(res)) });
-            // Progress: tool-result (message capped at 200 chars — buildTools.ts:160).
-            onProgress?.({
-                type: 'tool-result',
-                agent: 'router',
-                toolName: spec.name,
-                success: ok,
-                message: output.slice(0, 200),
-                toolCallId,
-                timestamp: Date.now(),
-            });
-            // spec.preview — the generic-path twin of server.ts:202: attach the
-            // pixels the JSON already links (preview_frame stills, checkpoint
-            // storyboards) so the model judges what it can SEE. ADDITIVE (text
-            // unchanged), gated by `attach` BEFORE any bytes move, and a failed
-            // fetch drops silently — a dead thumbnail never fails the call it
-            // decorates. Audio previews stay URL-as-text (tool results carry
-            // image blocks only).
-            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') {
-                    // fetchPreviews (not defaultFetchImage): isolate-safe base64 — the
-                    // Convex V8 runtime has no Buffer — plus the byte budget and cache.
-                    const images = await fetchPreviews(spec.preview.urls(json), spec.preview.cap ?? 12, opts?.fetchImage ? { fetchOne: opts.fetchImage } : undefined);
-                    if (images.length)
-                        return { __preview: true, text: output, images };
-                }
-            }
-            return output;
-        },
-        ...(spec.preview ? { toModelOutput: previewVisionModelOutput } : {}),
-    });
-}
-/**
- * Build an `ai` `ToolSet` from the curated SSOT, filtered to the caller's
- * `allowedNames`. Uses the REAL generated manifest (via opById) so a
- * missing/renamed operationId fails loud — that is the drift signal.
- */
-export function buildCuratedToolSet(ex, opts) {
-    const allowed = new Set(opts.allowedNames);
-    // One budget per build → one budget spans the whole author run (T5). A fresh
-    // ToolSet is built per author invocation, so counters reset per run — matching
-    // the in-process per-run caps (director.ts:282/290).
-    const budget = {
-        caps: opts?.budgets ?? DEFAULT_BUDGETS,
-        used: { captures: 0, verifies: 0, styleViews: 0 },
-    };
-    const tools = {};
-    // Internal loop entries FIRST, then the public curated set — the in-loop
-    // session-scoped names (A11/A12-internal) resolve even though they left the
-    // client surface at the 2026-07 verb cutover. `preview_component` exists in
-    // BOTH (public = sessionless managed box; internal = the run's own box) —
-    // internal wins here because this builder only serves the in-loop surface.
-    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;
-}