cozyclay 2.0.0 → 2.1.0

package/bin/agent/agent-routes.mjs

@@ -10,6 +10,7 @@ import { createAgentTools, SYSTEM_PROMPT, pickWorkspace } from "./agent-tools.mj
 import { createVideoAdapters, validateFalVideoRequest } from "./video-adapters.mjs";
 import { createSessionStore, transcriptFromHistory } from "./session-store.mjs";
 import { createAgentRunner } from "./agent-runner.mjs";
+import { STUDIO_SYSTEM_PROMPT_STORYBOARD } from "./studio-prompt.mjs";
 
 // Values the codex backend accepts for reasoning.effort (its own 400 lists them).
 export const REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
@@ -19,7 +20,7 @@ const json = (res, status, value) => {
 	res.end(JSON.stringify(value));
 };
 
-export function allowAgentOrigin(req, port) {
+function allowAgentOrigin(req, port) {
 	return [`http://127.0.0.1:${port}`, `http://${"local" + "host"}:${port}`].includes(req.headers.origin)
 		|| (req.headers.origin === undefined && req.method === "GET"
 			&& [`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host));
@@ -27,6 +28,8 @@ export function allowAgentOrigin(req, port) {
 
 // Two 1920x1080 PNG data URLs (frame + reference) fit comfortably in this.
 const IMAGE_BODY_LIMIT = 24 * 1024 * 1024;
+// The sizes gpt-image-2 accepts; omitted means the backend's own choice.
+const IMAGE_SIZES = ["auto", "1024x1024", "1536x1024", "1024x1536"];
 
 // Attached scene references (#167): identity sheets and the environment
 // reference. Capped because every one of them is another full image the
@@ -41,6 +44,10 @@ const ATTACHMENTS_MAX = 4;
 const ATTACHMENT_MAX_CHARS = 6_000_000;
 const TURN_BODY_LIMIT = ATTACHMENTS_MAX * ATTACHMENT_MAX_CHARS + 64 * 1024;
 
+// How long GET /agent/turn/<id>/supervisor holds a request for a review that
+// is still running before it answers 204 (#728).
+const SUPERVISOR_WAIT_MS = 180_000;
+
 /** Reject anything that is not a short list of inline {dataUrl, name?} images.
  * The Studio envelope validates its own copy; this is the legacy body's. */
 function validAttachments(attachments) {
@@ -60,7 +67,6 @@ const agentToolCategory = (name) => {
 	// Studio families are authored edits or reads; the analytics vocabulary has
 	// no Studio-specific category, so a write says so and everything else does not.
 	if (["arrange_objects", "arrange_characters", "patch_elements", "frame_shot", "undo_edit"].includes(name)) return "scene_write";
-	if (["inspect_studio", "operate_studio", "verify_result", "generate_motion"].includes(name)) return "other";
 	if (name === "run_workflow") return "workflow_run";
 	if (name === "describe_workflow" || name === "focus_workflow_node") return "workflow_read";
 	if (["add_workflow_node", "update_workflow_node", "remove_workflow_node", "connect_workflow_nodes", "disconnect_workflow_nodes", "set_workflow_node_output"].includes(name)) return "workflow_write";
@@ -75,6 +81,55 @@ const agentFailureCode = (error, signal, tool = false) => advisory(() => {
 	if (error?.status === 429) return "rate_limited";
 	return tool ? "tool_failed" : "upstream";
 }, tool ? "tool_failed" : "upstream");
+/**
+ * One user message is one editor transaction: every Studio turn whose editor
+ * reports a previsMode opens agent.turn.begin and closes agent.turn.finish, so
+ * all of its mutations land as ONE history entry and one receipt frame. A
+ * context without a previsMode comes from an editor that predates turn
+ * transactions and runs unwrapped. rollback() cancels the open transaction
+ * (restoring the pre-turn document) and reopens it for the rest of the turn.
+ */
+const agentTurn = ({ hub, context, turnId, admission }) => {
+	const wrapped = Boolean(context.scene?.previsMode);
+	const host = Object.fromEntries(["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"].map(key => [key, context.host[key]]));
+	const control = async action => {
+		const receipt = await hub.command("run_action", {
+			name: "run_action", args: { action, args: { turnId } }, turnId,
+			commandId: randomUUID(), host, expectedRevision: admission.revision,
+		}, context.host.workspaceHandle);
+		if (!receipt.ok) throw Object.assign(new Error(receipt.message), { code: receipt.code });
+		return receipt;
+	};
+	const open = async () => { await control("agent.turn.begin"); admission.turnId = turnId; };
+	return {
+		async rollback() {
+			if (admission.turnId !== turnId) return null;
+			delete admission.turnId;
+			const receipt = await control("agent.turn.cancel");
+			await admission.refresh();
+			await open();
+			return receipt;
+		},
+		run: start => async function* (input) {
+			if (!wrapped) { yield* start(input); return; }
+			await open();
+			let terminal;
+			try {
+				for await (const frame of start(input)) {
+					if (frame.type === "done") terminal = frame; else yield frame;
+				}
+			} finally {
+				// A rollback whose reopen failed has already closed the transaction.
+				if (admission.turnId === turnId) {
+					delete admission.turnId;
+					const receipt = await control("agent.turn.finish");
+					if (receipt.authored) yield { type: "receipt", receipt };
+				}
+			}
+			if (terminal) yield terminal;
+		},
+	};
+};
 // These existing canvas commands only return a node/edge after publishing a
 // new insertion. Read/focus, generic accepted responses, update no-ops and run
 // outputs (which can echo old values) are deliberately not application proof.
@@ -134,6 +189,8 @@ function validReferences(references) {
  * owns the geometry, each character sheet owns one performer's look and the
  * environment reference owns the location.
  */
+export const FRAME_COMPOSITION_GUIDANCE = "Use the first image (a clay blocking frame) as the layout: keep its composition and camera angle, and keep the pose but make it look natural. Render it as:";
+
 export function referenceGuidance(references = []) {
 	const list = Array.isArray(references) ? references : [];
 	if (!list.length) return "";
@@ -143,6 +200,8 @@ export function referenceGuidance(references = []) {
 			lines.push(`Character ${entry.name || "reference"}: match the identity, face, hair and wardrobe from the attached character sheet.`);
 		} else if (entry.role === "environment") {
 			lines.push("Environment: take the location look, materials, palette and lighting from the attached environment reference.");
+		} else if (entry.role === "reference") {
+			lines.push(`Reference ${entry.name || "image"}: use it for the look the prompt asks for (subject, wardrobe, style); keep the exact pose, body position and camera framing of the first image.`);
 		}
 	}
 	return `\n${lines.join("\n")}`;
@@ -174,7 +233,7 @@ function quotaEvent(codex, headers) {
 // one line — without it neither the log nor the panel can say why a turn died.
 const UPSTREAM_DETAIL_MAX = 200;
 export function sanitizeUpstreamDetail(body) {
-	let message = null;
+	let message;
 	try {
 		const parsed = JSON.parse(body);
 		const candidate = parsed?.error?.message ?? parsed?.error ?? parsed?.message ?? parsed?.detail;
@@ -249,7 +308,12 @@ function liveToolsRuntime(mcpRuntime) {
 	return liveToolsModules(mcpRuntime).then(async ([registry, { startLiveHub }]) => {
 		const owner = liveHubOwner();
 		const token = randomBytes(32).toString("hex");
-		const liveHub = await startLiveHub(Number(process.env.COZYCLAY_LIVE_PORT ?? 5184), { token, owner });
+		const livePort = Number(process.env.COZYCLAY_LIVE_PORT ?? 5184);
+		const liveHub = await startLiveHub(livePort, { token, owner });
+		// EADDRINUSE comes back as null: another CozyClay (or its dev server) owns
+		// the port, and the Studio page is built to connect to that port, so the
+		// pane would answer every turn with a misleading capability error.
+		if (!liveHub) console.error(`cozyclay: live hub port ${livePort} is already in use (another CozyClay or its dev server?); the Agent pane cannot drive this Studio until that port is free.`);
 		registry.setLiveHub(liveHub);
 		const handlers = registry.createToolHandlers().map((tool) => ({
 			...tool,
@@ -270,7 +334,7 @@ function liveToolsRuntime(mcpRuntime) {
 			publishLiveEndpoint({ port: liveHub.port, token, owner });
 			liveHub.server?.once("close", () => removeLiveEndpoint(liveHub.port));
 		}
-		return { liveHub, handlers };
+		return { liveHub, handlers, hubPortBusy: !liveHub ? livePort : null };
 	}).catch((error) => {
 		// The pane answers CAPABILITY_MISSING on use; the reason belongs on the
 		// launcher's terminal rather than nowhere.
@@ -280,7 +344,10 @@ function liveToolsRuntime(mcpRuntime) {
 	});
 }
 
-export function createAgentHandler({ auth = defaultAuth, codex, models, codexBaseUrl, cliproxyBaseUrl, env, fauxProvider, handlers, liveHub, mcpRuntime, port, studioRuntime, clock = Date.now, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, sessionStore: injectedSessionStore } = {}) {
+// `supervisor` (#728) defaults off only under an injected scripted provider:
+// a test's script is an exact queue of replies, and a review would take one
+// meant for a later turn. The real sidecar never injects one.
+export function createAgentHandler({ auth = defaultAuth, codex, models, codexBaseUrl, cliproxyBaseUrl, env, fauxProvider, handlers, liveHub, mcpRuntime, port, studioRuntime, clock = Date.now, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, sessionStore: injectedSessionStore, supervisor = !fauxProvider } = {}) {
 	const requestContext = new AsyncLocalStorage();
 	codex ||= defaultClient(auth, requestContext);
 	const runtime = handlers !== undefined || liveHub !== undefined ? Promise.resolve({ handlers: handlers ?? [], liveHub }) : liveToolsRuntime(mcpRuntime);
@@ -342,6 +409,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		return owner;
 	};
 	const emitStudioEvent = (turnId, event) => {
+		// The supervisor note lands after the turn ended (#728): it joins the turn's
+		// record, terminal or not, but never resurrects one that was retired.
+		if (event.type === "supervisor" && !studioEvents.has(turnId)) return;
 		const record = studioEvents.get(turnId) || { next: 0, events: [], listeners: new Set(), terminal: false };
 		// Execution telemetry is advisory and is validated key-by-key in the
 		// browser: it carries no replay cursor, is never retained for a resume,
@@ -372,10 +442,10 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	});
 
 	const studioIdentity = host => Object.fromEntries(["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"].map(key => [key, host[key]]));
-	const writeStudioStream = (res, record, after = 0, req = null) => {
+	const writeStudioStream = (res, record, after = 0) => {
 		res.writeHead(200, { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache", connection: "keep-alive" }); res.flushHeaders?.();
 		let cursor = after; const send = event => {
-			if (res.destroyed) return;
+			if (res.destroyed || res.writableEnded) return;
 			if (event.eventSeq === undefined) { res.write(`data: ${JSON.stringify(event)}\n\n`); return; }
 			if (event.eventSeq > cursor) { cursor = event.eventSeq; res.write(`data: ${JSON.stringify(event)}\n\n`); }
 		};
@@ -396,8 +466,8 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	};
 	const handleStudioTurn = async (req, res, value, path) => {
 		const { StudioProtocolError, validateStudioContextFreshness } = await import("../../src/studio-agent-protocol.js");
-		const [{ createStudioTools }, { encodeStudioContext }] = await Promise.all([
-			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"),
+		const [{ createStudioTools }, { encodeStudioContext }, { createScriptTool }, { runSupervisor, shouldSupervise }] = await Promise.all([
+			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"), import("./script-tool.mjs"), import("./supervisor.mjs"),
 		]);
 		const hubDeps = await runtime; const hub = hubDeps.liveHub || liveHub;
 		if (path === "/agent/stop") {
@@ -425,48 +495,71 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			await session.modelSession?.abort?.("studio stop", acknowledged ? { quiet: true } : undefined);
 			json(res, 200, { ok: true, status: jobId ? "stopped" : "detached", ...(outcome ? { outcome: { status: outcome.status ?? null, code: outcome.code ?? null, mutated: outcome.mutated ?? null } } : {}) }); return true;
 		}
+		if (!studioRuntime && !hub && hubDeps.hubPortBusy) throw new StudioProtocolError("CAPABILITY_MISSING", `The Studio live hub could not start: port ${hubDeps.hubPortBusy} is in use by another CozyClay or its dev server. Free that port and relaunch.`);
 		if (!studioRuntime && (!hub?.command || !hub?.workspaceId)) throw new StudioProtocolError("CAPABILITY_MISSING", "Studio execution is not installed.");
 		if (!value.context.host.workspaceHandle) throw new StudioProtocolError("LIVE_HUB_UNAVAILABLE", "A connected editor handle is required.");
 		let session = studioSessions.get(value.sessionId);
 		const suppliedOwner = parseCookies(req).studio_owner;
 		if (session && suppliedOwner && session.owner !== suppliedOwner) throw new StudioProtocolError("AUTH_REQUIRED", "Studio session owner mismatch.");
+		const existing = session?.turns.get(value.turnId);
+		if (existing) { session.updatedAt = clock(); writeStudioStream(res, existing, 0); return true; }
+		let current;
+		try { current = studioRuntime?.readContext ? await studioRuntime.readContext(value.context.host) : await authoritativeStudioContext(value, hub); }
+		catch (error) { if (error instanceof StudioProtocolError) throw error; if (error?.code) throw new StudioProtocolError(error.code, error.message); throw new StudioProtocolError("CAPABILITY_MISSING", "The connected editor does not expose authoritative Studio context."); }
+		validateStudioContextFreshness(value.context, current);
+		// The session, and the owner token only this turn's response can hand
+		// the browser, exist only once the turn is admitted. Minting them before
+		// a refusal (the editor still reconnecting after a restart) left a
+		// session whose owner the browser never received: its cookie from the
+		// previous server then failed every retry with "owner mismatch".
 		if (!session) {
 			studioOwner(req, value.sessionId, true);
 			let persisted = null;
-			try { persisted = sessionStore.read(value.sessionId); } catch { persisted = null; }
+			try { persisted = sessionStore.read(value.sessionId); } catch { /* an unreadable history starts the session fresh */ }
 			session = { owner: studioOwnerTokens.get(value.sessionId), history: persisted?.history ?? [], persistedItems: persisted?.history?.length ?? 0, meta: persisted?.meta ?? null, turns: new Map(), controller: null, activeJobId: null, activeJobTurnId: null, motionJobIds: new Set(Array.isArray(persisted?.meta?.motionJobIds) ? persisted.meta.motionJobIds.filter(id => typeof id === "string") : []), host: null, updatedAt: clock() };
 			studioSessions.set(value.sessionId, session);
 		}
 		session.updatedAt = clock();
-		const existing = session.turns.get(value.turnId);
-		if (existing) { writeStudioStream(res, existing, 0, req); return true; }
-		let current;
-		try { current = studioRuntime?.readContext ? await studioRuntime.readContext(value.context.host) : await authoritativeStudioContext(value, hub); }
-		catch (error) { if (error instanceof StudioProtocolError) throw error; if (error?.code) throw new StudioProtocolError(error.code, error.message); throw new StudioProtocolError("CAPABILITY_MISSING", "The connected editor does not expose authoritative Studio context."); }
-		validateStudioContextFreshness(value.context, current);
 		if (studioRuntime?.handleTurn) { await studioRuntime.handleTurn(value, req, res); return true; }
 		const record = { next: 0, events: [], listeners: new Set(), terminal: false }; studioEvents.set(value.turnId, record); session.turns.set(value.turnId, record); session.host = studioIdentity(value.context.host);
 		res.setHeader("set-cookie", `studio_owner=${encodeURIComponent(session.owner)}; Path=/agent; HttpOnly; SameSite=Strict`);
-		const close = writeStudioStream(res, record, 0, req);
-		const send = event => emitStudioEvent(value.turnId, event);
+		const close = writeStudioStream(res, record, 0);
+		// What the supervisor reviews once the turn is over: every frame but text
+		// and telemetry, and the last stretch of text the model wrote.
+		const turnFrames = [];
+		let replySegment = "", lastReply = "";
+		const send = event => {
+			if (event.type === "text.delta") { replySegment += event.text ?? ""; lastReply = replySegment; }
+			else if (!["execution_telemetry", "execution_tool_started"].includes(event.type)) {
+				if (event.type === "tool.start") replySegment = "";
+				turnFrames.push(event);
+			}
+			emitStudioEvent(value.turnId, event);
+		};
 		// The Studio turn is measured exactly like the Workflow turn, correlated by
 		// the turn id the host already owns (the frozen envelope carries no room
 		// for a second one).
 		const telemetry = createTurnTelemetry(send, value.turnId);
 		let turnOutcome = "succeeded", turnFailureCode = null, toolFailed = false;
-		const controller = new AbortController(); session.controller = controller;
+		const controller = new AbortController(); session.controller = controller; session.activeTurnId = value.turnId;
 		// Admission is the document identity plus the exact scene revision each
 		// command expects. Per-entity tokens are deliberately absent: the revision
 		// already moves whenever any authored content changes, and a turn's second
 		// edit to the same entity would otherwise carry a token the first edit retired.
 		const admission = {
 			commandId: () => randomUUID(), host: studioIdentity(value.context.host), revision: value.context.revision.scene,
-			refresh: async () => {
-				// Read at the admitted host: a scene action may have opened another
-				// scene of this workspace during the turn (studio-tools adopts it).
+			// Read at the admitted host: a scene action may have opened another
+			// scene of this workspace during the turn (studio-tools adopts it).
+			snapshot: async () => {
 				const host = { ...value.context.host, ...admission.host };
-				const refreshed = studioRuntime?.readContext ? await studioRuntime.readContext(host) : await authoritativeStudioContext({ ...value, context: { ...value.context, host } }, hub);
+				return studioRuntime?.readContext ? await studioRuntime.readContext(host) : await authoritativeStudioContext({ ...value, context: { ...value.context, host } }, hub);
+			},
+			// Re-admits at the live revision and hands back the context it read, which
+			// the tools compare against what the agent last saw (studio-rebase.mjs).
+			refresh: async () => {
+				const refreshed = await admission.snapshot();
 				admission.revision = refreshed.revision.scene;
+				return refreshed;
 			},
 		};
 		// One motion generation per user message, whichever path starts it:
@@ -498,7 +591,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				if (session.activeJobId === jobId) { session.activeJobId = null; session.activeJobTurnId = null; }
 			}
 		};
-		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, session: { signal: controller.signal, admission, generation, onJob, actionIndex: current?.actionIndex ?? [] }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
+		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, previsMode: value.context.scene?.previsMode, session: { signal: controller.signal, admission, generation, onJob, actionIndex: current?.actionIndex ?? [], baseline: value.context }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
 		const motion = async args => {
 			// Private artifact IDs belonged to the retired sidecar runtime. Reuse
 			// retained editor takes through motion.loadVersion, not another installer.
@@ -519,12 +612,35 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				return { ...result, visualStatus: visual.visualStatus, imageId: visual.imageId, revision: visual.revision, receiptId: visual.receiptId, ...(visual.dataUrl ? { dataUrl: visual.dataUrl } : {}) };
 			},
 		}));
+		const turnTransaction = agentTurn({ hub, context: current, turnId: value.turnId, admission });
+		const script = createScriptTool({ tools: modelTools, signal: controller.signal, emit: send });
+		const scriptTool = {
+			...script,
+			// A script that fails after it edited the scene rolls the turn back, so
+			// the model retries from the pre-turn document, never from half a script.
+			handler: async (args, options) => {
+				const result = await script.handler(args, options);
+				if (result.ok || !result.calls.some(call => call.ok && Number.isSafeInteger(call.revision?.after) && call.revision.after !== call.revision.before)) return result;
+				const rollback = await turnTransaction.rollback();
+				return rollback ? { ...result, rollback: { status: "rolled_back", receiptId: rollback.receiptId, revision: rollback.revision, affectedIds: rollback.affectedIds.slice(0, 8) } } : result;
+			},
+		};
 		let frameObservation;
 		if (value.attachFrame) {
 			const captured = await hub.command("capture_framing_png", {}, value.context.host.workspaceHandle);
 			if (!captured?.dataUrl?.startsWith("data:image/")) throw new StudioProtocolError("TARGET_NOT_READY", "The current frame has no image bytes.");
 			const match = /^data:([^;]+);base64,(.*)$/.exec(captured.dataUrl);
 			frameObservation = { data: match[2], mimeType: match[1], revision: captured.revision, receiptId: captured.receiptId };
+		} else if (value.context.scene?.characterCount >= 2 || (value.context.shots?.length ?? 0) >= 1 || /샷|컷|카메라|커버리지|OTS|투샷|프레임|shot|camera|coverage|two-shot|framing/i.test(value.text || "")) {
+			// A staging or coverage request also sees the top-view plan; without it the turn just runs.
+			try {
+				const captured = await hub.command("capture_plan_png", {}, value.context.host.workspaceHandle);
+				const match = /^data:([^;]+);base64,(.*)$/.exec(captured?.dataUrl ?? "");
+				if (!match) throw new Error("The plan capture has no image bytes.");
+				frameObservation = { kind: "plan", data: match[2], mimeType: match[1], revision: captured.revision ?? value.context.revision?.scene ?? null, receiptId: captured.receiptId };
+			} catch (error) {
+				console.warn(`[agent] plan observation skipped: ${error.message}`);
+			}
 		}
 		const telemetryTools = new Map();
 		const emitFrame = frame => {
@@ -539,6 +655,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				toolFailed = true;
 				if (typeof frame.error === "string" && frame.error.startsWith("Validation failed for tool ")) frame.error = "INVALID_ARGUMENT: Unexpected field.";
 			}
+			// A command the sidecar re-sent once (stale revision, busy gesture) is
+			// marked on the frame itself; the receipt carries autoRebased and a warning.
+			if (frame.ok && frame.result?.autoRebased === true) frame.autoRebased = true;
 			send(frame);
 			if (record) {
 				record.execution.executed(frame.ok ? "succeeded" : (controller.signal.aborted ? "cancelled" : "failed"));
@@ -554,10 +673,15 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			if (frame.type === "done") {
 			if (turnOutcome === "succeeded" && !toolFailed) telemetry.finished("succeeded", null);
 			else telemetry.finished(turnOutcome, turnFailureCode || "tool_failed");
+			// Marked before the done frame leaves, so a client that asks for the
+			// review the moment its stream ends finds it pending, not absent.
+			// The author's own switch (value.supervisor === false) skips this turn's review.
+			if (supervisor && process.env.COZYCLAY_SUPERVISOR !== "off" && value.supervisor !== false && !controller.signal.aborted && shouldSupervise(turnFrames)) record.supervisor = "pending";
 			}
 			send(frame);
 		};
 		const persistenceMeta = { sceneName: value.context?.scene?.name ?? value.context?.sceneName ?? null, firstText: value.text, motionJobIds: [...session.motionJobIds] };
+		const modelKey = value.model || (fauxProvider ? `${fauxProvider.provider?.id || fauxProvider.provider || "faux"}/scripted` : "gpt-6-astra");
 		let runner = studioRunners.get(value.sessionId);
 		if (!runner) {
 			runner = createAgentRunner({ models: await ensureWorkflowModels(), fauxProvider, sessionStore, clock, codexBaseUrl, cliproxyBaseUrl, auth, env });
@@ -565,10 +689,10 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		}
 		try {
 			if (!session.modelSession) session.modelSession = await runner.openSession(value.sessionId, { surface: "studio" });
-			for await (const frame of session.modelSession.start({
-				surface: "studio", sessionId: value.sessionId, model: value.model || (fauxProvider ? `${fauxProvider.provider?.id || fauxProvider.provider || "faux"}/scripted` : "gpt-6-astra"), effort: value.effort,
+			for await (const frame of turnTransaction.run(input => session.modelSession.start(input))({
+				surface: "studio", sessionId: value.sessionId, model: modelKey, effort: value.effort,
 				text: value.text, attachments: value.attachments, contextText: encodeStudioContext(value.context), frameObservation,
-				context: value.context, tools: modelTools, signal: controller.signal, emit: send,
+				context: value.context, tools: [...modelTools, scriptTool], systemPrompt: value.context.scene?.previsMode === "storyboard" ? STUDIO_SYSTEM_PROMPT_STORYBOARD : undefined, signal: controller.signal, emit: send,
 				meta: persistenceMeta,
 				quotaEvent: headers => codex?.parseQuotaHeaders ? quotaEvent(codex, headers) : { type: "quota", plan: null, primary: { usedPercent: null, windowMinutes: null, resetAt: null }, credits: { has: null } },
 			})) emitFrame(frame);
@@ -581,7 +705,25 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		}
 		if (controller.signal.aborted) { turnOutcome = "cancelled"; turnFailureCode = "aborted"; }
 		if (!record.terminal) emitFrame({ type: "done" });
-		close(); if (!res.writableEnded) res.end(); session.controller = null; return true;
+		close(); if (!res.writableEnded) res.end(); session.controller = null; session.activeTurnId = null;
+		// The review starts only now, after the stream has ended, and only ever
+		// appends one note to the record: it neither delays nor steers the turn.
+		if (record.supervisor === "pending") void (async () => {
+			const startedAt = Date.now();
+			let frame;
+			try {
+				frame = await runSupervisor({ registry: await ensureWorkflowModels(), modelKey, effort: process.env.COZYCLAY_SUPERVISOR_EFFORT || "high", turnId: value.turnId, request: value.text, frames: turnFrames, reply: lastReply,
+					hub, workspaceHandle: value.context.host.workspaceHandle, admission, baseline: value.context, actions: current?.actionIndex ?? [] });
+			} catch (error) {
+				frame = { type: "supervisor", turnId: value.turnId, verdict: "unavailable", model: modelKey, effort: null, elapsedMs: Date.now() - startedAt, summary: "", items: [], issues: [], fixes: [], droppedFixes: [], counts: { blocker: 0, concern: 0, note: 0, fixes: 0 }, reason: "The supervisor could not start." };
+			}
+			// COZYCLAY_SUPERVISOR_AUTOFIX=blocker (#743) only marks a note whose
+			// blockers carry fixes; turns stay the panel's to start, never the sidecar's.
+			if (process.env.COZYCLAY_SUPERVISOR_AUTOFIX === "blocker" && frame.fixes?.some(fix => fix.severity === "blocker")) frame = { ...frame, autofix: { eligible: true, severity: "blocker" } };
+			record.supervisor = "done";
+			emitStudioEvent(value.turnId, frame);
+		})();
+		return true;
 	};
 	const handle = async (req, res, path = new URL(req.url, "http://127.0.0.1").pathname) => {
 		if (!path.startsWith("/agent/")) return false;
@@ -595,7 +737,34 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			if (!record || !session || parseCookies(req).studio_owner !== session.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio event stream is not owned by this session." } }); return true; }
 			const after = Number(new URL(req.url, "http://127.0.0.1").searchParams.get("after") || 0);
 			if (!Number.isSafeInteger(after) || after < 0) { json(res, 400, { error: "invalid cursor" }); return true; }
-			writeStudioStream(res, record, after, req); return true;
+			writeStudioStream(res, record, after); return true;
+		}
+		// The supervisor note for one Studio turn (#728): 200 with the note once it
+		// exists, held up to SUPERVISOR_WAIT_MS while it is pending, 204 when the
+		// turn was never reviewed or the wait ran out.
+		if (path.startsWith("/agent/turn/") && path.endsWith("/supervisor") && req.method === "GET") {
+			if (!await hasAnyCredential()) { json(res, 401, { error: { code: "AUTH_REQUIRED", message: "Sign in or configure a provider key." } }); return true; }
+			const turnId = decodeURIComponent(path.slice("/agent/turn/".length, -"/supervisor".length));
+			const session = [...studioSessions.values()].find(candidate => candidate.turns.has(turnId)); const record = studioEvents.get(turnId);
+			if (!record || !session) { json(res, 404, { error: "turn not found" }); return true; }
+			if (parseCookies(req).studio_owner !== session.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio supervisor note is not owned by this session." } }); return true; }
+			const noContent = () => { res.writeHead(204, { "cache-control": "no-store" }); res.end(); };
+			const existing = record.events.findLast(event => event.type === "supervisor");
+			if (existing) { json(res, 200, existing); return true; }
+			if (record.supervisor !== "pending") { noContent(); return true; }
+			await new Promise(resolve => {
+				let timer;
+				const settle = note => {
+					clearTimeout(timer); record.listeners.delete(listener); res.off("close", onClose);
+					if (note !== undefined && !res.writableEnded && !res.destroyed) { if (note) json(res, 200, note); else noContent(); }
+					resolve();
+				};
+				const listener = event => { if (event.type === "supervisor") settle(event); };
+				const onClose = () => settle(undefined);
+				record.listeners.add(listener); res.once("close", onClose);
+				timer = setTimeout(() => settle(null), SUPERVISOR_WAIT_MS);
+			});
+			return true;
 		}
 		if (path.startsWith("/agent/turn/") && path.endsWith("/steer") && req.method === "POST") {
 			const turnId = decodeURIComponent(path.slice("/agent/turn/".length, -"/steer".length));
@@ -604,12 +773,15 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				value = await readBody(req, TURN_BODY_LIMIT);
 				if (!value || typeof value.text !== "string" || !value.text.trim() || !validAttachments(value.attachments)) throw new Error("Invalid request.");
 			} catch { json(res, 400, { error: "invalid request" }); return true; }
-			// Studio turnIds are frozen envelopes; their events are keyed in studioSessions,
-			// never in the Workflow `sessions` map, so that lookup alone tells them apart.
-			if ([...studioSessions.values()].some(candidate => candidate.turns.has(turnId))) { json(res, 409, { error: { code: "STEER_UNSUPPORTED", message: "Steering a Studio turn is not supported." } }); return true; }
-			const session = [...sessions.values()].find(candidate => candidate.turnId === turnId);
+			// Studio turns are keyed in studioSessions, never in the Workflow
+			// `sessions` map, so that lookup alone tells them apart. Only the cookie
+			// owner of the Studio session may steer its running turn.
+			const studio = [...studioSessions.values()].find(candidate => candidate.turns.has(turnId));
+			if (studio && parseCookies(req).studio_owner !== studio.owner) { json(res, 403, { error: { code: "AUTH_REQUIRED", message: "Studio turn is not owned by this session." } }); return true; }
+			const session = studio ?? [...sessions.values()].find(candidate => candidate.turnId === turnId);
 			if (!session) { json(res, 404, { error: "turn not found" }); return true; }
-			if (!session.running || !session.modelSession) { json(res, 409, { error: { code: "NO_ACTIVE_TURN", message: "This turn already ended." } }); return true; }
+			const active = studio ? studio.activeTurnId === turnId && studio.controller && !studio.controller.signal.aborted : session.running;
+			if (!active || !session.modelSession) { json(res, 409, { error: { code: "NO_ACTIVE_TURN", message: "This turn already ended." } }); return true; }
 			const images = (Array.isArray(value.attachments) ? value.attachments : []).map(attachment => {
 				const match = /^data:([^;]+);base64,(.*)$/.exec(attachment?.dataUrl || "");
 				return match ? { type: "image", data: match[2], mimeType: match[1] } : null;
@@ -672,7 +844,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			let value;
 			try {
 				value = await readBody(req, IMAGE_BODY_LIMIT);
-				if (typeof value.prompt !== "string" || !value.prompt.trim() || typeof value.imageDataUrl !== "string" || !value.imageDataUrl.startsWith("data:image/") || (value.referenceDataUrl !== undefined && (typeof value.referenceDataUrl !== "string" || !value.referenceDataUrl.startsWith("data:image/"))) || !validReferences(value.references) || (value.quality !== undefined && !["auto", "low", "medium", "high"].includes(value.quality))) throw new Error("Invalid request.");
+				if (typeof value.prompt !== "string" || !value.prompt.trim() || typeof value.imageDataUrl !== "string" || !value.imageDataUrl.startsWith("data:image/") || (value.referenceDataUrl !== undefined && (typeof value.referenceDataUrl !== "string" || !value.referenceDataUrl.startsWith("data:image/"))) || !validReferences(value.references) || (value.composition !== undefined && !["frame", "sheet"].includes(value.composition)) || (value.quality !== undefined && !["auto", "low", "medium", "high"].includes(value.quality)) || (value.size !== undefined && !IMAGE_SIZES.includes(value.size))) throw new Error("Invalid request.");
 			} catch { json(res, 400, { error: "invalid request" }); return true; }
 			if (!await auth.getAccessToken()) { json(res, 401, { error: { code: "auth", message: "Sign in with ChatGPT in the Agent panel." } }); return true; }
 			try {
@@ -681,8 +853,17 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				// Scene references (#167) are appended after the frame/reference pair,
 				// and the prompt says what each attachment is for.
 				const references = Array.isArray(value.references) ? value.references : [];
-				const prompt = `${value.prompt}${await renderGuidance(value.prompt)}${referenceGuidance(references)}`;
-				const result = await codex.editImage({ ...value, prompt, extraImages: references.map((entry) => entry.dataUrl) });
+				// composition "frame": the attached frame was framed by hand (Pose mode), so the shot
+				// camera's description would contradict it; the frame alone owns camera and pose.
+				// composition "sheet" (Sculpt blueprint): a model sheet, not a shot, so no scene or
+				// camera guidance is added; the prompt is sent as written.
+				const prompt = value.composition === "sheet"
+					? value.prompt
+					: value.composition === "frame"
+						? `${FRAME_COMPOSITION_GUIDANCE}\n${value.prompt}${referenceGuidance(references)}`
+						: `${value.prompt}${await renderGuidance(value.prompt)}${referenceGuidance(references)}`;
+				const { composition: _composition, ...request } = value;
+				const result = await codex.editImage({ ...request, prompt, extraImages: references.map((entry) => entry.dataUrl) });
 				json(res, 200, { dataUrl: `data:image/png;base64,${result.pngBase64}`, width: result.width, height: result.height });
 			} catch (error) { json(res, error.status === 401 ? 401 : 502, { error: errorInfo(error) }); }
 			return true;

package/bin/agent/agent-runner.mjs

@@ -40,7 +40,7 @@ export function classifyProviderError(message) {
 	return "upstream";
 }
 
-export function extractStatus(message) {
+function extractStatus(message) {
 	const match = /\b(401|403|429|5\d\d)\b/.exec(message);
 	return match ? Number(match[1]) : undefined;
 }
@@ -145,11 +145,90 @@ function studioUserMessage(input) {
 	};
 }
 
+const STUDIO_CONTEXT_PREFIX = "<studio-context>";
+const STUDIO_CONTEXT_BLOCK = /^<studio-context>\n([\s\S]*?)\n<\/studio-context>/;
+const STUDIO_CONTEXT_SUPERSEDED = "<studio-context superseded/>";
+const escapeStudioJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll(">", "\\u003e").replaceAll("&", "\\u0026");
+const isStudioContextPart = (part) => part?.type === "text" && typeof part.text === "string" && part.text.startsWith(STUDIO_CONTEXT_PREFIX);
+
+function withoutInspectContext(part) {
+	if (part?.type !== "text" || typeof part.text !== "string") return part;
+	let parsed;
+	try { parsed = JSON.parse(part.text); } catch { return part; }
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Object.hasOwn(parsed, "context")) return part;
+	const { context: _context, ...rest } = parsed;
+	return { ...part, text: JSON.stringify(rest) };
+}
+
+/** The Studio per-request context diet (#716), applied to the provider view
+ * only (pi's transform_context): every <studio-context> but the latest is
+ * replaced by a superseded marker, every inspect_studio result but the most
+ * recent tool result drops its re-embedded `context`, and the latest
+ * context's static actionIndex moves to the end of the system prompt. The
+ * stored lane messages are never touched; edited messages are new objects. */
+function studioContextDiet({ messages, systemPrompt }) {
+	let latestContext = -1;
+	let latestToolResult = -1;
+	messages.forEach((message, index) => {
+		if (message?.role === "user" && Array.isArray(message.content) && message.content.some(isStudioContextPart)) latestContext = index;
+		if (message?.role === "toolResult") latestToolResult = index;
+	});
+	let actionIndex;
+	const edited = messages.map((message, index) => {
+		if (message?.role === "toolResult" && message.toolName === "inspect_studio" && index !== latestToolResult && Array.isArray(message.content)) {
+			const content = message.content.map(withoutInspectContext);
+			return content.some((part, i) => part !== message.content[i]) ? { ...message, content } : message;
+		}
+		if (message?.role !== "user" || !Array.isArray(message.content) || !message.content.some(isStudioContextPart)) return message;
+		const content = message.content.map((part) => {
+			if (!isStudioContextPart(part)) return part;
+			const block = STUDIO_CONTEXT_BLOCK.exec(part.text);
+			if (index !== latestContext) return { ...part, text: block ? STUDIO_CONTEXT_SUPERSEDED + part.text.slice(block[0].length) : STUDIO_CONTEXT_SUPERSEDED };
+			if (!block) return part;
+			let context;
+			try { context = JSON.parse(block[1]); } catch { return part; }
+			if (!context || typeof context !== "object" || !Array.isArray(context.actionIndex)) return part;
+			({ actionIndex } = context);
+			const { actionIndex: _actionIndex, ...rest } = context;
+			return { ...part, text: `${STUDIO_CONTEXT_PREFIX}\n${escapeStudioJson(rest)}\n</studio-context>${part.text.slice(block[0].length)}` };
+		});
+		return { ...message, content };
+	});
+	return {
+		messages: edited,
+		systemPrompt: actionIndex ? `${systemPrompt}\n<actions>\n${JSON.stringify(actionIndex)}\n</actions>` : systemPrompt,
+	};
+}
+
+/** Anthropic prompt-cache breakpoints on the stable prefix (#716): pi-ai's
+ * anthropic-messages builder already marks the system blocks, the last tool
+ * and the last user block by default; this only fills a missing mark on the
+ * last system block and the last tool, never past the API's 4 breakpoints,
+ * and never on tools for a model whose compat declares them unsupported. */
+export function withAnthropicCacheBreakpoints(payload, model) {
+	if (!payload || typeof payload !== "object") return undefined;
+	const marked = (block) => Boolean(block?.cache_control);
+	const system = Array.isArray(payload.system) ? payload.system : [];
+	const tools = Array.isArray(payload.tools) ? payload.tools : [];
+	const messageBlocks = (Array.isArray(payload.messages) ? payload.messages : []).flatMap((message) => Array.isArray(message?.content) ? message.content : []);
+	let count = [...system, ...tools, ...messageBlocks].filter(marked).length;
+	const cacheControl = { type: "ephemeral" };
+	let next = payload;
+	if (system.length && !marked(system.at(-1)) && count < 4) {
+		next = { ...next, system: [...system.slice(0, -1), { ...system.at(-1), cache_control: cacheControl }] };
+		count += 1;
+	}
+	if (tools.length && !marked(tools.at(-1)) && model?.compat?.supportsCacheControlOnTools !== false && count < 4) {
+		next = { ...next, tools: [...tools.slice(0, -1), { ...tools.at(-1), cache_control: cacheControl }] };
+	}
+	return next === payload ? undefined : next;
+}
+
 function studioObservationMessage(observation) {
 	return {
 		role: "user",
 		content: [
-			{ type: "text", text: `Studio frame observation revision ${JSON.stringify(observation?.revision ?? null)} receipt ${observation?.receiptId ?? "unavailable"}` },
+			{ type: "text", text: `Studio ${observation?.kind === "plan" ? "plan observation (top view)" : "frame observation"} revision ${JSON.stringify(observation?.revision ?? null)} receipt ${observation?.receiptId ?? "unavailable"}` },
 			{ type: "image", data: observation.data, mimeType: observation.mimeType },
 		],
 	};
@@ -311,6 +390,18 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 					streamOptions: { maxRetryDelayMs: RETRY_MAX_DELAY_MS, ...(codexBaseUrl ? { transport: "sse" } : {}) },
 				}, state.context)).harness;
 				state.harness.hooks.on("after_response", (response) => emitQuota(state.active?.queue, state.lastInput, response));
+				state.harness.hooks.on("after_response", ({ message }) => {
+					const usage = state.active?.usage;
+					if (!usage) return;
+					usage.requests += 1;
+					for (const key of ["input", "output", "cacheRead", "cacheWrite"]) if (Number.isFinite(message?.usage?.[key])) usage[key] += message.usage[key];
+				});
+				state.harness.hooks.on("transform_context", (event) => state.lastInput?.surface === "studio" ? studioContextDiet(event) : undefined);
+				state.harness.hooks.on("before_payload", ({ model, payload }) => {
+					if (model?.api !== "anthropic-messages") return undefined;
+					const next = withAnthropicCacheBreakpoints(payload, model);
+					return next ? { payload: next } : undefined;
+				});
 				state.harness.hooks.on("after_response", async ({ message }) => {
 					if (message.stopReason !== "error" || state.provider !== "openai-codex" || state.active.authRetried
 						|| classifyError({ message: message.errorMessage }).code !== "unauthorized") return;
@@ -327,6 +418,9 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 					for (const message of restored.history) await state.lane.appendMessage(message, state.context);
 					state.persisted = restored.history.length;
 				}
+				// Studio only: older turns' full contexts are stale and large, so each request
+				// carries the newest one whole and a stub for the rest. The stored lane and
+				// the persisted history keep every context.
 				state.unsubscribers.push(state.harness.events.on("turn_end", persist));
 				state.unsubscribers.push(state.harness.events.on("run_end", persist));
 			}
@@ -405,7 +499,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 					const fallback = code === "aborted" ? "The turn was aborted." : code === "truncated" ? "The model stream ended before a terminal response event." : "The model or live editor could not complete this turn.";
 					queue.push({ type: "error", code, message: detail || fallback, ...(status ? { status } : {}) });
 				}
-				queue.push({ type: "done" });
+				queue.push({ type: "done", usage: { ...state.active.usage } });
 				queue.close();
 			});
 			return () => { for (const unsubscribe of eventUnsubscribers) unsubscribe(); };
@@ -420,7 +514,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 			const queue = new FrameQueue();
 			// Studio never sends a quota frame at all (unchanged, #379): mark it sent
 			// up front so `pushFrame`'s gate never holds Studio's first frame.
-			state.active = { queue, quotaSent: input.surface === "studio", pendingFrames: [], authRetried: false, abortRequested: false, lastResponseHeaders: null };
+			state.active = { queue, quotaSent: input.surface === "studio", pendingFrames: [], authRetried: false, abortRequested: false, lastResponseHeaders: null, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, requests: 0 } };
 			state.lastInput = input;
 			const controller = input.signal ? null : new AbortController();
 			const signal = input.signal || controller.signal;