cozyclay 1.10.0 → 2.0.2

package/mcp/tool-handlers.mjs

@@ -28,10 +28,10 @@ import { createHash, randomUUID } from "node:crypto";
 
 import { z } from "zod";
 
-import { LiveMutationUncertainError } from "./live-hub.mjs";
+import { MAX_COMMAND_TIMEOUT_MS } from "./live-hub.mjs";
 import { readMeshFromPath } from "./mesh-file.mjs";
-import { readMotionStream } from "../bin/agent/motion-runtime.mjs";
-import { motionPreflightReason, startMotionRequest } from "../src/analytics.js";
+import { DEFAULT_POSE } from "../src/poses.js";
+import { generationArgs } from '../src/motion/generation.js';
 import { BLOCK_MAX_SECONDS, PROMPT_GUIDE, normalizePhases, splitLongBeat, tileClipFrames } from "./ardy-prompts.mjs";
 
 import {
@@ -99,6 +99,7 @@ const liveWorkspaceTools = new Set([
 	"set_camera", "frame_shot", "add_character", "place_character", "remove_character",
 	"focus_character", "place_object", "import_mesh", "group_objects", "set_prompt_blocks", "generate_motion", "update_object",
 	"remove_object", "apply_batch", "add_scene", "switch_scene", "open_project", "capture_frame", "load_motion",
+	"studio_commands", "studio_run",
 ]);
 const MAX_CAPTURE_BYTES = 1_000_000;
 const CAPTURE_ARTIFACT_TTL_MS = 10 * 60_000;
@@ -166,8 +167,41 @@ const TOOL_ANNOTATIONS = Object.freeze({
 	switch_scene: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
 	open_project: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
 	save_project: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+	studio_commands: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	// Whatever the editor registers: some commands delete, export or spend a
+	// paid generation, and those answer CONFIRMATION_REQUIRED instead of running.
+	studio_run: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 });
 
+/** The document identity a Studio command is admitted in. */
+const STUDIO_IDENTITY_KEYS = ["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"];
+
+/** One registered editor command through the editor's own bus, admitted at
+ * the open document and its current revision like the agent's run_action. Its
+ * declaration (read from the editor, never from this server) sets the hub
+ * deadline unless the caller gives one. */
+const executeStudioCommand = async ({ action, args, expectedRevision, commandId, timeoutMs, confirmationToken, inspected }) => {
+	const workspaceHandle = liveWorkspace.getStore();
+	inspected ??= await liveHub.command("inspect_studio", { scope: "actions", ids: [action] }, workspaceHandle);
+	const context = inspected?.context;
+	if (!context?.host || !Number.isSafeInteger(context.revision?.scene)) throw new Error("The editor did not return a Studio context to admit this command against.");
+	const declared = inspected.actions?.find((row) => row.id === action);
+	const receipt = await liveHub.command("run_action", {
+		name: "run_action",
+		args: { action, args: typeof args === "function" ? await args(context) : args ?? {}, ...(confirmationToken ? { confirmationToken } : {}) },
+		commandId: commandId ?? randomUUID(),
+		host: Object.fromEntries(STUDIO_IDENTITY_KEYS.map((key) => [key, context.host[key]])),
+		expectedRevision: expectedRevision ?? context.revision.scene,
+	}, workspaceHandle, { timeoutMs: timeoutMs ?? (declared?.timeoutMs === undefined ? undefined : Math.min(MAX_COMMAND_TIMEOUT_MS, declared.timeoutMs + (declared.generation ? 5000 : 0))) });
+	return receipt;
+};
+// A refusal is the editor's receipt: its code and recovery are the answer.
+const studioResult = (...receipts) => ({
+	content: receipts.map(receipt => ({ type: "text", text: JSON.stringify(receipt) })),
+	...(receipts.some(receipt => receipt.ok === false) ? { isError: true } : {}),
+});
+const runStudioCommand = async options => studioResult(await executeStudioCommand(options));
+
 const scene = () => activeScene(state.doc.scenes, state.doc.activeSceneId);
 const stage = () => scene().stage;
 
@@ -189,6 +223,13 @@ const findCharacter = (ref) => {
 	return null;
 };
 
+// Resolve legacy letters and slots from the complete live cast inside the
+// inspected admission. A missing id is refused by the command, not hidden here.
+const liveCharacterId = async ref => {
+	await refreshLiveDescription();
+	return findCharacter(ref)?.id ?? ref;
+};
+
 /** The studio labels the cast A, B, C… by position. */
 const letterFor = (character) => String.fromCharCode(65 + cast().indexOf(character));
 
@@ -245,31 +286,6 @@ const framing = () => {
 
 const currentShot = () => deriveShot(state.camera, subject(), fov(), undefined, filmback());
 
-const appliedLiveMutation = async (name, args) => {
-	const workspaceHandle = liveWorkspace.getStore();
-	const value = await liveHub.command(name, args, workspaceHandle);
-	try {
-		if (!await refreshLiveDescription(workspaceHandle)) throw new Error("Live editor disconnected before verification.");
-	} catch (error) {
-		throw new LiveMutationUncertainError(`Live editor accepted ${name}, but its state could not be verified: ${error.message} The mutation may have been applied. Do not retry it; describe the scene before choosing a recovery action.`);
-	}
-	return value;
-};
-
-const requireLiveSceneParity = (name, document, result) => {
-	const expected = document.scenes.map(({ id, name: sceneName }) => ({ id, name: sceneName }));
-	const received = Array.isArray(result?.scenes) ? result.scenes : [];
-	const sameScenes = received.length === expected.length && received.every((scene, index) =>
-		scene?.id === expected[index].id && scene?.name === expected[index].name,
-	);
-	if (sameScenes && result?.activeSceneId === document.activeSceneId) return;
-	throw new LiveMutationUncertainError(
-		`Live editor accepted ${name}, but did not confirm the complete scene list and active scene ` +
-		`(expected ${JSON.stringify(expected)} active ${document.activeSceneId}; received ${JSON.stringify(received)} active ${result?.activeSceneId ?? "none"}). ` +
-		"The mutation may have been applied. Do not retry it; describe the scene before choosing a recovery action.",
-	);
-};
-
 const modelById = (id) =>
 	[...VIDEO_MODELS, ...IMAGE_MODELS].find((m) => m.id === id) ?? null;
 
@@ -470,13 +486,24 @@ function shotReport() {
 
 /* --------------------------------- tools --------------------------------- */
 
+const studioAliasTools = new Set([
+	"set_camera", "frame_shot", "place_object", "update_object", "remove_object",
+	"import_mesh", "group_objects", "add_scene", "switch_scene", "apply_batch", "open_project",
+	"add_character", "place_character", "remove_character", "set_prompt_blocks", "load_motion", "generate_motion",
+]);
+const studioAdmissionSchema = {
+	expectedRevision: z.number().int().min(0).optional().describe("scene revision to admit against; defaults to the inspected revision"),
+	commandId: z.string().min(1).max(120).optional().describe("idempotency key; reuse with the original expectedRevision to replay its receipt"),
+	timeoutMs: z.number().int().min(1).max(MAX_COMMAND_TIMEOUT_MS).optional().describe("hub deadline; defaults to the editor command declaration"),
+};
+
 /** One tool, as the registry hands it out: everything server.mjs needs to
  * register it, and everything a direct caller needs to run it. */
 const tool = (name, config, handler) => ({
 	name,
 	title: config.title,
 	description: config.description,
-	inputSchema: config.inputSchema,
+	inputSchema: studioAliasTools.has(name) ? { ...config.inputSchema, ...studioAdmissionSchema } : config.inputSchema,
 	annotations: TOOL_ANNOTATIONS[name],
 	live: liveWorkspaceTools.has(name),
 	handler,
@@ -489,14 +516,9 @@ const tool = (name, config, handler) => ({
  * @param {Promise<string>} [deps.projectRootPromise] the resolved directory
  *   `open_project`/`save_project` confine themselves to; the owner resolves it
  *   because doing so chdirs the process.
- * @param {object} [deps.motionJobs] the MotionJobRegistry `generate_motion`
- *   records work in.
- * @param {(job: object) => Promise<void>} [deps.publishMotionJob] delivers a
- *   finished job to its workspace; the owner holds it because the live hub's
- *   reconnect and cancel paths publish jobs too.
  * @returns {Array<{name: string, title: string, description: string, inputSchema: object, annotations: object, live: boolean, handler: Function}>}
  */
-export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMotionJob } = {}) => {
+export const createToolHandlers = ({ projectRootPromise } = {}) => {
 	const resolveProjectPath = async (path, { existing }) => {
 		if (!path.endsWith(".cclayproject")) throw new Error("Project path must end in .cclayproject.");
 		const root = await projectRootPromise;
@@ -675,17 +697,19 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					look_at_z: z.number().optional().describe("world z of an explicit aim point; give all three to aim the lens"),
 				},
 			},
-			async ({ x, y, z: zPos, focal_mm, look_at_x, look_at_y, look_at_z }) => {
+			async ({ x, y, z: zPos, focal_mm, look_at_x, look_at_y, look_at_z, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						// The aim is only forwarded when the caller gave a whole point: a
-						// partial target has no direction, and an omitted one deliberately
-						// leaves the live editor's orientation exactly where it was.
-						const aim = [look_at_x, look_at_y, look_at_z].every((value) => value !== undefined)
-							? { lookAtX: look_at_x, lookAtY: look_at_y, lookAtZ: look_at_z }
-							: {};
-						await appliedLiveMutation("set_camera", { x, y, z: zPos, focalMm: focal_mm, ...aim });
-						return text(`Camera set.\n\n${shotReport()}`);
+						return await runStudioCommand({ ...admission, action: "shot.frame", args: context => {
+							const camera = context.camera;
+							const position = { x: x ?? camera.position.x, y: y ?? camera.position.y, z: zPos ?? camera.position.z };
+							// Preserve direction when no complete explicit aim point was given.
+							const lookAt = [look_at_x, look_at_y, look_at_z].every(value => value !== undefined)
+								? { x: look_at_x, y: look_at_y, z: look_at_z }
+								: Object.fromEntries(["x", "y", "z"].map(axis => [axis, position[axis] + camera.lookAt[axis] - camera.position[axis]]));
+							return { subjectIds: [state.focusLocked ? state.focus : context.activeCharacterId],
+								framing: { exact: { position, lookAt, focalMm: focal_mm ?? camera.focalMm } } };
+						} });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -730,9 +754,11 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					focal_mm: z.number().min(8).max(300).default(35).describe("lens to frame with"),
 				},
 			},
-			async ({ size, view, level, side, focal_mm }) => {
+			async ({ size, view, level, side, focal_mm, ...admission }) => {
+				let inspected;
 				if (liveHub?.connected) {
 					try {
+						inspected = await liveHub.command("inspect_studio", { scope: "actions", ids: ["shot.frame"] }, liveWorkspace.getStore());
 						await refreshLiveDescription();
 					} catch (error) {
 						return liveError(error);
@@ -805,19 +831,13 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				};
 				if (liveHub?.connected) {
 					try {
-						// Placing the lens is only half the shot. deriveShot and captureFraming
-						// both measure as if the lens points at the framing pivot (see
-						// aimAtSubject), which the in-memory path gets for free because it has
-						// no orientation at all. A live editor has one and keeps it, so a
-						// position-only move orbited every view except `front` off the subject
-						// while the slate still read "98% of frame height". Send the same pivot
-						// the vocabulary is measured against, with the position.
-						await appliedLiveMutation("set_camera", {
-							...nextCamera,
-							lookAtX: s.x,
-							lookAtY: FRAMING_PIVOT_Y,
-							lookAtZ: s.z,
-						});
+						return await runStudioCommand({ ...admission, action: "shot.frame", inspected, args: {
+							subjectIds: [(findCharacter(state.focus) ?? cast()[0]).id],
+							framing: { exact: {
+								position: { x: nextCamera.x, y: nextCamera.y, z: nextCamera.z },
+								lookAt: { x: s.x, y: FRAMING_PIVOT_Y, z: s.z }, focalMm: lensMm,
+							} },
+						} });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -852,13 +872,12 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 						.describe("which mannequin to use"),
 				},
 			},
-			async ({ subject: desc, x, z: zPos, facing, model }) => {
+			async ({ subject: desc, x, z: zPos, facing, model, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						const result = await appliedLiveMutation("add_character", { subject: desc, x, z: zPos, rot: facing, model });
-						const added = stage().characters.find((character) => character.id === result?.id);
-						if (added && model !== undefined) added.model = model;
-						return text(`Added ${result?.id ?? "character"}.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "character.add", args: {
+							character: { subject: desc, x, z: zPos, rot: facing, model, pose: DEFAULT_POSE },
+						} });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -901,11 +920,12 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					hidden: z.boolean().optional().describe("hide without removing from the cast"),
 				},
 			},
-			async ({ character, x, z: zPos, y, facing, subject: desc, hidden }) => {
+			async ({ character, x, z: zPos, y, facing, subject: desc, hidden, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						await appliedLiveMutation("update_character", { ref: character, x, y, z: zPos, rot: facing, subject: desc, hidden });
-						return text(`Character updated.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "character.update", args: async () => ({
+							characterId: await liveCharacterId(character), patch: { x, y, z: zPos, rot: facing, subject: desc, hidden },
+						}) });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -931,11 +951,12 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					character: z.string().describe('which character — letter, slot number or id'),
 				},
 			},
-			async ({ character }) => {
+			async ({ character, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						await appliedLiveMutation("remove_character", { ref: character });
-						return text(`Character removed.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "character.remove", args: async () => ({
+							characterId: await liveCharacterId(character),
+						}) });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1001,11 +1022,10 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 						.describe("object id to attach to — the parent then carries this object when it moves"),
 				},
 			},
-			async ({ kind, x, z: zPos, y, facing, name, parent }) => {
+			async ({ kind, x, z: zPos, y, facing, name, parent, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						const result = await appliedLiveMutation("place_object", { kind, x, z: zPos, y, rot: facing, name, parent });
-						return text(`Placed object as ${result?.id ?? "unknown"}.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "object.add", args: { kind, placement: { x, z: zPos, y, rot: facing }, name, parent } });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1053,7 +1073,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					height: z.number().positive().optional().describe("standing height in metres; omitted uses the fitted size"),
 				},
 			},
-			async ({ path, clay, name, x, z: zPos, y, facing, height }) => {
+			async ({ path, clay, name, x, z: zPos, y, facing, height, ...admission }) => {
 				if (!liveHub?.connected) {
 					return liveError(new Error(noLiveEditor("import_mesh requires a connected CozyClay editor.")));
 				}
@@ -1066,7 +1086,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				const liveArgs = {
 					name: typeof name === "string" && name.trim() ? name.trim() : mesh.name,
 					mimeType: mesh.mimeType,
-					dataUrl: `data:${mesh.mimeType};base64,${Buffer.from(mesh.bytes).toString("base64")}`,
+					source: `data:${mesh.mimeType};base64,${Buffer.from(mesh.bytes).toString("base64")}`,
 					placeAs: "mesh",
 				};
 				if (clay === true) liveArgs.clay = true;
@@ -1078,10 +1098,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				if (facing !== undefined) liveArgs.rot = facing;
 				if (height !== undefined) liveArgs.height = height;
 				try {
-					const result = await appliedLiveMutation("import_asset", liveArgs);
-					return text(
-						`Placed ${liveArgs.name} as ${result?.objectId ?? "unknown"} (${result?.assetId ?? "unknown"}).\n\n${sceneReport()}`,
-					);
+					return await runStudioCommand({ ...admission, action: "asset.import", args: liveArgs });
 				} catch (error) {
 					return liveError(error);
 				}
@@ -1102,16 +1119,10 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					children: z.array(z.string()).min(1).describe("object ids to attach or detach"),
 				},
 			},
-			async ({ parent, children }) => {
+			async ({ parent, children, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						await appliedLiveMutation(parent === null ? "ungroup_objects" : "group_objects", { parent, children });
-						return text(
-							(parent === null
-								? `Detached ${children.length} object(s).`
-								: `Grouped ${children.length} object(s) under ${parent} — move ${parent} and they follow.`) +
-								`\n\n${sceneReport()}`,
-						);
+						return await runStudioCommand({ ...admission, action: parent === null ? "object.ungroup" : "object.group", args: parent === null ? { children } : { parent, children } });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1136,7 +1147,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				description:
 					"Write Prompt Blocks onto the timeline WITHOUT generating — the beats and their frame " +
 					"ranges, so a schedule can be read and revised before any GPU time is spent. Hit " +
-					"'Generate all N blocks' in the studio, or call generate_motion, when it reads right.\n\n" +
+					"the studio's top-bar Generate Motion button, or call generate_motion, when it reads right.\n\n" +
 					PROMPT_GUIDE,
 				inputSchema: {
 					beats: z
@@ -1156,7 +1167,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 						.describe("beats in order; each one becomes a contiguous block"),
 				},
 			},
-			async ({ beats }) => {
+			async ({ beats, ...admission }) => {
 				if (!liveHub?.connected) {
 					return text("Prompt Blocks live on the studio timeline — open the editor and try again.");
 				}
@@ -1164,12 +1175,10 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				// The timeline runs on a 24 fps production clock.
 				const TIMELINE_FPS = 24;
 				let cursor = 0;
-				let chained = 0;
 				const blocks = [];
 				for (const [i, textValue] of normalized.texts.entries()) {
 					const whole = beats[Math.min(normalized.sources[i], beats.length - 1)].seconds ?? 3;
 					const spans = splitLongBeat(whole);
-					if (spans.length > 1) chained += spans.length - 1;
 					for (const span of spans) {
 						const frames = Math.max(1, Math.round(span * TIMELINE_FPS));
 						blocks.push({ startFrame: cursor, endFrame: cursor + frames, text: textValue });
@@ -1177,24 +1186,12 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					}
 				}
 				try {
-					await appliedLiveMutation("set_prompt_blocks", { blocks });
+					return await runStudioCommand({ ...admission, action: "character.setPromptBlocks", args: context => ({
+						characterId: context.activeCharacterId, blocks,
+					}) });
 				} catch (error) {
 					return liveError(error);
 				}
-				// Report the normalised text itself, not blocks[i]: a long beat becomes
-				// several blocks, so block indices run ahead of phase indices and quoting
-				// blocks[i] would attribute one beat's edits to another beat's wording.
-				const rewrites = normalized.notes
-					.map((notes, i) => (notes.length ? `  ${i + 1}. ${normalized.texts[i]}  ← ${notes.join("; ")}` : null))
-					.filter(Boolean);
-				return text(
-					`${blocks.length} block(s) on the timeline (${(cursor / TIMELINE_FPS).toFixed(1)}s total):\n` +
-						blocks.map((b) => `  ${b.startFrame}-${b.endFrame}f  ${b.text}`).join("\n") +
-						(chained > 0 ? `\n  (${chained} block(s) chained to keep every block within ${BLOCK_MAX_SECONDS}s)` : "") +
-						(rewrites.length ? `\n\nRewritten for ARDY:\n${rewrites.join("\n")}` : "") +
-						(normalized.dropped > 0 ? `\n  (${normalized.dropped} beat(s) past the 8-phase limit were dropped)` : "") +
-						"\n\nGenerate them from the studio's Prompt Blocks panel, or with generate_motion.",
-				);
 			},
 		),
 
@@ -1216,23 +1213,10 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				if (!motionUrlPattern.test(args.url)) {
 					throw new Error(`Unsupported motion url "${args.url}". Use /ardy/motions/<id> or /ardy/assembled/<name>.npz.`);
 				}
-				const workspaceHandle = liveWorkspace.getStore() ?? liveHub.resolveWorkspace("load_motion", args.workspace_handle);
-				// Without an explicit target the editor installs onto ITS active character,
-				// which silently stacks multi-cast loads onto one rig — the generate path
-				// always names its target, so the load path must be able to as well.
-				let characterId;
-				if (args.character !== undefined) {
-					try {
-						await refreshLiveDescription();
-					} catch (error) {
-						return liveError(error);
-					}
-					const target = findCharacter(args.character);
-					if (!target) return text(`No character "${args.character}". ${castHint()}`);
-					characterId = target.id;
-				}
-				await liveHub.command("load_motion", { url: args.url, prompt: args.prompt ?? "", ...(characterId ? { characterId } : {}) }, workspaceHandle);
-				return text(`Motion installed from ${args.url}${characterId ? ` onto ${characterId}` : ""}.`);
+				return runStudioCommand({ ...args, action: 'motion.replace', args: async context => ({
+					characterId: args.character === undefined ? context.activeCharacterId : await liveCharacterId(args.character),
+					url: args.url, prompt: args.prompt ?? '',
+				}) });
 			},
 		),
 
@@ -1241,9 +1225,8 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 			{
 				title: "Generate character motion (Kimodo)",
 				description:
-					"Start a multi-phase Kimodo motion job for the connected live editor and return immediately with its " +
-					"task-shaped identity. Completion, failure, or cancellation arrives as the live socket's motion_job event; " +
-					"the MCP model does not poll task state. A completed event loads the active character's timeline.\n\n" +
+					"Alias for motion.generate in the editor. Returns its bus receipt; started jobs carry jobId for studio_run job.await or job.cancel. " +
+					"The installed take is undoable with studio_run edit.undo.\n\n" +
 					PROMPT_GUIDE,
 				inputSchema: {
 					phases: z
@@ -1290,203 +1273,16 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 						),
 				},
 			},
-			async ({ phases: rawPhases, seconds, seed, motion_url, drop }) => {
-				const phases = rawPhases.map((p) => (typeof p === "string" ? p : p.text));
-				const phaseSeconds = rawPhases.map((p) => (typeof p === "string" ? null : p.seconds));
-				const timed = phaseSeconds.some((s) => s !== null);
-				const bridge = (process.env.COZYCLAY_BRIDGE_ORIGIN ?? process.env.COZYCLAY_BRIDGE ?? "http://127.0.0.1:5181").replace(/\/$/, "");
-
-				// Every phase is rewritten into ARDY's own sentence shape before it is ever
-				// sent. One input beat stays one phase: the caller's phase list is the
-				// sequence, so a composite beat is theirs to split, not ours to re-cut.
-				const normalized = normalizePhases(phases);
-				// Keep notes beside the prompt they belong to: a blank beat normalises to
-				// "" and is dropped, which would otherwise slide every later note onto the
-				// wrong prompt in the rewrite report.
-				const kept = normalized.texts
-					.map((t, i) => ({ text: t, notes: normalized.notes[i], source: normalized.sources[i] }))
-					.filter((p) => p.text);
-				const prompts = kept.map((p) => p.text);
-				// One complete beat is a legitimate clip — ARDY's own examples are single
-				// prompts ("A person walks in a circle."), so a valid one-phase request must
-				// not fail merely for being one phase. Only an empty request is refused.
-				if (prompts.length === 0) return text("Give at least one motion beat.");
-
-				// ARDY Core is 20 fps; segments must tile 0..clipFrames exactly, and each
-				// one needs at least 3 frames.
-				const ARDY_FPS =
-					(process.env.CCLAY_MOTION_BACKEND || "kimodo").trim().toLowerCase() === "kimodo" ? 24 : 20;
-				let segments;
-				let clipFrames;
-				let chained = 0;
-				if (timed) {
-					// A beat that became several blocks shares its time between them, so an
-					// explicit "6 seconds of walking" stays 6 seconds however it was phrased.
-					const pieceCount = kept.reduce((acc, piece) => {
-						acc[piece.source] = (acc[piece.source] ?? 0) + 1;
-						return acc;
-					}, {});
-					segments = [];
-					let cursor = 0;
-					for (const { text: prompt, source } of kept) {
-						const whole = phaseSeconds[source] ?? seconds / phases.length;
-						const share = whole / pieceCount[source];
-						// The studio caps a block at BLOCK_MAX_SECONDS and refuses to generate
-						// a longer one, so a long beat becomes consecutive blocks here rather
-						// than something the UI would reject.
-						const spans = splitLongBeat(share);
-						if (spans.length > 1) chained += spans.length - 1;
-						for (const span of spans) {
-							const startFrame = cursor;
-							cursor += Math.max(3, Math.round(span * ARDY_FPS));
-							segments.push({ startFrame, endFrame: cursor, prompt });
-						}
-					}
-					clipFrames = cursor;
-				} else {
-					clipFrames = Math.floor(seconds * ARDY_FPS);
-					// Even division must also respect the cap: enough blocks that no single
-					// one exceeds it, distributed evenly across the clip.
-					const perPhase = seconds / prompts.length;
-					const piecesPer = Math.ceil(perPhase / BLOCK_MAX_SECONDS);
-					if (piecesPer > 1) chained = prompts.length * (piecesPer - 1);
-					const total = prompts.length * piecesPer;
-					const per = Math.floor(clipFrames / total);
-					segments = [];
-					for (const [i, prompt] of prompts.entries()) {
-						for (let k = 0; k < piecesPer; k += 1) {
-							const index = i * piecesPer + k;
-							segments.push({
-								startFrame: index * per,
-								endFrame: index === total - 1 ? clipFrames : (index + 1) * per,
-								prompt,
-							});
-						}
-					}
-				}
-				const clipSeconds = clipFrames / ARDY_FPS;
-				// A single beat has no sequence to chain: send it as a plain prompt;
-				// composite physical wording remains intact in the normalized text.
-				// Long single prompts are the exception: split the actual clip length
-				// into equal Kimodo blocks so every wire segment stays within the cap.
-				const singlePromptNeedsChain = prompts.length === 1 && clipSeconds > BLOCK_MAX_SECONDS;
-				if (prompts.length === 1) {
-					if (singlePromptNeedsChain) {
-						segments = tileClipFrames(clipFrames, clipSeconds).map((b) => ({ ...b, prompt: prompts[0] }));
-						chained = segments.length - 1;
-					} else {
-						chained = 0;
-					}
-				}
-				const rewrites = kept
-					.map(({ text: prompt, notes }, i) => (notes.length ? `  ${i + 1}. ${prompt}  ← ${notes.join("; ")}` : null))
-					.filter(Boolean);
-				const chainNote = chained > 0 ? `\n  (${chained} block(s) chained to keep every block within ${BLOCK_MAX_SECONDS}s)` : "";
-				// A drop is reported on its own account: a caller can send nine already-perfect
-				// phases, which produces no rewrite and no chaining yet still loses the ninth
-				// to the schema's 8-phase limit, and silence there would hide a lost beat.
-				const dropNote =
-					normalized.dropped > 0 ? `\n  (${normalized.dropped} beat(s) past the 8-phase limit were dropped)` : "";
-				const promptNote =
-					rewrites.length || chainNote || dropNote
-						? (rewrites.length ? `\n\nRewritten for ARDY:\n${rewrites.join("\n")}` : "\n") + dropNote + chainNote
-						: "";
-
-				if (!liveHub?.connected) return text(noLiveEditor("generate_motion requires a connected CozyClay editor so completion can be delivered over its live socket."));
-				const workspaceHandle = liveWorkspace.getStore() ?? liveHub.resolveWorkspace("generate_motion");
-				const workspaceId = liveHub.workspaceId(workspaceHandle);
-				// Reusing an existing take is installation, not generation demand. The
-				// shared lifecycle sanitizes before the targeted live transport sees it;
-				// disconnected events are omitted, never reconstructed on reconnect.
-				const motionRequest = motion_url ? null : startMotionRequest({ surface: "mcp", input_mode: "prompt" }, {
-					capture: (event, props) => liveHub?.sendEvent(workspaceId, "motion_telemetry", { event, props }),
-				});
-				try {
-					await refreshLiveDescription();
-				} catch (error) {
-					return liveError(error);
-				}
-				const targetCharacterId = stage().characters.find((character) => character.id === state.focus)?.id ?? stage().characters[0]?.id ?? null;
-				let job;
-				try {
-					job = motionJobs.create(workspaceId);
-					job.motionRequest = motionRequest;
-				} catch (error) {
-					return liveError(error);
-				}
-				const body =
-					prompts.length === 1 && !singlePromptNeedsChain
-						? { prompt: prompts[0], duration: clipSeconds, posePin: false }
-						: { prompt: prompts.join(" "), duration: clipSeconds, segments, posePin: false };
-				if (seed !== undefined) body.seed = seed;
-
-				// Abort tears down the HTTP stream. The bridge owns the child process group
-				// and kills it on disconnect, so cancellation stops generator work before a
-				// terminal cancelled event is sent; it never reaches editor installation.
-				const run = async () => {
-					if (job.status === "cancelled") return;
-					const controller = new AbortController();
-					const deadline = setTimeout(() => controller.abort(new Error("Motion generation exceeded the 5 minute deadline.")), 5 * 60_000);
-					deadline.unref?.();
-					job.cancel = () => {
-						controller.abort();
-						motionRequest?.fail(null, "aborted");
-					};
-					try {
-						let motionUrl = motion_url;
-						if (!motionUrl) {
-							let health;
-							try {
-								const response = await fetch(`${bridge}/ardy/health`, {
-									signal: AbortSignal.any([controller.signal, AbortSignal.timeout(5_000)]),
-								});
-								const payload = await response.json();
-								health = { ...payload, ok: response.ok && payload?.ok !== false };
-							} catch (error) {
-								if (controller.signal.aborted) throw error;
-								health = { ok: false };
-							}
-							if (job.status === "cancelled") return;
-							// Readiness controls execution independently of best-effort telemetry.
-							const reason = motionPreflightReason(health, { body });
-							motionRequest?.preflight(health, { body });
-							if (reason) {
-								motionJobs.transition(job, "failed", { message: `Motion generation preflight blocked: ${reason}.` });
-								await publishMotionJob(job);
-								return;
-							}
-							motionJobs.transition(job, "running");
-							motionRequest?.start();
-							const res = await fetch(`${bridge}/ardy/generate`, {
-								method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: controller.signal,
-							});
-							motionUrl = await readMotionStream(res);
-						}
-						if (job.status === "cancelled") return;
-						if (typeof motionUrl !== "string") throw new Error("Generation ended without a motion.");
-						if (!motionUrlPattern.test(motionUrl)) throw new Error("Generator returned an invalid motion URL.");
-						motionRequest?.succeed();
-						motionJobs.transition(job, "completed", {
-							motionUrl, prompt: prompts.join(" "), blocks: segments, drop, targetCharacterId,
-							summary: `${clipSeconds.toFixed(1)}s / ${clipFrames} frames${promptNote}`,
-						});
-						await publishMotionJob(job);
-					} catch (error) {
-						if (job.status === "cancelled" || controller.signal.aborted || error?.name === "AbortError") {
-							motionRequest?.fail(error, "aborted");
-							if (job.status !== "cancelled") motionJobs.transition(job, "cancelled", { message: "Generation cancelled before editor delivery." });
-						} else {
-							motionRequest?.fail(error);
-							motionJobs.transition(job, "failed", { message: error instanceof Error ? error.message : "Motion generation failed." });
-						}
-						await publishMotionJob(job);
-					} finally {
-						clearTimeout(deadline);
-						job.cancel = null;
-					}
-				};
-				queueMicrotask(run);
-				return text(JSON.stringify(motionJobs.task(job)));
+			async ({ phases, seconds = 9, seed, motion_url, drop, ...admission }) => {
+				if (!liveHub?.connected) return text(noLiveEditor("Motion requires a connected CozyClay editor."));
+				const normalized = normalizePhases(phases.map(phase => typeof phase === 'string' ? phase : phase.text));
+				const beats = normalized.texts.map((text, index) => ({ text, seconds: phases[normalized.sources[index]]?.seconds ?? seconds / phases.length })).filter(beat => beat.text);
+				return runStudioCommand({ ...admission, action: motion_url ? 'motion.replace' : 'motion.generate', args: context => {
+					const generated = generationArgs({ characterId: context.activeCharacterId, source: { kind: 'generate', beats, ...(seed === undefined ? {} : { seed }) } });
+					return motion_url ? { characterId: generated.characterId, url: motion_url, prompt: beats.map(beat => beat.text).join(' '),
+						blocks: generated.blocks.map(({ startFrame, endFrame, text: prompt }) => ({ startFrame, endFrame, prompt })), ...(drop ? { drop } : {}) }
+						: { ...generated, ...(drop ? { drop } : {}) };
+				} });
 			},
 		),
 
@@ -1534,7 +1330,7 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					hidden: z.boolean().optional().describe("true hides the prop without deleting it"),
 				},
 			},
-			async ({ id, x, y, z: zPos, facing, tilt, roll, scale, scale_x, scale_y, scale_z, color, name, path, height, clay, hidden }) => {
+			async ({ id, x, y, z: zPos, facing, tilt, roll, scale, scale_x, scale_y, scale_z, color, name, path, height, clay, hidden, ...admission }) => {
 				const travelPath = path === null
 					? null
 					: path
@@ -1542,15 +1338,11 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 						: undefined;
 				if (liveHub?.connected) {
 					try {
-						await appliedLiveMutation("update_object", {
-							id, x, y, z: zPos, rot: facing, rotX: tilt, rotZ: roll,
-							scale, scaleX: scale_x, scaleY: scale_y, scaleZ: scale_z, color, name,
-							...(travelPath !== undefined ? { path: travelPath } : {}),
-							...(height !== undefined ? { height } : {}),
-							...(clay !== undefined ? { clay } : {}),
-							...(hidden !== undefined ? { hidden } : {}),
-						});
-						return text(`Updated ${id}.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "object.update", args: { id, patch: {
+							x, y, z: zPos, rot: facing, rotX: tilt, rotZ: roll,
+							scaleX: scale_x ?? scale, scaleY: scale_y ?? scale, scaleZ: scale_z ?? scale,
+							color, name, path: travelPath, height, clay, hidden,
+						} } });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1591,11 +1383,10 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				description: "Take a prop out of the set.",
 				inputSchema: { id: z.string().describe("object id") },
 			},
-			async ({ id }) => {
+			async ({ id, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						await appliedLiveMutation("remove_object", { id });
-						return text(`Removed ${id}.\n\n${sceneReport()}`);
+						return await runStudioCommand({ ...admission, action: "object.remove", args: { ids: [id] } });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1639,18 +1430,12 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 					label: z.string().min(1).default("MCP batch").describe("the single editor undo entry name"),
 				},
 			},
-			async ({ ops, atomic, stopOnError, label }) => {
+			async ({ ops, atomic, stopOnError, label, ...admission }) => {
 				if (!liveHub?.connected) return text(noLiveEditor("apply_batch requires a connected CozyClay editor."));
 				try {
-					const result = await appliedLiveMutation("apply_batch", { ops, atomic, stopOnError, label });
-					const applied = Array.isArray(result?.applied) ? result.applied : [];
-					const failed = Array.isArray(result?.failed) ? result.failed : [];
-					const failure = failed[0];
-					const summary = result?.rolledBack
-						? `Batch rolled back after failure at operation ${failure?.index ?? "unknown"}.`
-						: `Applied ${applied.length} operation(s).`;
-					const detail = failure ? ` Failure at operation ${failure.index}: ${failure.error}.` : "";
-					return text(`${summary}${detail}\n\n${sceneReport()}`);
+					// #446: the v1 alias is objects-only, so objects.batch (not a
+					// generic run.batch) preserves its options and single undo entry.
+					return await runStudioCommand({ ...admission, action: "objects.batch", args: { ops, atomic, stopOnError, label } });
 				} catch (error) {
 					return liveError(error);
 				}
@@ -1780,30 +1565,30 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 			{
 				title: "Add a scene",
 				description:
-					"Add another scene to the project and make it active. With a connected editor, the complete " +
-					"scene document is forwarded through that workspace's load_scenes command before success is reported; " +
-					"without one, this changes MCP memory only.",
+					"Add another scene to the project and make it active. A connected editor runs scene.create then scene.rename " +
+					"and returns both bus receipts; without one, this changes MCP memory only.",
 				inputSchema: { name: z.string().default("SCENE 02").describe("scene name") },
 			},
-			async ({ name }) => {
+			async ({ name, ...admission }) => {
 				if (liveHub?.connected) {
+					let created;
 					try {
-						await refreshLiveDescription();
+						created = await executeStudioCommand({ ...admission, action: "scene.create" });
+						if (!created.ok) return studioResult(created);
+						// Creation is a document boundary; naming is a separate retained edit.
+						const renamed = await executeStudioCommand({ ...admission, action: "scene.rename",
+							commandId: admission.commandId ? createHash("sha256").update(`${admission.commandId}:rename`).digest("hex") : undefined,
+							args: { sceneId: created.host.sceneId, name }, expectedRevision: created.revision.after });
+						return studioResult(created, renamed);
 					} catch (error) {
-						return liveError(error);
+						const failure = liveError(error);
+						if (created) failure.content.unshift(...studioResult(created).content);
+						return failure;
 					}
 				}
 				const document = JSON.parse(JSON.stringify(state.doc));
 				document.scenes = addScene(document.scenes, name);
 				document.activeSceneId = document.scenes[document.scenes.length - 1].id;
-				if (liveHub?.connected) {
-					try {
-						const live = await appliedLiveMutation("load_scenes", { document });
-						requireLiveSceneParity("add_scene", document, live);
-					} catch (error) {
-						return liveError(error);
-					}
-				}
 				state.doc = document;
 				return text(`Added "${scene().name}".\n\n${sceneReport()}`);
 			},
@@ -1814,14 +1599,18 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 			{
 				title: "Switch the active scene",
 				description:
-					"Make a different scene active. With a connected editor, the complete scene document is forwarded " +
-					"through that workspace's load_scenes command before success is reported; without one, this changes MCP memory only.",
+					"Make a different scene active through scene.switch and return its bus receipt. Without a connected editor, this changes MCP memory only.",
 				inputSchema: { name: z.string().describe("scene name to switch to") },
 			},
-			async ({ name }) => {
+			async ({ name, ...admission }) => {
 				if (liveHub?.connected) {
 					try {
-						await refreshLiveDescription();
+						return await runStudioCommand({ ...admission, action: "scene.switch", args: async () => {
+							await refreshLiveDescription();
+							const target = state.doc.scenes.find(row => row.name.toLowerCase() === name.toLowerCase());
+							if (!target) throw new Error(`No scene "${name}".`);
+							return { sceneId: target.id };
+						} });
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1832,14 +1621,6 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				}
 				const document = JSON.parse(JSON.stringify(state.doc));
 				document.activeSceneId = target.id;
-				if (liveHub?.connected) {
-					try {
-						const live = await appliedLiveMutation("load_scenes", { document });
-						requireLiveSceneParity("switch_scene", document, live);
-					} catch (error) {
-						return liveError(error);
-					}
-				}
 				state.doc = document;
 				return text(`Switched to "${scene().name}".\n\n${sceneReport()}`);
 			},
@@ -1850,10 +1631,13 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 			{
 				title: "Open a .cclayproject file",
 				description:
-					"Load a project authored in the CozyClay studio (or saved here). Replaces the current state.",
-				inputSchema: { path: z.string().describe("path to a .cclayproject file") },
+					"Load a project authored in the CozyClay studio (or saved here). Replacing scene ids in a connected editor requires a Studio-issued confirmationToken; returns the load_scenes bus receipt.",
+				inputSchema: {
+					path: z.string().describe("path to a .cclayproject file"),
+					confirmationToken: z.string().min(1).max(120).optional().describe("token issued by the Studio UI for this exact scene document"),
+				},
 			},
-			async ({ path }) => {
+			async ({ path, ...admission }) => {
 				let full;
 				let raw;
 				try {
@@ -1879,8 +1663,14 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				const nextDocument = scenes.document;
 				if (liveHub?.connected) {
 					try {
-						const live = await appliedLiveMutation("load_scenes", { document: nextDocument });
-						requireLiveSceneParity("open_project", nextDocument, live);
+						const loaded = await executeStudioCommand({ ...admission, action: "load_scenes", args: { document: nextDocument } });
+						if (loaded.ok) {
+							state.name = result.project.name;
+							state.focus = null;
+							state.focusLocked = false;
+							state.markedFraming = null;
+						}
+						return studioResult(loaded);
 					} catch (error) {
 						return liveError(error);
 					}
@@ -1972,5 +1762,58 @@ export const createToolHandlers = ({ projectRootPromise, motionJobs, publishMoti
 				return text(`Saved "${state.name}" to ${full} (${state.doc.scenes.length} scene(s)).`);
 			},
 		),
+
+		tool(
+			"studio_commands",
+			{
+				title: "List Studio commands",
+				description:
+					"List every command the connected editor registers, for studio_run: id, label, kind (mutation, transient, job, document), " +
+					"exposure, whether it is available now (the reason when not), and timeoutMs or generation where declared. The list carries " +
+					"no schemas; pass ids to read those commands' full declarations, description and input schema included.",
+				inputSchema: {
+					ids: z.array(z.string().min(1).max(120)).min(1).max(32).optional().describe("command ids whose full declarations to read"),
+				},
+			},
+			async ({ ids }) => {
+				if (!liveHub?.connected) return liveError(new Error(noLiveEditor("studio_commands requires a connected CozyClay editor.")));
+				try {
+					const listed = await liveHub.command("inspect_studio", { scope: "actions", ...(ids ? { ids } : {}) }, liveWorkspace.getStore());
+					return text(JSON.stringify({ actions: listed?.actions ?? [] }));
+				} catch (error) {
+					return liveError(error);
+				}
+			},
+		),
+
+		tool(
+			"studio_run",
+			{
+				title: "Run a Studio command",
+				description:
+					"Run one command the connected editor registers, by id, through the editor's command bus: the same door its UI and agent use. " +
+					"args must match the command's input schema (read it with studio_commands and ids). The command is admitted at the open " +
+					"document and its current revision unless expectedRevision is given, and answers the editor's JSON receipt: status, summary, " +
+					"affectedIds, undo, and output for a job. A refusal is a receipt with ok false and its code: STALE_SCENE means read again and " +
+					"re-issue; CONFIRMATION_REQUIRED means obtain the user's approval in Studio and pass its confirmationToken. Reusing a commandId returns the receipt of " +
+					"that earlier call instead of running again.",
+				inputSchema: {
+					action: z.string().min(1).max(120).describe("command id, as studio_commands lists it"),
+					args: z.record(z.string(), z.unknown()).default({}).describe("the command's arguments, matching its input schema"),
+					expectedRevision: z.number().int().min(0).optional().describe("the scene revision the command is admitted at; defaults to the current one"),
+					commandId: z.string().min(1).max(120).optional().describe("idempotency key; a repeated id answers the first call's receipt"),
+					timeoutMs: z.number().int().min(1).max(MAX_COMMAND_TIMEOUT_MS).optional().describe("how long the hub waits; defaults to the command's declared timeout"),
+					confirmationToken: z.string().min(1).max(120).optional().describe("Studio UI approval token for this exact command; MCP cannot mint one"),
+				},
+			},
+			async (args) => {
+				if (!liveHub?.connected) return liveError(new Error(noLiveEditor("studio_run requires a connected CozyClay editor.")));
+				try {
+					return await runStudioCommand(args);
+				} catch (error) {
+					return liveError(error);
+				}
+			},
+		),
 	];
 };