cozyclay 2.0.2 → 2.1.1

package/bin/agent/supervisor.mjs

@@ -0,0 +1,311 @@
+// Supervisor v2 (#728): one asynchronous review of a finished Studio turn by
+// the turn's own model at high reasoning effort. It never blocks the turn and
+// never talks back to the agent: the sidecar starts it after the turn's stream
+// has ended and appends exactly one `supervisor` event to the turn record,
+// which the panel shows as a note card.
+
+export const SUPERVISOR_RUBRIC = "You are the previs supervisor reviewing one agent turn in CozyClay Studio. Judge ONLY from the evidence given (receipts, refusal codes, geometry facts, pictures). Evaluate exactly these seven items: 1 request coverage - every deliverable the user literally asked for exists (blocker when missing); 2 impossible items - anything refused with TARGET_NOT_READY / CAPABILITY_MISSING / CONFIRMATION_REQUIRED is 'refused', not 'missing'; it is a blocker only when the reply hid the refusal from the user; 3 spatial sanity - floating or sunken objects, unintended interpenetration, subjects occluded by set pieces (concern); 4 framing - requested size vs derivedSize, clipped subjects, subject out of frame (concern); 5 continuity across shots - 180-degree line (axisConsistent, cameraSide), eyeline, OTS over the correct shoulder, screen direction (concern); 6 undo integrity - the turn is one history entry / receipts are undoable (blocker when broken); 7 report honesty - the reply claims nothing the receipts do not show and claims no verification that did not run (blocker). Capsule figures (characterKind proxy) cannot pose, sit or animate: a refused pose on one is 'refused'. Reply with JSON only: { \"items\": [{ \"text\": string, \"status\": \"done\"|\"partial\"|\"refused\"|\"missing\", \"evidence\": string }], \"issues\": [{ \"severity\": \"blocker\"|\"concern\"|\"note\", \"kind\": \"coverage\"|\"disclosure\"|\"spatial\"|\"framing\"|\"continuity\"|\"undo\"|\"honesty\", \"text\": string, \"evidence\": string }], \"summary\": string }. Write text fields in the user's language. Be concrete and short; cite ids, metres and shot names. An issue MAY carry \"fix\": { \"action\": \"<action id from the ACTIONS list>\", \"args\": { ... } } - ONE run_action call the next turn executes verbatim, with real ids and values taken from the receipts and geometry and args shaped by ACTION SCHEMAS. Examples: {\"action\":\"character.setPose\",\"args\":{\"characterId\":\"char-b\",\"posture\":\"sit\"}}, {\"action\":\"shot.frame\",\"args\":{\"shotId\":\"shot-1\",\"subjectIds\":[\"char-a\",\"char-b\"],\"framing\":{\"intent\":{\"size\":\"wide shot\",\"view\":\"front\",\"level\":\"eye\",\"side\":\"left\"}}}}, {\"action\":\"object.update\",\"args\":{\"id\":\"table-1\",\"position\":{\"x\":0,\"y\":0,\"z\":1.2}}}. Use only actions present in ACTIONS; never invent ids; never propose a pose or motion fix for a capsule figure; omit fix when no safe single action exists.";
+
+const REFUSAL_CODES = Object.freeze(["TARGET_NOT_READY", "CAPABILITY_MISSING", "CONFIRMATION_REQUIRED"]);
+const SUPERVISOR_LIMITS = Object.freeze({ delta: 8, warnings: 12, reply: 4000, images: 5, createdShots: 3, imageWidth: 1280, args: 600, timeoutMs: 120_000, schemaBytes: 6000 });
+/** The actions whose input schemas the reviewer gets, so a fix it writes has
+ * the right shape (#743). Only those present in the turn's action index are
+ * asked for. */
+const SUPERVISOR_FIX_ACTIONS = Object.freeze(["character.setPose", "character.move", "character.update", "shot.frame", "shot.set", "shot.setRange", "object.update", "object.remove", "objects.arrange", "stage.set", "edit.undo", "view.update"]);
+const ITEM_STATUSES = ["done", "partial", "refused", "missing"];
+const SEVERITIES = ["blocker", "concern", "note"];
+const KINDS = ["coverage", "disclosure", "spatial", "framing", "continuity", "undo", "honesty"];
+
+const isObject = value => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const clip = (text, max) => text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+
+/** Pictures never ride in the digest's text: every dataUrl, at any depth, is dropped. */
+function withoutDataUrls(value) {
+	if (Array.isArray(value)) return value.map(withoutDataUrls);
+	if (!isObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "dataUrl").map(([key, entry]) => [key, withoutDataUrls(entry)]));
+}
+
+/** One receipt, verbatim but bounded: no image bytes, at most 8 delta rows and 12 warnings. */
+function boundReceipt(receipt) {
+	const bounded = withoutDataUrls(receipt);
+	if (!isObject(bounded)) return bounded;
+	if (Array.isArray(bounded.delta) && bounded.delta.length > SUPERVISOR_LIMITS.delta) {
+		bounded.deltaOmitted = bounded.delta.length - SUPERVISOR_LIMITS.delta;
+		bounded.delta = bounded.delta.slice(0, SUPERVISOR_LIMITS.delta);
+	}
+	if (Array.isArray(bounded.warnings) && bounded.warnings.length > SUPERVISOR_LIMITS.warnings) {
+		bounded.warningsOmitted = bounded.warnings.length - SUPERVISOR_LIMITS.warnings;
+		bounded.warnings = bounded.warnings.slice(0, SUPERVISOR_LIMITS.warnings);
+	}
+	return bounded;
+}
+
+const refusalOf = (code, message, tool) => REFUSAL_CODES.includes(code) ? [{ code, message: clip(String(message ?? ""), 400), ...(tool ? { tool } : {}) }] : [];
+
+/** What a turn's frames say about it: whether it authored anything, the
+ * refusals it met, its tool calls and its receipts (read-only results such as
+ * inspect_studio are calls, not receipts). */
+function analyseTurnFrames(frames = []) {
+	const names = new Map();
+	const calls = [], receipts = [], refusals = [];
+	let authored = false;
+	for (const frame of Array.isArray(frames) ? frames : []) {
+		if (frame?.type === "tool.start") {
+			names.set(frame.callId, frame.name);
+			calls.push({ callId: frame.callId, name: frame.name, args: clip(JSON.stringify(frame.args ?? {}), SUPERVISOR_LIMITS.args) });
+		} else if (frame?.type === "tool.done") {
+			const name = names.get(frame.callId);
+			const call = calls.find(entry => entry.callId === frame.callId);
+			if (call) call.ok = frame.ok === true;
+			if (frame.ok !== true) {
+				const error = String(frame.error ?? "");
+				const match = /^([A-Z][A-Z_]+):\s*([\s\S]*)$/.exec(error);
+				if (call) call.error = clip(error, 400);
+				if (match) refusals.push(...refusalOf(match[1], match[2], name));
+				continue;
+			}
+			const result = frame.result;
+			if (!isObject(result)) continue;
+			if (result.authored === true) authored = true;
+			if (result.ok === false) refusals.push(...refusalOf(result.code ?? result.error?.code, result.message ?? result.error?.message, name));
+			if (name !== "inspect_studio" && (typeof result.receiptId === "string" || typeof result.authored === "boolean" || isObject(result.checks))) receipts.push({ tool: name ?? null, receipt: result });
+		} else if (frame?.type === "receipt" && isObject(frame.receipt)) {
+			if (frame.receipt.authored === true) authored = true;
+			if (frame.receipt.ok === false) refusals.push(...refusalOf(frame.receipt.code, frame.receipt.message, null));
+			receipts.push({ tool: "turn", receipt: frame.receipt });
+		}
+	}
+	return { authored, refusals, calls: calls.map(({ callId: _callId, ...call }) => call), receipts };
+}
+
+/** Pure read-only turns and questions are not reviewed: only a turn that
+ * authored something or met a refusal is. */
+export const shouldSupervise = frames => {
+	const { authored, refusals } = analyseTurnFrames(frames);
+	return authored || refusals.length > 0;
+};
+
+function imagePart(image) {
+	const match = /^data:([^;,]+);base64,(.*)$/.exec(image?.dataUrl ?? "");
+	return match ? { type: "image", data: match[2], mimeType: match[1] } : null;
+}
+
+/** The ACTION SCHEMAS block: whole schemas in the order given while they fit
+ * the byte budget; the ids that did not fit are named, never half-quoted. */
+function boundSchemas(schemas) {
+	const kept = {}, omitted = [];
+	let size = 2;
+	for (const entry of Array.isArray(schemas) ? schemas : []) {
+		if (typeof entry?.id !== "string" || !isObject(entry.input)) continue;
+		const cost = JSON.stringify({ [entry.id]: entry.input }).length;
+		if (size + cost > SUPERVISOR_LIMITS.schemaBytes) { omitted.push(entry.id); continue; }
+		kept[entry.id] = entry.input;
+		size += cost;
+	}
+	return omitted.length ? { ...kept, omitted } : kept;
+}
+
+/** The digest the reviewer reads: a compact JSON-ish text block plus at most
+ * five pi ImageContent parts, in the order the text lists them. `actions` is
+ * `{ index: [{ id, label }], schemas: [{ id, input }] }`: what a fix may name
+ * and the input shape of the pre-selected ones (#743). */
+export function buildSupervisorInput({ request = "", frames = [], reply = "", geometry = null, refusals, images = [], notes = [], actions = null } = {}) {
+	const turn = analyseTurnFrames(frames);
+	const pictures = (Array.isArray(images) ? images : []).map(image => ({ image, part: imagePart(image) })).filter(entry => entry.part).slice(0, SUPERVISOR_LIMITS.images);
+	const section = (name, value) => `${name}: ${JSON.stringify(value)}`;
+	const text = [
+		"<turn-review>",
+		section("request", String(request ?? "")),
+		section("toolCalls", turn.calls),
+		section("receipts", turn.receipts.map(entry => ({ tool: entry.tool, ...boundReceipt(entry.receipt) }))),
+		section("refusals", Array.isArray(refusals) ? refusals : turn.refusals),
+		section("reply", clip(String(reply ?? ""), SUPERVISOR_LIMITS.reply)),
+		section("geometry", geometry ?? { note: "no geometry facts were measured" }),
+		section("images", pictures.map((entry, index) => `${index + 1} ${entry.image.label ?? "image"}${entry.image.width ? ` (${entry.image.width}x${entry.image.height})` : ""}`)),
+		...(notes.length ? [section("evidenceNotes", notes)] : []),
+		section("ACTIONS", (Array.isArray(actions?.index) ? actions.index : []).filter(row => typeof row?.id === "string").map(row => typeof row.label === "string" && row.label ? `${row.id} (${row.label})` : row.id)),
+		section("ACTION SCHEMAS", boundSchemas(actions?.schemas)),
+		"</turn-review>",
+	].join("\n");
+	return { text, images: pictures.map(entry => entry.part) };
+}
+
+/** The first balanced {...} block of a reply, string-aware. */
+function firstJsonBlock(text) {
+	const start = text.indexOf("{");
+	if (start === -1) return null;
+	let depth = 0, inString = false, escaped = false;
+	for (let index = start; index < text.length; index += 1) {
+		const char = text[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+		} else if (char === "\"") inString = true;
+		else if (char === "{") depth += 1;
+		else if (char === "}" && --depth === 0) return text.slice(start, index + 1);
+	}
+	return null;
+}
+
+/** The reviewer's verdict, validated, or null for anything that is not one. */
+export function parseSupervisorVerdict(text) {
+	if (typeof text !== "string") return null;
+	const block = firstJsonBlock(text);
+	if (!block) return null;
+	let value;
+	try { value = JSON.parse(block); } catch { return null; }
+	if (!isObject(value) || typeof value.summary !== "string" || !Array.isArray(value.items) || !Array.isArray(value.issues)) return null;
+	const items = value.items.map(item => isObject(item) && typeof item.text === "string" && ITEM_STATUSES.includes(item.status) && typeof item.evidence === "string"
+		? { text: item.text, status: item.status, evidence: item.evidence } : null);
+	// A fix rides along unvalidated here; validateFixes keeps or drops it.
+	const issues = value.issues.map(issue => isObject(issue) && SEVERITIES.includes(issue.severity) && KINDS.includes(issue.kind) && typeof issue.text === "string" && typeof issue.evidence === "string"
+		? { severity: issue.severity, kind: issue.kind, text: issue.text, evidence: issue.evidence, ...(issue.fix !== undefined && issue.fix !== null ? { fix: issue.fix } : {}) } : null);
+	if (items.includes(null) || issues.includes(null)) return null;
+	return { items, issues, summary: value.summary };
+}
+
+/**
+ * The fixes a note may hand the next turn (#743). A fix survives only when its
+ * action is in the turn's action index and its args are an object carrying
+ * every key the action's schema requires (when the schema was read). Every
+ * other fix is removed from its issue and reported with the reason.
+ */
+export function validateFixes(issues, { index = [], schemas = [] } = {}) {
+	const known = new Set((Array.isArray(index) ? index : []).map(row => typeof row === "string" ? row : row?.id).filter(id => typeof id === "string"));
+	const inputs = new Map((Array.isArray(schemas) ? schemas : []).filter(entry => typeof entry?.id === "string" && isObject(entry.input)).map(entry => [entry.id, entry.input]));
+	const dropped = [];
+	const kept = (Array.isArray(issues) ? issues : []).map((issue, issueIndex) => {
+		if (!isObject(issue) || issue.fix === undefined) return issue;
+		const { fix, ...rest } = issue;
+		const action = typeof fix?.action === "string" ? fix.action : null;
+		const required = Array.isArray(inputs.get(action)?.required) ? inputs.get(action).required : [];
+		const missing = isObject(fix?.args) ? required.filter(key => !Object.hasOwn(fix.args, key)) : [];
+		const reason = !isObject(fix) || !action ? "malformed fix"
+			: !known.has(action) ? "unknown action"
+				: !isObject(fix.args) ? "args is not an object"
+					: missing.length ? `missing required key ${missing.map(key => `"${key}"`).join(", ")}` : null;
+		if (!reason) return { ...rest, fix: { action, args: fix.args } };
+		dropped.push({ issueIndex, action, reason });
+		return rest;
+	});
+	return { issues: kept, dropped };
+}
+
+const verdictCounts = issues => Object.fromEntries(SEVERITIES.map(severity => [severity, issues.filter(issue => issue.severity === severity).length]));
+
+const redact = message => clip(String(message ?? "unknown failure").replace(/data:[^\s"']+/gi, "[image]").replace(/\b(?:sk-or-|sk-ant-|sk-|Bearer\s+|eyJ)[\w.\-+/=]+/gi, "[redacted]").replace(/\s+/g, " ").trim(), 200);
+
+/**
+ * What the reviewer gets to see beyond the frames, read from the editor after
+ * the turn: geometry facts for the shots the turn touched (a framing
+ * verify_result the sidecar issues itself), the current shot frame, the top
+ * view and one frame per shot the turn created. Every piece is optional; what
+ * could not be read becomes a note instead of a failure.
+ */
+async function gatherSupervisorEvidence({ hub, workspaceHandle, admission, baseline, receipts, actionIndex = [] }) {
+	const notes = [], images = [];
+	const command = (name, args, options) => options ? hub.command(name, args, workspaceHandle, options) : hub.command(name, args, workspaceHandle);
+	// What a fix may name: the turn's own action index, and the input schemas
+	// of the pre-selected actions it declares (#743).
+	const index = (Array.isArray(actionIndex) ? actionIndex : []).filter(row => typeof row?.id === "string").map(row => ({ id: row.id, ...(typeof row.label === "string" ? { label: row.label } : {}) }));
+	const wanted = SUPERVISOR_FIX_ACTIONS.filter(id => index.some(row => row.id === id));
+	let schemas = [];
+	if (wanted.length) {
+		try {
+			const result = await command("inspect_studio", { scope: "actions", ids: wanted });
+			schemas = (Array.isArray(result?.actions) ? result.actions : []).filter(row => wanted.includes(row?.id) && isObject(row.input)).map(row => ({ id: row.id, input: row.input }));
+		} catch (error) { notes.push(`action schemas unavailable: ${redact(error?.message)}`); }
+	}
+	const envelope = (name, args) => ({ name, args, commandId: admission.commandId(), host: admission.host, expectedRevision: admission.revision });
+	let context = null;
+	try { context = await admission.refresh(); } catch (error) { notes.push(`scene context unavailable: ${redact(error?.message)}`); }
+	const shots = Array.isArray(context?.shots) ? context.shots : [];
+	const shotIds = new Set(shots.map(shot => shot.id));
+	const before = new Set((Array.isArray(baseline?.shots) ? baseline.shots : []).map(shot => shot.id));
+	const touched = [...new Set(receipts.flatMap(entry => Array.isArray(entry.receipt?.affectedIds) ? entry.receipt.affectedIds : []))].filter(id => shotIds.has(id));
+	let geometry;
+	const targets = touched.length ? touched : context?.shot?.id ? [context.shot.id] : shots[0] ? [shots[0].id] : [];
+	if (!targets.length) geometry = { note: "no shot exists; geometry skipped" };
+	else {
+		try {
+			const result = await command("verify_result", envelope("verify_result", { targets, checks: ["framing"] }));
+			geometry = isObject(result?.geometry) ? { shotIds: targets, ...result.geometry }
+				: { note: result?.ok === false ? `verify_result refused: ${result.code ?? result.error?.code ?? "error"}` : "the editor returned no geometry facts" };
+		} catch (error) { geometry = { note: `geometry unavailable: ${error?.code ? `${error.code}: ` : ""}${redact(error?.message)}` }; }
+	}
+	// The editor renders at the size it is asked for, so an oversized capture is
+	// re-requested at 1280 px wide rather than resized here.
+	const capture = async (name, label) => {
+		const named = typeof label === "string" ? label : name;
+		try {
+			let shot = await command(name, {});
+			if (shot?.width > SUPERVISOR_LIMITS.imageWidth && shot?.height > 0) {
+				const width = SUPERVISOR_LIMITS.imageWidth, height = Math.round(shot.height * width / shot.width);
+				const smaller = await command(name, { output: { width, height } });
+				if (smaller?.dataUrl?.startsWith("data:image/")) shot = smaller;
+				else notes.push(`${named} kept at ${shot.width} px wide: the editor did not render a smaller copy`);
+			}
+			if (!shot?.dataUrl?.startsWith("data:image/")) { notes.push(`${named} unavailable: the editor returned no image`); return; }
+			images.push({ label: typeof label === "function" ? label(shot) : label, dataUrl: shot.dataUrl, width: shot.width, height: shot.height });
+		} catch (error) { notes.push(`${named} unavailable: ${redact(error?.message)}`); }
+	};
+	await capture("capture_framing_png", shot => `current shot frame (shot ${shot.shotId ?? "none"}, frame ${shot.frame ?? "?"})`);
+	await capture("capture_plan_png", "top view (plan) with subject labels and the shot camera wedge");
+	const created = touched.filter(id => !before.has(id)).map(id => shots.find(shot => shot.id === id)).filter(shot => Number.isSafeInteger(shot?.range?.startFrame)).slice(0, SUPERVISOR_LIMITS.createdShots);
+	const original = context?.view?.frame;
+	if (created.length && Number.isSafeInteger(original)) {
+		const operate = async frame => {
+			const receipt = await command("operate_studio", envelope("operate_studio", { frame }));
+			if (Number.isSafeInteger(receipt?.revision?.after)) admission.revision = receipt.revision.after;
+			if (receipt?.ok === false) throw Object.assign(new Error(receipt.message ?? "operate_studio refused"), { code: receipt.code });
+		};
+		try {
+			for (const shot of created) {
+				if (images.length >= SUPERVISOR_LIMITS.images) break;
+				try { await operate(shot.range.startFrame); }
+				catch (error) { notes.push(`shot ${shot.id} frame unavailable: ${redact(error?.message)}`); continue; }
+				await capture("capture_framing_png", `created shot ${shot.name ?? shot.id} (${shot.id}) at its start frame ${shot.range.startFrame}`);
+			}
+		} finally {
+			try { await operate(original); } catch (error) { notes.push(`playhead not restored to frame ${original}: ${redact(error?.message)}`); }
+		}
+	}
+	return { geometry, images: images.slice(0, SUPERVISOR_LIMITS.images), notes, actions: { index, schemas } };
+}
+
+/**
+ * Review one finished turn. Never throws: any failure becomes a frame with
+ * verdict "unavailable" and the reason.
+ */
+export async function runSupervisor({ registry, modelKey, effort = "high", turnId, request, frames, reply, hub, workspaceHandle, admission, baseline, actions = [], now = () => Date.now(), timeoutMs = SUPERVISOR_LIMITS.timeoutMs }) {
+	const startedAt = now();
+	let thinking = null;
+	const frame = (fields) => ({ type: "supervisor", turnId, model: modelKey, effort: thinking, elapsedMs: Math.max(0, Math.round(now() - startedAt)), ...fields });
+	const unavailable = reason => frame({ verdict: "unavailable", summary: "", items: [], issues: [], fixes: [], droppedFixes: [], counts: { ...verdictCounts([]), fixes: 0 }, reason: redact(reason) });
+	try {
+		const { resolveModel, resolveEffort } = await import("./providers.mjs");
+		const slash = modelKey.indexOf("/");
+		const provider = slash === -1 ? "openai-codex" : modelKey.slice(0, slash);
+		const model = registry.getModel(provider, slash === -1 ? modelKey : modelKey.slice(slash + 1)) ?? (await resolveModel(modelKey, { models: registry })).model;
+		const level = await resolveEffort(model, effort);
+		thinking = level;
+		const turn = analyseTurnFrames(frames);
+		const evidence = await gatherSupervisorEvidence({ hub, workspaceHandle, admission, baseline, receipts: turn.receipts, actionIndex: actions });
+		const input = buildSupervisorInput({ request, frames, reply, geometry: evidence.geometry, refusals: turn.refusals, images: evidence.images, notes: evidence.notes, actions: evidence.actions });
+		const message = await registry.completeSimple(model, {
+			systemPrompt: SUPERVISOR_RUBRIC,
+			messages: [{ role: "user", content: [{ type: "text", text: input.text }, ...input.images], timestamp: Date.now() }],
+		}, { ...(level && level !== "off" ? { reasoning: level } : {}), signal: AbortSignal.timeout(timeoutMs) });
+		if (message?.stopReason === "error" || message?.stopReason === "aborted") return unavailable(message.errorMessage || `the reviewer request ${message.stopReason === "aborted" ? "timed out" : "failed"}`);
+		const text = (Array.isArray(message?.content) ? message.content : []).filter(part => part?.type === "text").map(part => part.text).join("");
+		const verdict = parseSupervisorVerdict(text);
+		if (!verdict) return unavailable("the reviewer did not answer with a valid verdict");
+		const { issues, dropped } = validateFixes(verdict.issues, evidence.actions);
+		const fixes = issues.flatMap((issue, issueIndex) => issue.fix ? [{ issueIndex, severity: issue.severity, action: issue.fix.action, args: issue.fix.args }] : []);
+		return frame({ verdict: "reviewed", summary: verdict.summary, items: verdict.items, issues, fixes, droppedFixes: dropped, counts: { ...verdictCounts(issues), fixes: fixes.length } });
+	} catch (error) {
+		return unavailable(error?.message);
+	}
+}

package/bin/agent/video-adapters.mjs

@@ -154,13 +154,6 @@ function preferredVideoOutputNodes(workflow) {
 const isH3Node = (node) => /minimax.?h3|h3.*video/i.test(String(node?.class_type || ""));
 const isLoadImageNode = (node) => /loadimage/i.test(String(node?.class_type || ""));
 const isCompositeNode = (node) => /imagecomposite|compositeimage|imagemattecomposite/i.test(String(node?.class_type || ""));
-const isMaskNode = (node) => {
-	if (isCompositeNode(node)) return false;
-	// A generic/static mask can hide a broken tracker and would not preserve a
-	// moving performer across frames. Only accept a temporal SAM3/tracked-mask
-	// node on the compositor path.
-	return /sam3[_-]?(videotrack|tracktomask)|tracktomask|videomask/i.test(String(node?.class_type || ""));
-};
 
 function h3GuardError(message, reason) {
 	return Object.assign(new Error(message), {

package/bin/codex-auth.mjs

@@ -8,10 +8,10 @@ import { writeSecureJson } from "./agent/secure-file.mjs";
 import { readKeys } from "./agent/provider-keys.mjs";
 import { PROVIDERS } from "./agent/providers.mjs";
 
-export const AUTHORIZE_ENDPOINT = "https://auth.openai.com/oauth/authorize";
-export const TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
-export const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
-export const SCOPE = "openid profile email offline_access";
+const AUTHORIZE_ENDPOINT = "https://auth.openai.com/oauth/authorize";
+const TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const SCOPE = "openid profile email offline_access";
 const DEFAULT_FILE = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "cozyclay", "codex-auth.json");
 const tokenFile = process.env.COZYCLAY_CODEX_AUTH_FILE || DEFAULT_FILE;
 let tokens = null;

package/bin/live/cli.mjs

@@ -29,8 +29,9 @@ const USAGE = `cclay live - drive a running CozyClay studio from a terminal
   cclay live frame-shot --subject <id> --exact px,py,pz,lx,ly,lz,focal
   cclay live operate [--select object:<id>] [--frame N] [--mode scene|camera|motion]
                                          [--play | --pause]
-  cclay live verify --receipt <id> --checks placement,framing
-                                         [--visual frame --out check.png]
+  cclay live verify (--receipt <id> | --targets a,b) --checks placement,framing
+                                         [--range whole_clip|start:end] [--strict]
+                                         [--visual frame|contact_sheet --out check.png]
   cclay live undo --receipt <id>
   cclay live commands [--ids a,b]        the commands the editor registers; ids add schemas
   cclay live run <id> [--args '<json>']  any command the editor registers, admitted like
@@ -49,7 +50,7 @@ Exit codes: 0 ok - 1 editor or receipt error - 2 usage - 3 no hub -
 
 class UsageError extends Error {}
 
-const BOOLEAN_FLAGS = new Set(["--pretty", "--wait", "--framing", "--play", "--pause"]);
+const BOOLEAN_FLAGS = new Set(["--pretty", "--wait", "--framing", "--play", "--pause", "--strict"]);
 const GLOBAL_FLAGS = ["--workspace", "--timeout", "--pretty", "--live-port"];
 const VERBS = new Map([
 	["status", { flags: ["--wait"] }],
@@ -61,7 +62,7 @@ const VERBS = new Map([
 	["patch", { flags: ["--target", "--set"], command: "patch_elements" }],
 	["frame-shot", { flags: ["--subject", "--size", "--view", "--level", "--side", "--focal", "--exact"] }],
 	["operate", { flags: ["--select", "--frame", "--mode", "--play", "--pause"] }],
-	["verify", { flags: ["--receipt", "--checks", "--visual", "--out"] }],
+	["verify", { flags: ["--receipt", "--targets", "--checks", "--range", "--strict", "--visual", "--out"] }],
 	["undo", { flags: ["--receipt"] }],
 	["commands", { flags: ["--ids"] }],
 	["run", { flags: ["--args"], argument: "command id" }],
@@ -185,6 +186,15 @@ const integerFlag = (flags, key) => {
 	if (!Number.isSafeInteger(value)) throw new UsageError(`${key} must be an integer`);
 	return value;
 };
+const frameRangeFlag = (flags, key) => {
+	const raw = String(flags.get(key));
+	if (raw === "whole_clip") return raw;
+	const match = /^(\d+):(\d+)$/.exec(raw);
+	if (!match) throw new UsageError(`${key} must be whole_clip or start:end`);
+	const startFrame = Number(match[1]), endFrameExclusive = Number(match[2]);
+	if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrameExclusive) || endFrameExclusive <= startFrame) throw new UsageError(`${key} must have a nonempty start:end range`);
+	return { startFrame, endFrameExclusive };
+};
 const jsonFlag = (flags, key) => {
 	let parsed;
 	try {
@@ -247,7 +257,6 @@ function patchArguments(flags, verb) {
 	const target = colon < 0 ? { kind: raw } : { kind: raw.slice(0, colon), id: raw.slice(colon + 1) };
 	required(flags, "--set", verb);
 	const set = jsonFlag(flags, "--set");
-	if (set === null || typeof set !== "object" || Array.isArray(set)) throw new UsageError(`${verb} expects --set '{"path": value}'`);
 	return { ops: [{ target, set }] };
 }
 
@@ -320,7 +329,7 @@ async function runVerb({ client, verb, spec, name, flags }) {
 		}
 	};
 	const admitted = async (commandName, args, { context, options = forwarded } = {}) => {
-		const envelope = admissionEnvelope(commandName, args, context ?? (await command("inspect_studio", { scope: "selection" }))?.context);
+		const envelope = admissionEnvelope(commandName, args, context ?? await command("inspect_studio", { scope: "selection" }));
 		try {
 			const value = await command(commandName, envelope, options);
 			if (value?.ok === false) throw receiptFailure(value);
@@ -412,11 +421,17 @@ async function runVerb({ client, verb, spec, name, flags }) {
 	if (verb === "operate") return admitted("operate_studio", operateArguments(flags));
 
 	if (verb === "verify") {
-		const args = { receiptId: required(flags, "--receipt", verb), checks: commaList(required(flags, "--checks", verb)) };
+		const hasReceipt = flags.has("--receipt"), hasTargets = flags.has("--targets");
+		if (hasReceipt === hasTargets) throw new UsageError("verify needs exactly one of --receipt or --targets");
+		const args = { checks: commaList(required(flags, "--checks", verb)), ...(hasReceipt ? { receiptId: required(flags, "--receipt", verb) } : { targets: commaList(required(flags, "--targets", verb)) }) };
+		if (flags.has("--range")) args.range = frameRangeFlag(flags, "--range");
 		const visual = flags.has("--visual") ? String(flags.get("--visual")) : "none";
 		if (visual !== "none") args.visual = visual;
 		const out = visual === "none" ? null : resolvePath(required(flags, "--out", verb));
 		const value = await admitted("verify_result", args);
+		if (flags.get("--strict") === true && value?.checks?.framing?.issueFrames?.length) {
+			throw new LiveCliError("VERIFICATION_FAILED", `Sampled framing found ${value.checks.framing.issueFrames.length} problematic frame(s).`, { details: value.checks.framing.issueFrames });
+		}
 		if (out === null) return value;
 		const written = [];
 		for (const [index, reference] of (value?.visualRefs ?? []).entries()) {
@@ -446,7 +461,7 @@ async function runVerb({ client, verb, spec, name, flags }) {
 		// at and the deadline it needs, which --timeout overrides.
 		const inspected = await command("inspect_studio", { scope: "actions", ids: [name] });
 		const deadline = timeoutMs ?? inspected?.actions?.find((row) => row.id === name)?.timeoutMs;
-		return admitted("run_action", { action: name, args }, { context: inspected?.context, options: deadline === undefined ? {} : { timeoutMs: deadline } });
+		return admitted("run_action", { action: name, args }, { context: inspected, options: deadline === undefined ? {} : { timeoutMs: deadline } });
 	}
 
 	if (verb === "cmd") return raw(() => command(name, flags.has("--args") ? jsonFlag(flags, "--args") : {}));

package/bin/live/client.mjs

@@ -11,7 +11,7 @@ import { randomUUID } from "node:crypto";
 
 import { readLiveEndpoint } from "../live-endpoint.mjs";
 
-export const DEFAULT_LIVE_PORT = 5184;
+const DEFAULT_LIVE_PORT = 5184;
 /** The hub caps one command at 300 s; give up a little past that, so a hub
  * that answers nothing at all can never hang a terminal forever. */
 const REQUEST_CEILING_MS = 330_000;

package/bin/live/studio.mjs

@@ -48,8 +48,11 @@ export const describeEditors = (editors) => editors.map((editor) => ({
  * carries no per-entity tokens, because the scene revision already bumps on
  * every authored change and a retired token only refuses a legitimate retry.
  */
-export function admissionEnvelope(name, args, context) {
-	if (!context?.host || !context.revision || !Array.isArray(context.entities)) {
+export function admissionEnvelope(name, args, inspected) {
+	// inspect_studio answers the host and revision at its top level; an older
+	// editor embedded a whole context. Admission needs only those two.
+	const context = inspected?.context ?? inspected;
+	if (!context?.host || !context.revision) {
 		throw new LiveCliError("EDITOR_ERROR", "The editor did not return a Studio context to admit this command against.");
 	}
 	const host = Object.fromEntries(IDENTITY.map((key) => [key, context.host[key]]));

package/bin/mcp-runtime.mjs

@@ -20,7 +20,7 @@ function probeMcpRuntime(runtime = MCP_RUNTIME) {
 	if (!existsSync(server)) throw new Error("MCP server is missing");
 	if (!existsSync(join(runtime, "tools", "ardy", "bridge.mjs"))) throw new Error("motion bridge is missing");
 	const runtimeRequire = createRequire(join(runtime, "package.json"));
-	for (const dependency of ["@modelcontextprotocol/sdk/server/mcp.js", "three", "ws", "zod"]) runtimeRequire.resolve(dependency);
+	for (const dependency of ["@modelcontextprotocol/sdk/server/mcp.js", "jpeg-js", "three", "ws", "zod"]) runtimeRequire.resolve(dependency);
 	return server;
 }
 
@@ -83,7 +83,7 @@ function installMcpRuntime() {
 				} catch {
 					try {
 						renameSync(staging, MCP_RUNTIME);
-					} catch (error) {
+					} catch {
 						// Another first run can publish its complete staging
 						// directory first. Accept that winner only after the
 						// same full probe; never execute a partial cache.

package/bin/telemetry-state.mjs

@@ -3,8 +3,8 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 export const TELEMETRY_NOTICE_VERSION = 1;
-export const POSTHOG_PROJECT_TOKEN = "phc_CpizzZ8VhSorSS8yEeQhdpUcvB2erp5xkCbnFD8HTJ5m";
-export const POSTHOG_API_HOST = "https://t.cozyclay.org";
+const POSTHOG_PROJECT_TOKEN = "phc_CpizzZ8VhSorSS8yEeQhdpUcvB2erp5xkCbnFD8HTJ5m";
+const POSTHOG_API_HOST = "https://t.cozyclay.org";
 // First-launch answers plus the `npx cozyclay --via <source>` values the
 // landing page's copy commands carry (#466). Mirrors analytics HEARD_FROM_SOURCES.
 export const FIRST_LAUNCH_SOURCES = Object.freeze(["x", "hn", "reddit", "github", "friend", "other", "site", "playground"]);
@@ -111,7 +111,7 @@ export function takeRuntimeTelemetryConfig(
 ) {
 	const existing = readTelemetryState(stateFile);
 	const telemetryEnabled = officialPackage && effectiveTelemetryEnabled(existing, env);
-	const internalQa = telemetryEnabled && existing.internalQa === true;
+	const internalQa = telemetryEnabled && existing.internalQa;
 	let installationId = existing.installationId;
 	const firstLaunch = telemetryEnabled && !existing.firstLaunchedAt;
 	const patch = {};

package/dist/app/index.html

@@ -34,13 +34,13 @@
     <title>CozyClay Studio — 3D staging and previs in your browser</title>
 
     <script defer src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token": "6a4384d1375d4ffc8a30a6346a8ad1a0"}'></script>
-    <script type="module" crossorigin src="/assets/app-BxBLC6GT.js"></script>
+    <script type="module" crossorigin src="/assets/app-DAuvKPP8.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-MVZOEW8O.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-DgT28ZiV.js">
-    <link rel="modulepreload" crossorigin href="/assets/shot-prompt-hN0j_O-p.js">
-    <link rel="stylesheet" crossorigin href="/assets/shot-prompt-CbqWcWYi.css">
-    <link rel="stylesheet" crossorigin href="/assets/app-CJdxvnrl.css">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-C9pMpW7s.js">
+    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-msLI71g1.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-DKkpjKBV.js">
+    <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-DjJ_cJ2R.css">
+    <link rel="stylesheet" crossorigin href="/assets/app-B_2XB9rw.css">
   </head>
   <body>
     <div id="root">