@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/mcp/burnedNames.js

@@ -1,73 +0,0 @@
-/**
- * Burned tool names (amendment A12, plan 2026-07-10-flow-verbs) — names that
- * DIED in the verb cutover and may NEVER be reused for a different job: a
- * reused name is a silent behavior change for every old caller.
- *
- * Each burned name registers as a TOMBSTONE tool: calling it hard-errors with
- * the replacement (an agent with a stale memory of the surface gets taught,
- * not a bare method-not-found), and the tools/list entry itself documents the
- * cutover. The gate in curation.test.ts ("burned names stay dead") asserts no
- * curated/infrastructure tool ever takes a burned name back, that the
- * internal-loop overlap stays exactly the documented four, and that every
- * tombstone's replacement is a live tool.
- */
-export const BURNED_NAMES = [
-    {
-        name: "create_composition",
-        replacement: "compose",
-        reason: "renamed — one flagship verb: compose {briefId | fromComposition | suggestionId} starts the Director run.",
-    },
-    {
-        name: "verify_composition",
-        replacement: "score_composition",
-        reason: "renamed — the standalone sighted check SCORES a composition and returns a Checkpoint packet.",
-    },
-    {
-        name: "render_frame",
-        replacement: "preview_frame",
-        reason: "renamed — the evidence family says preview_*; render_* is the paid finisher family.",
-    },
-    {
-        name: "trigger_suggestions",
-        replacement: "suggest_briefs",
-        reason: "renamed — the analysis mints kind-'clip' Briefs, each composable via compose {briefId}.",
-    },
-    {
-        name: "resume_compose",
-        replacement: "resume",
-        reason: "renamed — checkpoint-addressed: resume(checkpointId, {decision}) answers the packet, not the job.",
-    },
-    {
-        name: "open_session",
-        replacement: "score_composition / preview_frame / preview_component",
-        reason: "sessions dissolved — each op manages its own warm box server-side, billed flat per operation.",
-    },
-    {
-        name: "close_session",
-        replacement: "(nothing — the managed box reaps itself on idle)",
-        reason: "sessions dissolved — there is no client-held box to close.",
-    },
-    {
-        name: "commit_session",
-        replacement: "apply_composition",
-        reason: "scratch-vs-active dissolved into composition versioning — there is nothing left to commit.",
-    },
-    {
-        name: "new_video",
-        replacement: "new_composition",
-        reason: "renamed — every verb in the family says composition; only the mint said video.",
-    },
-    {
-        name: "list_components",
-        replacement: "list_catalog",
-        reason: "renamed — 'component' on the wire means installed-only; the verb returns the whole catalog.",
-    },
-    {
-        name: "adopt_candidate",
-        replacement: "apply_composition",
-        reason: "removed — adopt a consult proposal by applying its composition (the client stays the author).",
-    },
-];
-export function burnedNameError(b) {
-    return `'${b.name}' was RETIRED in the 2026-07 verb cutover and will never come back. Use ${b.replacement}. (${b.reason})`;
-}

package/dist/_members/mcp/core.js

