@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/mcp/wait.js

@@ -1,378 +0,0 @@
-/**
- * `wait_job` — block until a long-running job reaches a terminal state, by
- * POLLING its status endpoint through the Executor. Unified across transports:
- * the same poll loop works for stdio (network) and hosted (in-process), so the
- * blocking-SSE path is gone (the agent only ever sees the terminal result, so
- * polling is functionally equivalent; `create_webhook` is the event-driven path
- * for fan-out). Pure + side-effect-free (clock/sleep injectable) so it unit-tests
- * without a server.
- */
-import { opById, buildPath, isOk, safeParse, apiErrorFrom, fmtErr } from './core.js';
-const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const defaultNow = () => Date.now();
-const DEFAULT_POLL_MS = 3000;
-function fmtTime(sec) {
-    return `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, '0')}`;
-}
-const KINDS = {
-    render: {
-        operationId: 'getRender',
-        mapArg: (p, id, projectId) => (p === 'renderId' ? id : projectId),
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            if (s === 'complete' || s === 'completed') {
-                const url = j?.outputUrl;
-                const lines = ['Render complete.'];
-                if (url)
-                    lines.push(`\nDownload URL: ${url}`);
-                if (j?.outputExpiresAt)
-                    lines.push(`Expires: ${j.outputExpiresAt}`);
-                return { ok: true, text: lines.join('\n') };
-            }
-            if (s === 'error' || s === 'failed' || s === 'cancelled') {
-                const cause = j?.errorDetails ? JSON.stringify(j.errorDetails) : (j?.error ?? j?.errorCode ?? '');
-                const lines = [`Render ${s}${cause ? `: ${cause}` : ''}.`];
-                if (j?.errorCode)
-                    lines.push(`Code: ${j.errorCode}${j?.category ? ` (${j.category})` : ''}`);
-                if (typeof j?.retryable === 'boolean') {
-                    lines.push(j.retryable
-                        ? 'retryable: true — transient pipeline failure; call retry_render to re-attempt.'
-                        : `retryable: false — deterministic defect${j?.category ? ` (category ${j.category})` : ''}; fix the composition before re-rendering — retry_render alone will not help.`);
-                }
-                return { ok: false, text: lines.join('\n') };
-            }
-            return null;
-        },
-    },
-    compose: {
-        operationId: 'getComposeJob',
-        mapArg: (p, id, projectId) => (p === 'composeJobId' ? id : projectId),
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            // Client-agent checkpoint: the compose is PAUSED at a holdAt stage,
-            // awaiting the client's decision. STOP polling and hand back to the agent
-            // — this is a decision point, distinct from the still-running continuation
-            // (no `stillRunning`, so the poll loop returns) and from an error. The
-            // warm box is already released, so the run costs nothing while parked.
-            if (s === 'awaiting_input') {
-                // The job carries a POINTER at the durable checkpoint packet — the
-                // artifact/stills/verdicts/quote live there, not on the job row.
-                const cp = (j?.checkpoint ?? {});
-                const lines = [
-                    `Compose paused (awaiting_input) at a checkpoint — stage "${cp.stage ?? '?'}" (version ${cp.version ?? '?'}), checkpointId ${cp.checkpointId ?? '?'}.`,
-                    `\n1. get_checkpoint(checkpointId: "${cp.checkpointId ?? ''}") — the packet: stage artifact, presigned storyboard stills (REVIEW THE EVIDENCE, relay stills + the money triple to your human), critic verdicts, and the quote.`,
-                    `\n2. Answer with resume(checkpointId: "${cp.checkpointId ?? ''}", body: { decision: "approve" | "revise" | "abandon" }). "revise" loops IN-JOB — add body.comments ([{anchor: {beatId}|{timecodeMs}, verdict: "approve"|"revise"|"lock", note}]) and/or body.edits (your revised artifact); the director re-presents this same gate as a new packet. "abandon" ends the run. Approve-with-comments is legal (notes record without gating). The compose stays parked (warm box released) until you resume.`,
-                ];
-                return { ok: true, text: lines.filter(Boolean).join('\n') };
-            }
-            if (s === 'complete' || s === 'completed') {
-                const lines = ['Compose complete.'];
-                const w = j?.winner;
-                if (w && typeof w.candidateIndex === 'number') {
-                    lines.push(`Winner: candidate #${w.candidateIndex}`);
-                    // composite lives on the winning candidate, NOT top-level.
-                    const cand = Array.isArray(j?.candidates)
-                        ? j.candidates.find((c) => c?.index === w.candidateIndex)
-                        : undefined;
-                    if (typeof cand?.composite === 'number')
-                        lines.push(`Composite score: ${cand.composite}`);
-                }
-                // A job can COMPLETE below the bar (e.g. footage that cannot satisfy the
-                // brief): say so, name the stuck criteria with the judge's critique, and
-                // give the caller its three real moves — otherwise "complete" reads as
-                // "accepted" and the caller ships a video the judge just told us is short.
-                const qa = j?.qualityAssessment;
-                if (qa?.route === 'handoff') {
-                    lines.push(`\n⚠ BELOW THE QUALITY BAR (${qa.qualityThreshold ?? '?'}) — completed, but not publish-ready.`);
-                    for (const b of qa.blockers ?? []) {
-                        lines.push(`  • ${b.criterion} ${b.score}/${b.floor} (floor) — ${(b.critique ?? '').slice(0, 300)}`);
-                    }
-                    lines.push('\nYour options: fix the ROOT cause the critique names (often the source footage or the brief itself) and compose again; accept it as-is and create_render; or hand it to a human to finish.');
-                    return { ok: true, text: lines.join('\n') };
-                }
-                lines.push('\nThe winning composition is saved to the project. Render it with create_render.');
-                return { ok: true, text: lines.join('\n') };
-            }
-            // 'error' is the legacy terminal (composeJobs.isTerminalComposeStatus
-            // includes it for pre-contract rows) — omitting it polls a dead job to
-            // the 30-min cap (review finding 2026-07-10, same fix as consult).
-            if (s === 'failed' || s === 'cancelled' || s === 'error') {
-                // Surface the row's terminal reason (sanitized `code: message` prose,
-                // e.g. "reframe_coverage_gap: clip clip-0: uncovered [0–3s] …").
-                // Hardcoding "Compose failed." here left the agent debugging blind
-                // while the real reason sat unread on the row (2026-07-07 LBO run).
-                const reason = typeof j?.error === 'string' && j.error ? `: ${j.error}` : '.';
-                return { ok: false, text: `Compose ${s}${reason}` };
-            }
-            return null;
-        },
-    },
-    consult: {
-        // A consult job IS a composeJob (routes/consult.ts returns consultJobId =
-        // composeJobId) — same detail op, different terminal: the advisory envelope
-        // (assessment / proposals / principles / plan), never the compose kind's
-        // "winner — render it" text. Before this kind existed, consult was a
-        // DEAD-END: its advisoryResult was unreachable over the curated surface.
-        operationId: 'getComposeJob',
-        mapArg: (p, id, projectId) => (p === 'composeJobId' ? id : projectId),
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            if (s === 'complete' || s === 'completed') {
-                const a = j?.advisoryResult;
-                if (!a) {
-                    // Fail loud: a consult that finished without an envelope is a defect,
-                    // not a success to paper over (the worker-callback whitelist dropped
-                    // advisoryResult once before — http.ts).
-                    return {
-                        ok: false,
-                        text: 'Consult completed but the job has no advisoryResult — inspect getComposeJob for the raw row; this is a pipeline defect, not a usage error.',
-                    };
-                }
-                const lines = [`Consult (${a.mode ?? '?'}) complete.`];
-                // Evidence convergence: the advisory minted a durable kind:'score'
-                // Checkpoint — same addressable noun as gates and score_composition.
-                if (typeof a.checkpointId === 'string') {
-                    lines.push(`Checkpoint: ${a.checkpointId} (durable advisory packet — get_checkpoint re-reads it later).`);
-                }
-                if (a.assessment) {
-                    for (const [criterion, v] of Object.entries(a.assessment)) {
-                        // A criterion may arrive critique-only (judge omitted the numeric
-                        // score) — dropping it would swallow the very critique the caller
-                        // paid for. Render whatever is present.
-                        if (v && (typeof v.score === 'number' || v.critique)) {
-                            const score = typeof v.score === 'number' ? String(v.score) : '—';
-                            lines.push(`- ${criterion}: ${score}${v.critique ? ` — ${v.critique}` : ''}`);
-                        }
-                    }
-                }
-                if (Array.isArray(a.proposals) && a.proposals.length > 0) {
-                    lines.push('\nProposals:');
-                    for (const p of a.proposals) {
-                        // selectStrategy is REQUIRED on the select body (no route default) —
-                        // teaching the short body here would 400 the agent that follows it.
-                        const adopt = typeof p.candidateIndex === 'number'
-                            ? ` — adopt via select_candidate(projectId, composeJobId, body: { candidateIndex: ${p.candidateIndex}, selectStrategy: "agent-authoritative" })`
-                            : ' (advisory only — re-author via apply_composition)';
-                        lines.push(`- ${p.label ?? '?'}: ${(p.changeSummary ?? []).join('; ')}${adopt}`);
-                        if (typeof p.candidateIndex === 'number')
-                            lines.push(`  (candidateIndex: ${p.candidateIndex})`);
-                    }
-                }
-                if (Array.isArray(a.principles) && a.principles.length > 0) {
-                    lines.push(`\nPrinciples:\n${a.principles.map((x) => `- ${x}`).join('\n')}`);
-                }
-                if (a.plan !== undefined) {
-                    lines.push(`\nPlan (mode=advise — GUIDANCE to re-author from via apply_composition; it is not converted to ops):\n${JSON.stringify(a.plan, null, 2)}`);
-                }
-                return { ok: true, text: lines.join('\n') };
-            }
-            // 'error' is the legacy compose terminal (composeJobs.ts
-            // isTerminalComposeStatus) — omitting it here polls a dead job to the
-            // 30-min cap (review finding 2026-07-10).
-            if (s === 'failed' || s === 'cancelled' || s === 'error') {
-                const reason = typeof j?.error === 'string' && j.error ? `: ${j.error}` : '.';
-                return { ok: false, text: `Consult ${s}${reason}` };
-            }
-            return null;
-        },
-    },
-    suggestions: {
-        operationId: 'listMediaSuggestions',
-        mapArg: (_p, id) => id,
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            const suggestions = Array.isArray(j?.suggestions) ? j.suggestions : [];
-            if (s === 'failed')
-                return { ok: false, text: 'Clip-suggestion analysis failed.' };
-            // Gate on STATUS only — never on suggestions.length, or a still-"generating"
-            // re-analysis would return the previous run's stale suggestions as terminal.
-            if (s === 'complete' || s === 'completed') {
-                if (suggestions.length === 0) {
-                    return { ok: true, text: 'Analysis complete — no clip suggestions produced.' };
-                }
-                const lines = suggestions.map((sg) => {
-                    const dur = sg?.trim ? (sg.trim.end - sg.trim.start).toFixed(1) : '?';
-                    const t = sg?.trim ? `${fmtTime(sg.trim.start)} → ${fmtTime(sg.trim.end)} (${dur}s)` : '';
-                    const door = sg.briefId
-                        ? `\n  briefId: ${sg.briefId} — compose it via compose {briefId}`
-                        : '';
-                    return `- ${sg.id}\n  "${sg.title}"\n  ${t}  ${sg.format ?? ''}  score: ${sg.score ?? ''}\n  ${sg.reason ?? ''}${door}`;
-                });
-                const anyBrief = suggestions.some((sg) => sg.briefId);
-                const tail = anyBrief
-                    ? '\n\nEach suggestion above was minted as a kind-\'clip\' Brief — compose {briefId} runs the Director on it (list_briefs {kind:"clip"} shows them).'
-                    : '\n\nNo Briefs were minted (this media has no project) — import it into a project and re-run suggest_briefs to get composable briefIds.';
-                return {
-                    ok: true,
-                    text: `Analysis complete. ${suggestions.length} clip suggestion${suggestions.length !== 1 ? 's' : ''}:\n\n${lines.join('\n\n')}${tail}`,
-                };
-            }
-            return null;
-        },
-    },
-    verify: {
-        // The generic jobs resource (GET /v1/jobs/{id}) — verify is its first
-        // tenant; future job kinds reuse this parser instead of adding adapters.
-        operationId: 'getJob',
-        mapArg: (_p, id) => id,
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            if (s === 'succeeded') {
-                const r = (j?.result ?? {});
-                const lines = ['Verify complete.'];
-                // Lane convergence: the verdicts also minted a durable kind:'score'
-                // Checkpoint — the same addressable evidence noun the director's gates
-                // produce (get_checkpoint / list_checkpoints reads it back).
-                if (typeof r.checkpointId === 'string') {
-                    lines.push(`Checkpoint: ${r.checkpointId} (durable score packet — get_checkpoint to re-read the verdicts later).`);
-                }
-                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}` : ''}`);
-                        }
-                    }
-                }
-                // A6 lane parity: the org's OWN registered critics grade here too —
-                // parallel channel, never part of the composite.
-                if (Array.isArray(r.clientScores) && r.clientScores.length > 0) {
-                    lines.push('\nYour registered critics:');
-                    for (const c of r.clientScores) {
-                        const name = c.label ?? c.criticId ?? 'critic';
-                        if (c.unavailable) {
-                            lines.push(`- ${name}: unavailable (your evaluator did not answer — excluded from the gate)`);
-                        }
-                        else if (typeof c.score === 'number') {
-                            const below = typeof c.floor === 'number' && c.score < c.floor ? ' (BELOW your floor)' : '';
-                            lines.push(`- ${name}: ${c.score}${below}${c.critique ? ` — ${c.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 { ok: true, text: lines.join('\n') };
-            }
-            if (s === 'failed')
-                return jobFailedResult('Verify', 'score_composition', j);
-            return null;
-        },
-    },
-    preview: {
-        // Generic jobs resource — preview job (single-component still).
-        operationId: 'getJob',
-        mapArg: (_p, id) => id,
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            if (s === 'succeeded') {
-                // `url` is presigned at READ time by the jobs route from the result's
-                // durable `outputR2Key` (routes/jobs.ts) — the executor never stores a
-                // URL that would expire inside the immortal job row.
-                const r = (j?.result ?? {});
-                return {
-                    ok: true,
-                    mediaUrls: r.url ? [r.url] : undefined,
-                    text: r.url
-                        ? `Preview ready.\n\nClip: ${r.url}${r.urlExpiresAt ? `\n(link valid until ${r.urlExpiresAt})` : ''}\n\nInspect it, fix the component via create_component if needed, and re-preview.`
-                        : 'Preview succeeded but returned no url — inspect GET /v1/jobs for the raw result.',
-                };
-            }
-            if (s === 'failed')
-                return jobFailedResult('Preview', 'preview_component', j);
-            return null;
-        },
-    },
-    brand_kit_extract: {
-        // Generic jobs resource — brand-token extraction job.
-        operationId: 'getJob',
-        mapArg: (_p, id) => id,
-        terminal: (j) => {
-            const s = String(j?.status ?? '');
-            if (s === 'succeeded') {
-                const r = (j?.result ?? {});
-                const colors = Array.isArray(r.colors) ? r.colors.length : 0;
-                const fonts = Array.isArray(r.fonts) ? r.fonts.length : 0;
-                const head = `${colors} color${colors !== 1 ? 's' : ''}, ${fonts} font${fonts !== 1 ? 's' : ''}${r.title ? ` — ${r.title}` : ''}`;
-                return {
-                    ok: true,
-                    text: `Extraction complete: ${head}.\n\n${JSON.stringify(j?.result ?? {}, null, 2)}\n\nReview the tokens, then create_brand_kit to persist a kit. (0 tokens usually means a JS-rendered site — author the kit manually from the site's compiled CSS.)`,
-                };
-            }
-            if (s === 'failed')
-                return jobFailedResult('Brand-kit extraction', 'extract_brand_kit', j);
-            return null;
-        },
-    },
-};
-/** Shared FAILED terminal for generic-job kinds: typed code + retry hint. */
-function jobFailedResult(label, reEnqueueTool, j) {
-    const code = String(j?.error?.code ?? 'unknown');
-    const msg = typeof j?.error?.message === 'string' ? j.error.message : '';
-    const retryHint = code === 'job_timeout'
-        ? ` The executor died mid-run and the stall sweep reaped the job — re-enqueue ${reEnqueueTool} to retry.`
-        : '';
-    return { ok: false, text: `${label} failed (${code})${msg ? `: ${msg}` : ''}.${retryHint}` };
-}
-/**
- * Poll a job's status op until terminal or the deadline. 4xx → fail loud
- * immediately; 5xx/transient → keep polling; 2xx non-terminal → sleep + retry.
- */
-export async function waitForJob(ex, kind, id, projectId, deadline, deps = {}) {
-    const sleep = deps.sleep ?? defaultSleep;
-    const now = deps.now ?? defaultNow;
-    const pollMs = deps.pollMs ?? DEFAULT_POLL_MS;
-    const cfg = KINDS[kind];
-    const op = opById(cfg.operationId);
-    let lastStatus = '';
-    // Overshoot guard: never START an invoke (or a sleep+invoke cycle) that
-    // would land past the deadline — the old `now() < deadline` check let a
-    // poll beginning at deadline−1ms overshoot by the whole invoke duration,
-    // blowing the transport budget the deadline exists to respect.
-    const INVOKE_BUDGET_MS = deps.invokeBudgetMs ?? 2_000;
-    // ALWAYS poll at least once: a caller with a tiny timeout (schema floor is
-    // 1000ms, under the invoke budget) is doing a quick status check — zero
-    // polls would return still-running for a job that already finished (or
-    // doesn't exist), and an agent obeying the re-call hint livelocks forever.
-    let firstPoll = true;
-    while (firstPoll || now() + INVOKE_BUDGET_MS < deadline) {
-        firstPoll = false;
-        const res = await ex.invoke({
-            method: op.method,
-            path: buildPath(op, (p) => cfg.mapArg(p, id, projectId)),
-        });
-        // Fail fast on a client error (4xx) OR any error the API marks
-        // non-retryable (`error.retryable === false`) — only genuinely transient
-        // 5xx are worth polling. (Without this, a non-retryable 500 — e.g. a
-        // malformed id — would poll until the full timeout.)
-        if (!isOk(res.status)) {
-            const j = safeParse(res.text);
-            if ((res.status >= 400 && res.status < 500) || j?.error?.retryable === false) {
-                return { ok: false, text: `Failed to poll ${kind} status: ${fmtErr(apiErrorFrom(res))}` };
-            }
-        }
-        if (isOk(res.status)) {
-            const json = safeParse(res.text);
-            const t = cfg.terminal(json);
-            if (t)
-                return t;
-            if (json && typeof json.status === 'string')
-                lastStatus = json.status;
-        }
-        if (now() + pollMs + INVOKE_BUDGET_MS >= deadline)
-            break;
-        await sleep(pollMs);
-    }
-    // Window expired with the job still running: a CONTINUATION (success), not
-    // an error. The job keeps executing server-side; the caller re-invokes
-    // wait_job to keep waiting. This is what makes wait_job an honest bounded
-    // long-poll on capped transports instead of a misleading failure.
-    const tail = lastStatus ? ` Last status: ${lastStatus}.` : '';
-    return {
-        ok: true,
-        stillRunning: true,
-        text: `Still running — the ${kind} job continues server-side.${tail} Call wait_job again with the SAME arguments (kind="${kind}", id="${id}"${projectId ? `, projectId="${projectId}"` : ''}) to keep waiting. For event-driven fan-out, create_webhook delivers the terminal instead.`,
-    };
-}

package/dist/_members/mcp/x402Meta.js

@@ -1,66 +0,0 @@
-/**
- * x402-over-MCP wire constants + helpers, VENDORED from the first-party
- * `@x402/mcp` package and pinned to it by `x402Meta.conformance.test.ts`.
- *
- * Why vendored instead of `import … from "@x402/mcp"`: the published `@x402/mcp`
- * dist is a single bundle that imports `@x402/core/client` + `/server`
- * (viem/Buffer) at MODULE scope, so importing even a constant drags Buffer into
- * the Convex V8 isolate — the exact failure `x402Facilitator.ts` is `"use node"`
- * to avoid. This module is plain-JSON + `btoa` only, so it is V8-safe and runs in
- * both the hosted (V8 isolate) and stdio (Node) transports. Same generator/runtime
- * split as `x402Discovery` (a Node test tracks the spec; the runtime reads plain
- * data). The conformance test fails if these drift from `@x402/mcp`.
- *
- * The convention (Cloudflare/Coinbase/Vercel + `@x402/mcp`): over MCP, payment
- * rides in the JSON-RPC `_meta` field, NOT an HTTP header — MCP is transport-
- * agnostic (stdio has no HTTP layer). The `PaymentPayload` / `PaymentRequired`
- * objects are byte-identical to CueFrame's REST v2 envelope; only the carrier
- * differs (`_meta` key vs `PAYMENT-SIGNATURE`/`Payment-Required` header).
- */
-/** Client → server: the signed EIP-3009 `PaymentPayload`, on the tools/call `_meta`. */
-export const MCP_PAYMENT_META_KEY = 'x402/payment';
-/** JSON-RPC error code a paid tool returns when called unpaid. */
-export const MCP_PAYMENT_REQUIRED_CODE = 402;
-/**
- * True iff a parsed body is a canonical x402 `PaymentRequired` challenge (has a
- * numeric `x402Version` and an `accepts` array) — matching the @x402/mcp client's
- * `isPaymentRequiredStructure`. Used to tell the REAL 402 payment challenge apart
- * from the OTHER errors that share HTTP 402 (billing_required,
- * generation_budget_exceeded, payment_invalid, …), which must surface as typed
- * errors, not an x402 "sign a payment" prompt.
- */
-export function isX402PaymentRequired(body) {
-    return (!!body &&
-        typeof body === 'object' &&
-        typeof body.x402Version === 'number' &&
-        Array.isArray(body.accepts));
-}
-/**
- * Read the client's signed payment (a `PaymentPayload` object) off a tools/call
- * `_meta`. Returns the raw object or null; the STRUCTURE is validated downstream
- * by the facilitator's EIP-3009 decode (single source of truth), so this is a
- * presence/shape gate only — never trust it as verified payment.
- */
-export function extractPaymentFromMeta(meta) {
-    const p = meta?.[MCP_PAYMENT_META_KEY];
-    return p && typeof p === 'object' ? p : null;
-}
-/**
- * Encode a `PaymentPayload` object into the base64 `PAYMENT-SIGNATURE` header
- * value the REST x402 middleware decodes (`@x402/core` `encodePaymentSignatureHeader`
- * = `safeBase64Encode(JSON.stringify(payload))`). `btoa`-based → V8-safe; mirrors
- * `@x402/core`'s own `safeBase64Encode` (which is also btoa-first). This lets an
- * MCP tool call forward its `_meta` payment INTO the unchanged REST verify/settle
- * path via the inner `app.fetch`, reusing all money-safety.
- */
-export function encodePaymentSignature(payload) {
-    const bytes = new TextEncoder().encode(JSON.stringify(payload));
-    let binary = '';
-    for (let i = 0; i < bytes.length; i++)
-        binary += String.fromCharCode(bytes[i]);
-    return btoa(binary);
-}
-// NB: no `attachPaymentResponseToMeta` / `decodePaymentResponse` — CueFrame does
-// NOT emit an inline settle receipt (settle is async; the caller reads the final
-// outcome from x402Payments). If a synchronous-settle receipt is ever added,
-// re-vendor those two @x402/mcp helpers here with a conformance test.