@@ -1,390 +0,0 @@
-import { ApiError, adviseError } from '@cueframe/sdk';
-import * as bodySchemas from '@cueframe/sdk/zod';
-import { GENERATED_OPERATIONS } from './generated/operations.js';
-import { MCP_PAYMENT_REQUIRED_CODE, isX402PaymentRequired, extractPaymentFromMeta, encodePaymentSignature, } from './x402Meta.js';
-export function text(s) {
-    return { content: [{ type: 'text', text: s }] };
-}
-export function errText(s) {
-    return { content: [{ type: 'text', text: s }], isError: true };
-}
-/**
- * The JSON payload of a tool result. Since `content` gained image/audio blocks,
- * callers can no longer assume `content[0].text` — but every result still leads
- * with its text block (see `withMedia`), so this is the stable accessor.
- */
-export function firstText(r) {
-    const b = r.content.find((c) => c.type === 'text');
-    return b?.text ?? '';
-}
-/**
- * Sniff an image's media type from its base64 magic bytes.
- *
- * Authoritative, never hardcoded: the declared media type must match the pixels
- * or the model API rejects the whole message. Server-rendered stills are PNG,
- * but `view_style_reference` exemplars are USER-UPLOADED frames written as JPEG
- * (`frame-01.jpg`) — hardcoding `image/png` mislabeled every inspiration kit's
- * exemplars and crashed the designer the instant it looked at the reference
- * (2026-07-16, waverly-mercury card-lane bench). Unknown ⇒ png (the server default).
- *
- * Lives here rather than in adapter.ts so the ai-SDK path and the MCP-server path
- * share ONE sniffer — the bug above must not be re-introduced on the new surface.
- */
-/**
- * base64 ⇄ bytes WITHOUT Node's `Buffer`.
- *
- * The hosted MCP runs in Convex's V8 runtime, which has the web APIs (`btoa`,
- * `atob`, `Uint8Array`) but NOT Node globals. `Buffer.from(...)` threw there on
- * every preview — AFTER a successful fetch — and `fetchAsBase64`'s catch
- * swallowed it, so `mcp_preview` reported `{urls:2, fetched:0}` and the whole
- * eyes-and-ears surface silently did nothing in production while 187 tests
- * passed under Node. Web APIs only, so one implementation serves both runtimes.
- */
-function bytesToBase64(bytes) {
-    // PREFERRED: the TC39 standard method (proposal-arraybuffer-base64, now in MDN).
-    // Skips the binary-string round trip entirely, so there is no argument-count
-    // limit to trip over. Feature-detected because Convex's runtime version is not
-    // ours to pin.
-    const std = bytes.toBase64;
-    if (typeof std === 'function')
-        return std.call(bytes);
-    // FALLBACK: chunked String.fromCharCode + btoa — the documented pattern for
-    // Workers-like runtimes. 8192 is the size those guides use: passing a whole
-    // 100KB thumbnail (or even 32768 bytes) as spread arguments can exceed the
-    // engine's max-argument limit and throw. Our tests use 4-byte fixtures, so a
-    // too-large chunk would never have failed in CI — only in production, on a
-    // real image, silently, exactly like the Buffer bug this replaced.
-    let bin = '';
-    const CHUNK = 8192;
-    for (let i = 0; i < bytes.length; i += CHUNK) {
-        bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
-    }
-    return btoa(bin);
-}
-/**
- * Decode only the leading bytes — enough for a magic-number sniff.
- *
- * `atob` is STRICTER than the `Buffer.from(s,'base64')` this replaced: it throws
- * on a prefix whose length is not a multiple of 4, and on stray padding. So take
- * a 4-aligned prefix and never let a malformed string propagate — an unsniffable
- * blob falls back to the caller's default rather than failing the tool call.
- */
-function base64Head(base64, n = 12) {
-    const want = Math.ceil((n * 4) / 3);
-    const aligned = base64.slice(0, Math.min(base64.length, want) & ~3);
-    if (!aligned)
-        return new Uint8Array(0);
-    let bin;
-    try {
-        bin = atob(aligned);
-    }
-    catch {
-        return new Uint8Array(0);
-    }
-    const out = new Uint8Array(Math.min(n, bin.length));
-    for (let i = 0; i < out.length; i++)
-        out[i] = bin.charCodeAt(i);
-    return out;
-}
-function ascii(b, start, end) {
-    let s = '';
-    for (let i = start; i < end && i < b.length; i++)
-        s += String.fromCharCode(b[i]);
-    return s;
-}
-export function sniffImageMediaType(base64) {
-    const head = base64Head(base64);
-    if (head.length >= 4 && head[0] === 0x89 && head[1] === 0x50 && head[2] === 0x4e && head[3] === 0x47)
-        return 'image/png';
-    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)
-        return 'image/jpeg';
-    if (head.length >= 12 && ascii(head, 0, 4) === 'RIFF' && ascii(head, 8, 12) === 'WEBP')
-        return 'image/webp';
-    if (head.length >= 4 && ascii(head, 0, 3) === 'GIF')
-        return 'image/gif';
-    return 'image/png';
-}
-/** Sniff an audio media type from magic bytes; unknown ⇒ mpeg (Freesound previews are mp3). */
-export function sniffAudioMediaType(base64) {
-    const head = base64Head(base64);
-    if (head.length >= 4 && ascii(head, 0, 4) === 'OggS')
-        return 'audio/ogg';
-    if (head.length >= 12 && ascii(head, 0, 4) === 'RIFF' && ascii(head, 8, 12) === 'WAVE')
-        return 'audio/wav';
-    if (head.length >= 4 && ascii(head, 4, 8) === 'ftyp')
-        return 'audio/mp4';
-    if (head.length >= 3 && ascii(head, 0, 3) === 'ID3')
-        return 'audio/mpeg';
-    if (head.length >= 2 && head[0] === 0xff && (head[1] & 0xe0) === 0xe0)
-        return 'audio/mpeg';
-    return 'audio/mpeg';
-}
-/**
- * A tool result that carries the JSON payload as text AND the pixels/samples the
- * agent needs to judge it.
- *
- * THE CONTRACT, and why it is shaped this way:
- *  - Media is ADDITIVE. The JSON text block is always first and unchanged, so ids,
- *    urls and flags keep flowing and nothing downstream breaks.
- *  - Zero media ⇒ NO media blocks at all, just the text. An empty content array is
- *    the one failure the old `(b) images never leave execute() content-shaped`
- *    constraint was written to avoid (adapter.ts:384-390) — the fix for "empty
- *    array is invalid" is to omit the block, not to convert every image to text
- *    forever.
- *  - Media types are SNIFFED per item, never declared by the caller.
- */
-export function withMedia(payload, media) {
-    const blocks = [{ type: 'text', text: payload }];
-    for (const m of media) {
-        if (!m.data)
-            continue;
-        blocks.push(m.kind === 'image'
-            ? { type: 'image', data: m.data, mimeType: sniffImageMediaType(m.data) }
-            : { type: 'audio', data: m.data, mimeType: sniffAudioMediaType(m.data) });
-    }
-    return { content: blocks };
-}
-/**
- * Fetch a URL and return its bytes as base64. Returns undefined on ANY failure —
- * a preview that will not load must never fail the tool call it decorates, since
- * the JSON payload is still useful on its own.
- */
-/**
- * Per-image ceiling. A PREVIEW is a thumbnail — 7KB for a catalog poster, ~30KB
- * for a Pexels preview. 2MB is generous headroom; the old 8MB was sized for
- * "some image" rather than for the thing this actually fetches.
- */
-const MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
-/**
- * Cumulative ceiling across ONE tool response.
- *
- * Convex caps an httpAction response at 20MB
- * (https://docs.convex.dev/production/state/limits), and base64 inflates bytes
- * by 4/3. The count cap alone did NOT bound this: 12 images x the old 8MB
- * per-image limit is 96MB raw => ~128MB encoded, six times over the ceiling. A
- * count is not a size. 3MB raw (~4MB encoded) leaves the response comfortably
- * inside the limit with room for the JSON payload.
- */
-const MAX_PREVIEW_BYTES_TOTAL = 3 * 1024 * 1024;
-export async function fetchAsBase64(url, opts) {
-    const timeoutMs = opts?.timeoutMs ?? 10_000;
-    const maxBytes = opts?.maxBytes ?? MAX_PREVIEW_BYTES;
-    try {
-        const ctl = new AbortController();
-        const t = setTimeout(() => ctl.abort(), timeoutMs);
-        const res = await fetch(url, { signal: ctl.signal });
-        clearTimeout(t);
-        if (!res.ok)
-            return undefined;
-        const bytes = new Uint8Array(await res.arrayBuffer());
-        if (bytes.byteLength === 0 || bytes.byteLength > maxBytes)
-            return undefined;
-        return bytesToBase64(bytes);
-    }
-    catch (err) {
-        // Log the REASON. Swallowing this is what hid a Buffer-not-defined crash in
-        // the Convex isolate behind an innocent-looking "no previews available".
-        console.log(JSON.stringify({ evt: 'preview_fetch_failed', err: err instanceof Error ? err.message : String(err) }));
-        return undefined;
-    }
-}
-/**
- * Fetch up to `cap` previews concurrently, preserving input order and dropping
- * failures. The cap is a TOKEN budget, not a correctness one: a contact sheet of
- * a dozen downscaled thumbnails is the difference between an agent that can see
- * and one that blows its context on one full-size still.
- */
-/**
- * Preview cache, keyed by URL.
- *
- * `list_catalog` re-fetched up to 12 posters on EVERY call, and their keys are
- * content-addressed (`<id>@<version>.jpg`) — they can never change, so that was
- * pure repeat work on the hottest discovery verb. Convex reuses a warm isolate
- * across invocations, so a module-level map is the cheapest correct place for
- * this: no new substrate, nothing to invalidate, and it evaporates with the
- * isolate. Presigned R2 URLs carry a fresh signature per call, so they simply
- * never hit — correct by construction rather than by a rule someone must
- * remember.
- */
-const previewCache = new Map();
-const PREVIEW_CACHE_MAX = 64;
-function cacheGet(url) {
-    const hit = previewCache.get(url);
-    if (hit === undefined)
-        return undefined;
-    // refresh recency
-    previewCache.delete(url);
-    previewCache.set(url, hit);
-    return hit;
-}
-function cachePut(url, data) {
-    if (previewCache.size >= PREVIEW_CACHE_MAX) {
-        const oldest = previewCache.keys().next().value;
-        if (oldest !== undefined)
-            previewCache.delete(oldest);
-    }
-    previewCache.set(url, data);
-}
-/** Test seam — the cache is module-level and outlives a single test. */
-export function __resetPreviewCache() {
-    previewCache.clear();
-}
-/**
- * Fetch up to `cap` previews, preserving input order and dropping failures.
- *
- * Bounded by BOTH a count and a cumulative byte budget: the count keeps the
- * contact sheet legible, the bytes keep the response inside Convex's 20MB
- * httpAction ceiling. Sequential rather than parallel because the budget has to
- * be spent in order — a parallel batch cannot know it has already overspent.
- */
-export async function fetchPreviews(urls, cap = 12, opts) {
-    const picked = urls.filter((u) => !!u).slice(0, cap);
-    const out = [];
-    let spent = 0;
-    for (const u of picked) {
-        const cached = opts?.fetchOne ? undefined : cacheGet(u);
-        const data = cached ??
-            (opts?.fetchOne
-                ? await opts.fetchOne(u).catch(() => undefined)
-                : await fetchAsBase64(u, opts));
-        if (!data)
-            continue;
-        // base64 length is a close proxy for encoded bytes; budget on what we SEND.
-        if (spent + data.length > MAX_PREVIEW_BYTES_TOTAL * 1.34)
-            break;
-        spent += data.length;
-        if (!cached && !opts?.fetchOne)
-            cachePut(u, data);
-        out.push(data);
-    }
-    return out;
-}
-// ── error formatting (reuses the SDK's advice table) ──────────────────────
-export function fmtErr(err) {
-    const head = err instanceof ApiError
-        ? `${err.message} (${err.code}, ${err.status})`
-        : err instanceof Error
-            ? err.message
-            : String(err);
-    const advice = adviseError(err);
-    return advice ? `${head}\n  → ${advice}` : head;
-}
-/** Reconstruct an ApiError from a non-2xx executor response so adviseError works. */
-export function apiErrorFrom(res) {
-    let code = 'internal_error';
-    let message = res.text || `HTTP ${res.status}`;
-    let details;
-    try {
-        const j = JSON.parse(res.text);
-        if (j && typeof j === 'object' && j.error) {
-            code = j.error.code ?? code;
-            message = j.error.message ?? message;
-            details = j.error.details;
-        }
-    }
-    catch {
-        /* non-JSON body — keep the raw text as the message */
-    }
-    return new ApiError(res.status, { code, message, details }, res.requestId);
-}
-export function isOk(status) {
-    return status >= 200 && status < 300;
-}
-export function safeParse(textBody) {
-    try {
-        return JSON.parse(textBody);
-    }
-    catch {
-        return undefined;
-    }
-}
-// ── generated-manifest accessors ──────────────────────────────────────────
-const OP_BY_ID = new Map(GENERATED_OPERATIONS.map((o) => [o.operationId, o]));
-/** Look up a generated operation by id; throws (fail-loud) if absent. */
-export function opById(operationId) {
-    const op = OP_BY_ID.get(operationId);
-    if (!op) {
-        throw new Error(`MCP: no generated operation '${operationId}'. The op-manifest (generated/operations.ts) is out of sync — run \`pnpm generate:mcp-tools\`.`);
-    }
-    return op;
-}
-/** The bound zod body schema for an operation, or undefined for body-less ops. */
-export function bodySchemaFor(op) {
-    if (!op.bodyKey)
-        return undefined;
-    const schema = bodySchemas[op.bodyKey];
-    if (!schema) {
-        throw new Error(`MCP: bodySchemas.${op.bodyKey} not found for '${op.operationId}'. Run \`pnpm generate:sdk\`.`);
-    }
-    return schema;
-}
-/**
- * Substitute path params into an op's template. `mapArg(opParamName)` returns the
- * concrete value (raw layer: the arg of the same name; curated layer: the friendly
- * arg mapped to this op param). Values are URL-encoded.
- */
-export function buildPath(op, mapArg) {
-    let path = op.pathTemplate;
-    for (const p of op.pathParams) {
-        path = path.replace(`{${p}}`, encodeURIComponent(String(mapArg(p))));
-    }
-    return path;
-}
-/** Run an operation through the executor. `body` is sent only for bodied ops. */
-export async function invokeOp(ex, op, mapArg, body, 
-/** base64 PAYMENT-SIGNATURE for a paid (x402) tool call; omitted for authed calls. */
-payment, 
-/** Pre-encoded query string (no leading '?') — curated queryArgs filters. */
-query) {
-    return ex.invoke({
-        method: op.method,
-        path: buildPath(op, mapArg),
-        body: op.bodyKey ? (body ?? {}) : undefined,
-        ...(query ? { query } : {}),
-        payment,
-    });
-}
-/**
- * Surface a canonical x402 `PaymentRequired` challenge as the MCP result an
- * x402-aware client acts on. Emit the PaymentRequired JSON in BOTH carriers:
- * `content[0].text` (the spec-required carrier a content-first client parses —
- * matching @x402/mcp's own reference server) AND `structuredContent` (the
- * preferred carrier the pinned client reads first). The envelope already carries
- * a top-level human `error` string, so a non-x402 LLM client still reads a
- * legible reason. `paymentRequired` is pre-parsed + shape-checked by the caller.
- */
-function paymentRequiredResult(paymentRequired) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(paymentRequired) }],
-        isError: true,
-        structuredContent: paymentRequired,
-    };
-}
-/**
- * Run an op through the executor with x402 pay-per-call support (used by every
- * tool). Reads the client's signed payment from the tool call `_meta`, forwards
- * it as `PAYMENT-SIGNATURE` so the REST x402 middleware verifies + settles (the
- * SAME money path as a direct REST call), turns an inner 402 into a
- * payment-required result, and attaches the settle receipt on success.
- * `formatOk` builds the success result from the executor response; `label` names
- * the tool for the error message. Payment-free (key/OAuth) calls are unaffected.
- */
-export async function dispatchOp(ex, op, mapArg, body, extra, label, formatOk) {
-    const paymentObj = extractPaymentFromMeta(extra?._meta);
-    const payment = paymentObj ? encodePaymentSignature(paymentObj) : undefined;
-    const res = await invokeOp(ex, op, mapArg, body, payment);
-    // Discriminate the x402 challenge from the OTHER errors that share HTTP 402
-    // (billing_required, generation_budget_exceeded, payment_invalid, …): only a
-    // real PaymentRequired body ({x402Version, accepts[]}) becomes a "pay with
-    // x402" result; everything else falls through to its typed error advice.
-    if (res.status === MCP_PAYMENT_REQUIRED_CODE) {
-        const parsed = safeParse(res.text);
-        if (isX402PaymentRequired(parsed))
-            return paymentRequiredResult(parsed);
-    }
-    if (!isOk(res.status))
-        return errText(`${label} failed: ${fmtErr(apiErrorFrom(res))}`);
-    // No receipt attach: settle is async (see x402.ts) — the caller reads the final
-    // outcome from x402Payments, not an inline `_meta["x402/payment-response"]`.
-    return formatOk(res);
-}