package/dist/_members/media-model/api.js

@@ -1,175 +0,0 @@
-import { z } from "zod";
-import { zid } from "convex-helpers/server/zod3";
-// Phase labels for media processing. One canonical vocabulary across desktop,
-// Convex, and OpenAPI — no per-consumer redefinition. Superset of every stage
-// either side runs:
-//   shared:        idle → pending_import → pending_upload → uploading → ...
-//                  → complete | error | cancelled
-//   desktop-local: extracting (audio extract), loading_model (whisper download),
-//                  transcribing, proxy (low-res preview transcode), embedding,
-//                  analyzing, indexing
-//   cloud-only:    generating (TTS / text-to-image), rendering (final encode)
-//   intermediate:  processing (generic in-flight when no specific stage applies)
-//
-// Legacy cloud writers that wrote 'completed'/'ready'/'failed'/'in_progress'/
-// 'transcoding' map onto this canonical via projectStatus() in
-// projections/mediaItems.ts; the data migration in PR 2 backfills them.
-export const MediaProcessingPhase = z.enum([
-    "idle",
-    "pending_import",
-    "pending_upload",
-    "uploading",
-    "extracting",
-    "loading_model",
-    "transcribing",
-    "proxy",
-    "embedding",
-    "analyzing",
-    "indexing",
-    "generating",
-    "rendering",
-    "processing",
-    "complete",
-    "error",
-    "cancelled",
-]);
-// ProxyStatus — lifecycle of the low-res preview proxy file. One canonical
-// enum across desktop SQLite, Convex `mediaItems.proxyStatus`, and any
-// OpenAPI shape that exposes proxy state.
-export const ProxyStatus = z.enum([
-    "none",
-    "generating",
-    "ready",
-    "failed",
-]);
-// MediaProcessingStatus — runtime state object combining phase + progress
-// detail. This is the single shape every consumer (desktop, Convex storage,
-// OpenAPI responses) sees. Older code that referenced `MediaProcessingStatus`
-// as an enum should now reference `MediaProcessingPhase`; older code that
-// hand-defined a `{phase, percent, message, error}` object (OpenAPI, desktop
-// discriminated unions) should now import this.
-// percent/message/error are nullable AND optional — desktop construction
-// sites typically omit them (`{ phase: 'idle' }`), worker writes nullable
-// (e.g. `{ phase: 'processing', percent: 60, message: 'Transcribing', error: null }`),
-// OpenAPI emission preserves whichever the producer sent. Consumers tolerate
-// any of: present-with-value | present-with-null | omitted.
-export const MediaProcessingStatus = z.object({
-    phase: MediaProcessingPhase,
-    percent: z.number().nullable().optional(),
-    message: z.string().nullable().optional(),
-    error: z.string().nullable().optional(),
-});
-// MediaUnderstanding — populated by the visual/topical analysis stage.
-// Shape is intentionally permissive at P0; pipeline stages may extend it.
-export const MediaUnderstanding = z.object({
-    summary: z.string().optional(),
-    topics: z.array(z.string()).optional(),
-    language: z.string().optional(),
-    notes: z.string().optional(),
-    extra: z.record(z.string(), z.unknown()).optional(),
-});
-// Generation — present iff MediaItem.source === 'generated'.
-// Provider is an open string mapping to a server-side generator registered with credentials;
-// new providers are additions to the generator registry, not schema migrations.
-export const TextToSpeechGeneration = z.object({
-    kind: z.literal("text-to-speech"),
-    provider: z.string().min(1),
-    text: z.string().min(1),
-    voice: z.string().min(1),
-    params: z.record(z.string(), z.unknown()).optional(),
-});
-export const TextToImageGeneration = z.object({
-    kind: z.literal("text-to-image"),
-    provider: z.string().min(1),
-    prompt: z.string().min(1),
-    params: z.record(z.string(), z.unknown()).optional(),
-});
-export const ImageToVideoGeneration = z.object({
-    kind: z.literal("image-to-video"),
-    provider: z.string().min(1),
-    sourceMediaId: zid("mediaItems"),
-    prompt: z.string().optional(),
-    params: z.record(z.string(), z.unknown()).optional(),
-});
-export const ManimGeneration = z.object({
-    kind: z.literal("manim"),
-    scriptId: z.string().optional(),
-    inlineScript: z.string().optional(),
-    params: z.record(z.string(), z.unknown()).optional(),
-});
-export const Generation = z.discriminatedUnion("kind", [
-    TextToSpeechGeneration,
-    TextToImageGeneration,
-    ImageToVideoGeneration,
-    ManimGeneration,
-]);
-// TranscriptRef — pointer to the transcript artifact (full word-level data lives in R2,
-// the row carries metadata + R2 key). `ready` flips when the transcribe stage completes.
-export const TranscriptRef = z.object({
-    id: z.string().min(1),
-    ready: z.boolean(),
-});
-// Agent-perception surface (filmstrip + per-frame analysis) — populated by
-// the perception pipeline stage post-ingestion. Placed before MediaItem so
-// MediaItem's `perception` field resolves.
-// FrameAnalysis — analysis derived from a single sampled frame: spatial
-// regions (faces, primary subject, safe regions for overlay placement) and
-// non-spatial signals (dominant colors). Keyed by timestamp `t`.
-export const FrameAnalysis = z.object({
-    t: z.number().nonnegative(),
-    faces: z.array(z.object({
-        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
-        confidence: z.number().min(0).max(1).optional(),
-    })).optional(),
-    primarySubject: z.object({
-        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
-    }).optional(),
-    safeRegions: z.array(z.object({
-        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
-        kind: z.string().optional(),
-    })).optional(),
-    dominantColors: z.array(z.string()).optional(),
-});
-export const Filmstrip = z.object({
-    mediaId: zid("mediaItems"),
-    sheetUrl: z.string().url(),
-    frameCount: z.number().int().positive(),
-    frameInterval: z.number().positive(),
-    frameWidth: z.number().int().positive(),
-    frameHeight: z.number().int().positive(),
-    columns: z.number().int().positive(),
-});
-// Perception — bundle of pre-computed perception artifacts for a MediaItem row.
-// Filmstrip is the visual artifact (sprite-sheet); frameAnalysis[] is the
-// per-moment structured analysis. Read by agents reasoning about content
-// without re-decoding the source.
-export const Perception = z.object({
-    mediaId: zid("mediaItems"),
-    filmstrip: Filmstrip.optional(),
-    frameAnalysis: z.array(FrameAnalysis).optional(),
-});
-export const MediaItem = z.object({
-    id: zid("mediaItems"),
-    // Track-routing kind; not in the data-model.md spec but load-bearing for
-    // the existing storage pipeline. video/audio/image determine ingest path.
-    kind: z.enum(["video", "audio", "image"]),
-    filename: z.string().min(1),
-    // Aliased per data-model.md § MediaItem — `mimeType` is the doc name; `size` is bytes.
-    mimeType: z.string().min(1),
-    size: z.number().int().nonnegative(),
-    duration: z.number().nonnegative().optional(), // seconds; populated post-transcode
-    width: z.number().int().positive().optional(),
-    height: z.number().int().positive().optional(),
-    fps: z.number().positive().optional(),
-    status: MediaProcessingPhase,
-    source: z.enum(["upload", "generated"]).optional(),
-    generation: Generation.optional(),
-    // Derived data populated through the pipeline
-    transcript: TranscriptRef.optional(),
-    mediaUnderstanding: MediaUnderstanding.optional(),
-    perception: Perception.optional(),
-    // Lifecycle timestamps — epoch ms (see CONVEX_ADAPTATIONS.md)
-    createdAt: z.number(),
-    updatedAt: z.number(),
-    ownerOrgId: z.string().optional(),
-});

package/dist/_members/media-model/index.js

@@ -1 +0,0 @@
-export * from "./api";