cozyclay 2.1.1 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 ## Unreleased
 
+## 3.0.1 - 2026-10-19
+
+Fixes from an audit of recent Studio agent sessions.
+
+Motion
+
+- Whole-body pitch and roll take full turns; new skill `flip` (back, front,
+  cartwheel).
+- New skill `hitReaction`: a body hit by an object or a person is thrown,
+  lands and comes to rest.
+- Other characters' installed takes are bodies for QA and anchor targets
+  (`{kind: "person", person, bone}`, refs `person:<id>.<Bone>`).
+- A dropped object tumbles and rests on a stable face.
+- The `fist` and `grip` thumbs wrap the fingers instead of standing up.
+
+Studio and agent
+
+- QA reads as problems (`qa.problems`), not frame-level issues, on the draft
+  card, the timeline beats and the receipt summary.
+- The agent's requests carry less old bulk (older images and receipts are
+  shortened at call time), replies follow the user's language, and the plan
+  image comes only when staging or the scene asks for it.
+- The agent can place a character within ±240 m, rename a shot and set a
+  shot's camera mode (`shot.setCameraMode`). `object.attach` no longer
+  crashes, and an editor fault answers `INTERNAL_ERROR`.
+- Playback no longer stutters in large scenes: panels stop serializing the
+  scene on every render.
+
+## 3.0.0 - 2026-10-19
+
+Motion is computed, not generated. The Studio agent writes a motion spec (key
+poses, skills, walks, contacts and goals) and a deterministic compiler in the
+browser bakes it frame by frame and measures it with QA. The agent compiles,
+reads the numbers and fixes the spec in seconds, with no GPU host.
+
+Breaking
+
+- The motion-generation backend (ARDY with Kimodo) is removed, and with it
+  text-to-motion generation, AI video, video motion capture, line edit,
+  AutoPhysics, platform fit and the collision fixer. `npm run dev` starts no
+  motion bridge and `CCLAY_KIMODO_HOST` is no longer read.
+- Motion is stored as a new take, `cozyclay.take.v3`: per-bone rotations on
+  the X Bot and Y Bot rigs, the hips' path, object tracks and the spec that
+  made it. A 2.x project still opens, but its generated (npz) motion is
+  dropped when the project is read; compile new motion for its characters.
+
+Motion compiler
+
+- `motion.compile`, `motion.qa`, `motion.sample`, `motion.describe` and
+  `motion.keyObject`. Specs combine keys, generators and skills (`standIdle`,
+  `walkTo`, `sitInSeat`, `exitCar`, `reachGrip`, `smokeCigarette`), with
+  two-bone IK limbs, finger presets and hand anchors on the world, the body,
+  bones, moving objects or the mouth.
+- QA measures collisions with scene objects and the body's own skin, foot
+  slides, floating, reach, balance, elbow, knee and wrist limits and pops, and
+  names each issue's cause with a hint. Hints become patches that
+  `repair` rounds apply; `goals` (near, above, moved, still, speed, ordering)
+  state what the motion must do.
+- Held props: grab and release, carried groups, keyed and falling objects,
+  prop kits and aim keys; the arm follows what the hand holds.
+- The walk rolls heel to toe, sets its hips from the legs, keeps an uneven
+  natural rhythm, and scales its knees, ankles, arm swing and trunk with its
+  pace. A held pose breathes and shifts its weight.
+- Compiles run in a Web Worker, off the editor's main thread. The Sequencer
+  cuts, retimes and trims an installed take.
+
+Look
+
+- Practical point and spot lights, glow, lighting looks
+  (`stage.applyLighting`), sky light with ambient occlusion and HDR
+  environment maps.
+- Deterministic effects: smoke, exhale, steam, fire, sparks, dust, rain, snow
+  and a motion trail.
+- Characters default to white clay; the outline ink is at half strength.
+
+Agent and Studio
+
+- The agent's motion drafts show while it works: as beats on the timeline,
+  as a ghost on the character and in the panel, which also shows the running
+  turn's reasoning and steps. Replies render their Markdown.
+- Contact sheets pick beat frames, add views that show depth, and draw
+  trails and onion-skin ghosts; the viewport has ghosts too.
+- The agent cuts for a new view and lays a camera move as one rail.
+- Connect a model runs the agent runtime's own provider login; keys are
+  checked before they are kept. Supervisor review is off by default.
+- Objects scale down to 1 cm, inspect reports each object's world box,
+  verify reports support gaps, and a follow dolly goes up to 40 m/s.
+
 ## 2.1.1 - 2026-10-13
 
 - Include the sampled framing fix, embedded composition-guide controls, and

package/README.md

@@ -42,7 +42,7 @@ That is the whole install. Not sure yet? **[Try it in the browser first](https:/
 npx cozyclay --scene city-block
 ```
 
-The studio ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating *new* motion is optional and uses the Kimodo bridge when configured.
+The camera tutorial seeds a compiled walk, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away. New motion is compiled in the browser from a motion spec — no GPU box or sidecar needed.
 
 ## Demo
 
@@ -57,9 +57,8 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 | **Cut and move the camera** | Add shots on the timeline, draw a dolly rail on the Top-View, set speed, height and crane, and preview the move through the shot camera. Each shot carries a **Target model** (Seedance 2.5, Kling 2, Veo 3, self-hosted MiniMax-H3) and is flagged when the cut runs past that model's limits. |
 | **Export for AI video** | One **Export ▾** menu: a keyframe pack (first/last frame, clip, camera JSON, prompt, README) as a zip, an mp4 of the shot, depth + normal conditioning passes, a storyboard contact sheet, and an OTIO cut list. Seedance 2.5 reads the pack's greybox clip as its white-model reference video, and MiniMax H3, Wan 3.0, LTX Desktop and fal render-to-real accept the same clip. The **Shot Prompt** turns the framing into a structured prompt for the model you picked. |
 | **Undo anything** | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit, an agent's camera key is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform. |
-| **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to Kimodo, then play the result back with sparse IK correction where the generated motion needs fixing. Draw over a joint's trail to reshape a take, keep most of it and regenerate a window, and step back through its history. |
-| **Capture motion from video or a photo** | Drop a clip or a still: the GPU box runs [GVHMR](https://github.com/zju3dv/GVHMR) and the result is retargeted onto the character with stabilisation, contact correction and a quality gate. |
-| **Direct it with an AI** | Open the **Agent panel** (`Cmd/Ctrl+B`), sign in with your ChatGPT account, and ask for a shot in plain language; the conversation survives reloads and you can paste a reference screenshot into it. Or connect Claude — or any MCP client — or drive the Studio from a terminal with `cclay live`. All three place the cast, frame "a low wide profile", generate multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control). |
+| **Compile motion** | The agent writes a motion spec — key poses, hand anchors, props, walks, hinged doors — and a deterministic compiler bakes every frame on the X Bot or Y Bot rig, then QA measures collisions, foot slide, reach and the contacts the spec declares ([`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md)). A compiled take is saved as its spec and replays identically; sparse IK keys and range pins correct any frame on top. |
+| **Direct it with an AI** | Open the **Agent panel** (`Cmd/Ctrl+B`), sign in with your ChatGPT account, and ask for a shot in plain language; the conversation survives reloads and you can paste a reference screenshot into it. Or connect Claude — or any MCP client — or drive the Studio from a terminal with `cclay live`. All three place the cast, frame "a low wide profile", compile motion, and the viewport moves in front of you. See [AI control](#ai-control). |
 
 ## Modes
 
@@ -68,9 +67,9 @@ A project is either a **Storyboard** or an **Animation**. Pick it on the start s
 | | Storyboard | Animation |
 | --- | --- | --- |
 | **Choose it when** | You want a row of still panels: framing, who stands where, a caption and a hold per panel | You want moving shots: motion on a timeline, camera moves, takes |
-| **Timeline** | The **Board** dock tab: one card per panel with a greybox thumbnail, caption, hold, duplicate, delete and drag-to-reorder | Shots on the timeline, with motion and Prompt Blocks |
+| **Timeline** | The **Board** dock tab: one card per panel with a greybox thumbnail, caption, hold, duplicate, delete and drag-to-reorder | Shots on the timeline, with the compiled take |
 | **Cast** | Rigged characters or capsule figures; each panel can keep its own placement ("Use stage placement" clears it) | Rigged characters with Pose and Motion mode; capsule figures for blocking |
-| **Motion tools** | Hidden: no Generate group, no Motion mode (`4`); the agent has no `generate_motion` and the MCP motion tools answer `NOT_IN_MODE` | Available |
+| **Motion tools** | Hidden: no Motion mode (`4`) | Available |
 | **Agent** | **Agent · Storyboard** builds one panel per request and never generates motion | The full Studio tool set |
 | **Exports** | **Stylize** a panel through the image route, **Send to Workflow** (the stylized image or the greybox) from its card, plus the Export ▾ menu: **Contact sheet (PNG)**, **Panel pack (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and **Depth + normal (PNG)**; File ▸ **Export as Animation project…** turns the panels into an Animation. There is no keyframe pack or shot video in a storyboard | Export ▾: keyframe pack, mp4, depth + normal passes, contact sheet, OTIO cut list |
 
@@ -101,18 +100,7 @@ npm install
 npm run dev
 ```
 
-Open `http://127.0.0.1:5180/app/` for the Studio (the root redirects there) and `http://127.0.0.1:5180/workflow/` for the Workflow canvas. `npm run dev` starts the studio together with its local Kimodo bridge once `CCLAY_KIMODO_HOST` points at a GPU box; without that variable it starts the studio alone and says so. `npm run dev:ui` starts the browser UI alone in every case.
-
-### Motion generation
-
-Generating new motion needs Kimodo on a machine you can reach. Point the Studio at it and install the worker once:
-
-```bash
-CCLAY_KIMODO_HOST=user@your-gpu-box npm run kimodo:setup
-CCLAY_KIMODO_HOST=user@your-gpu-box npx cozyclay
-```
-
-The installer detects OS, architecture, RAM and CUDA and picks the best-supported backend for that host — kimodo-mlx on a big Apple Silicon machine, kimodo.cpp with Metal or CPU otherwise, the upstream PyTorch stack on NVIDIA. An SSH-accessible NVIDIA box is the classic target and the only route with the full feature set; the same box runs GVHMR for video and photo mocap. Routes, overrides and local-only limits are in [`docs/kimodo-setup.md`](docs/kimodo-setup.md).
+Open `http://127.0.0.1:5180/app/` for the Studio (the root redirects there) and `http://127.0.0.1:5180/workflow/` for the Workflow canvas. `npm run dev` starts the studio together with its local OAuth and agent sidecar; `npm run dev:ui` starts the browser UI alone.
 
 ## AI control
 
@@ -153,8 +141,8 @@ The studio ships an [MCP](https://modelcontextprotocol.io) server, so any MCP cl
 
 Drop that into `claude_desktop_config.json` (or any MCP client config) and restart the client. The first run automatically installs the MCP SDK's 95-package tree; opening the studio never waits on it, so those dependencies are fetched only when you actually want the server.
 
-- **Editor open?** Tool calls move the visible viewport — camera, cast, set, generated motion, prompt blocks on the timeline.
-- **No editor?** Scene and project tools run headless: block scenes, derive film vocabulary ("wide shot · right profile · knee level · 24mm"), render AI video prompts, and write `.cclayproject` files. `capture_frame`, `set_prompt_blocks`, `generate_motion`, and `apply_batch` require the live editor.
+- **Editor open?** Tool calls move the visible viewport — camera, cast, set, compiled motion on the timeline.
+- **No editor?** Scene and project tools run headless: block scenes, derive film vocabulary ("wide shot · right profile · knee level · 24mm"), render AI video prompts, and write `.cclayproject` files. `capture_frame` and `apply_batch` require the live editor.
 
 Tools, transports and the live-control protocol are documented in [`mcp/README.md`](mcp/README.md).
 
@@ -195,13 +183,13 @@ Every control's home is recorded in [`docs/studio-ui-ia.md`](docs/studio-ui-ia.m
 
 | Read | For |
 | --- | --- |
-| [`docs/kimodo-setup.md`](docs/kimodo-setup.md) | Installing Kimodo: the route table, CUDA over SSH, local MLX/Metal/CPU generation and what each route supports |
+| [`docs/motion3-agent-guide.md`](docs/motion3-agent-guide.md) | How the agent writes a motion spec, compiles it and reads QA |
 | [`docs/agent-cli.md`](docs/agent-cli.md) | Driving the Studio from a terminal with `cclay live` |
 | [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking, and the one-panel-per-request rule in storyboards |
 | [`mcp/README.md`](mcp/README.md) | MCP tools, transports, and the live-control protocol |
 | [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md) | Where every Studio control lives and why |
 | [`docs/privacy.md`](docs/privacy.md) | The full analytics disclosure: events, identifiers, opt-out, internal QA marking |
-| [`workers/api/README.md`](workers/api/README.md) | The hosted demo on cozyclay.org: queue policy, the Cloudflare Worker and the GPU-box poller |
+| [`workers/api/README.md`](workers/api/README.md) | The cozyclay.org API Worker: sign-in and the hosted video-model route |
 | [`docs/releasing.md`](docs/releasing.md) | Publishing a signed npm release |
 | [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
 
@@ -217,7 +205,7 @@ Longer reads on the site: [Greybox to AI video](https://cozyclay.org/greybox-to-
 | `npm run test:objects` | Gizmo interaction in a real browser — needs `npm run dev:ui` in another shell |
 | `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
 | `npm run test:lifecycle` | Dev-server process lifecycle |
-| `npm run test:ardy` | Motion conversion, playback, and IK pipeline |
+| `npm run test:ardy` | IK pipeline, range pins and timeline helpers |
 | `node tools/run-tests.mjs` | Every Node verification file (what CI runs) |
 | `npm run qa:browser -- node test/qa-camera-tutorial-browser.mjs` | The seven-step tutorial driven with real input, beacons pinned to their controls |
 | `QA_URL=… CDP_PORT=… OUT=/tmp/count npm run qa:browser -- node tools/qa/studio-control-count.mjs` | Simultaneously visible controls per mode (budget: Scene ≤35 / Camera ≤38 / Motion ≤52) |
@@ -235,7 +223,7 @@ npm run qa:browser -- node <qa-script>
 
 Found something broken, or want a feature? [Open an issue](https://github.com/NomaDamas/CozyClay/issues) — bug reports with a repro are the most useful thing you can send. Contributions are accepted under `AGPL-3.0-or-later`.
 
-**Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `tools/ardy/out/`, `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
+**Repository hygiene.** Generated motion archives, QA output, build output, logs and local runtime artifacts are not source files and must not be committed. Keep `artifacts/`, `dist/`, `.gjc/` and `.npz` files local.
 
 Every runtime library except the two agent packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`) intentionally lives in `devDependencies`, because the published npm package ships the prebuilt `dist/`, so `npx cozyclay` must not install the studio's dependency tree.
 
@@ -250,12 +238,6 @@ cclay telemetry off
 
 `COZYCLAY_TELEMETRY=0` or `DO_NOT_TRACK=1` disables collection for a launch; **Settings ▾ → Privacy** is the same switch inside the Studio. The event list, what each identifier is, how internal QA traffic is marked and the first-edit definition are in [`docs/privacy.md`](docs/privacy.md).
 
-## Hosted demo
-
-Installing a GPU motion backend is the hard part, so `cozyclay.org` also runs a queued demo: a visitor writes one prompt, gets a ticket link, and a GPU box owned by the maintainer generates the motion and uploads it — the result opens in the studio itself. The composer pages, the Cloudflare Worker queue API and the GPU-box poller all live in this repository; the queue policy and runbooks are in [`workers/api/README.md`](workers/api/README.md).
-
 ## License & credits
 
 GNU Affero General Public License v3.0 or later — see [`LICENSE`](LICENSE) and the transition details in [`LICENSING.md`](LICENSING.md). Modified network services must offer their users the corresponding source. Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
-
-The hosted demo worker may use an externally installed [NVIDIA ARDY](https://github.com/nv-tlabs/ardy) runtime. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA. The local Studio uses Kimodo instead.

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 { createProviderRoutes } from "./provider-routes.mjs";
 import { STUDIO_SYSTEM_PROMPT_STORYBOARD } from "./studio-prompt.mjs";
 
 // Values the codex backend accepts for reasoning.effort (its own 400 lists them).
@@ -85,9 +86,9 @@ const agentFailureCode = (error, signal, tool = false) => advisory(() => {
  * 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.
+ * context without a previsMode runs unwrapped (an editor that predates turn
+ * transactions). mark() records where a script starts; rollback() undoes only
+ * the edits after it and keeps the turn open, so earlier edits still land.
  */
 const agentTurn = ({ hub, context, turnId, admission }) => {
 	const wrapped = Boolean(context.scene?.previsMode);
@@ -102,12 +103,11 @@ const agentTurn = ({ hub, context, turnId, admission }) => {
 	};
 	const open = async () => { await control("agent.turn.begin"); admission.turnId = turnId; };
 	return {
+		mark: async () => (admission.turnId === turnId ? control("agent.turn.mark") : null),
 		async rollback() {
 			if (admission.turnId !== turnId) return null;
-			delete admission.turnId;
-			const receipt = await control("agent.turn.cancel");
+			const receipt = await control("agent.turn.rollback");
 			await admission.refresh();
-			await open();
 			return receipt;
 		},
 		run: start => async function* (input) {
@@ -119,7 +119,7 @@ const agentTurn = ({ hub, context, turnId, admission }) => {
 					if (frame.type === "done") terminal = frame; else yield frame;
 				}
 			} finally {
-				// A rollback whose reopen failed has already closed the transaction.
+				// Finish only the transaction this run opened (a rollback keeps it open).
 				if (admission.turnId === turnId) {
 					delete admission.turnId;
 					const receipt = await control("agent.turn.finish");
@@ -381,9 +381,10 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		try { if (await auth.getAccessToken()) return true; } catch { /* an unavailable ChatGPT token is not a credential */ }
 		const registry = await ensureWorkflowModels();
 		if (typeof registry?.getAuth !== "function") return false;
-		const { PROVIDERS } = await import("./providers.mjs");
-		for (const provider of PROVIDERS) {
-			try { if (await registry.getAuth(provider.id)) return true; } catch { /* one broken provider does not break the gate */ }
+		// the curated providers and any other one a pi login stored a credential for (#pi-login)
+		const [{ PROVIDERS }, { readCredentials }] = await Promise.all([import("./providers.mjs"), import("./provider-keys.mjs")]);
+		for (const id of new Set([...PROVIDERS.map((provider) => provider.id), ...Object.keys(readCredentials())])) {
+			try { if (await registry.getAuth(id)) return true; } catch { /* one broken provider does not break the gate */ }
 		}
 		return false;
 	};
@@ -395,9 +396,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	const studioOwnerTokens = new Map();
 	const parseCookies = req => Object.fromEntries(String(req.headers.cookie || "").split(";").map(part => part.trim().split("=")).filter(([key, value]) => key && value).map(([key, value]) => [key, decodeURIComponent(value)]));
 	const pruneStudioSessions = () => {
-		const now = clock();
-		for (const [id, session] of studioSessions) if (!session.activeJobId && now - session.updatedAt > 600_000) { studioSessions.delete(id); studioOwnerTokens.delete(id); for (const turn of session.turns.keys()) studioEvents.delete(turn); }
-		const retired = [...studioSessions.entries()].filter(([, session]) => !session.activeJobId).sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+		const now = clock(), idle = session => !(session.activeTurnId && session.controller && !session.controller.signal.aborted); // a running turn keeps its session
+		for (const [id, session] of studioSessions) if (idle(session) && now - session.updatedAt > 600_000) { studioSessions.delete(id); studioOwnerTokens.delete(id); for (const turn of session.turns.keys()) studioEvents.delete(turn); }
+		const retired = [...studioSessions.entries()].filter(([, session]) => idle(session)).sort((a, b) => a[1].updatedAt - b[1].updatedAt);
 		while (studioSessions.size > 256 && retired.length) { const [id, session] = retired.shift(); studioSessions.delete(id); studioOwnerTokens.delete(id); for (const turn of session.turns.keys()) studioEvents.delete(turn); }
 	};
 	const studioOwner = (req, sessionId, create = false) => {
@@ -425,13 +426,16 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		record.next = value.eventSeq;
 		const previous = record.events.at(-1);
 		if (value.type === "job.progress" && previous?.type === "job.progress" && previous.jobId === value.jobId) record.events[record.events.length - 1] = value;
+		// The panel's live frames (turn-frames.mjs, a script's nested calls) keep one replay slot per run of them.
+		else if (value.type === "thinking.delta" && previous?.type === "thinking.delta") record.events[record.events.length - 1] = { ...value, text: previous.text + value.text };
+		else if (value.type === "tool.progress" && previous?.type === "tool.progress" && previous.callId === value.callId) record.events[record.events.length - 1] = value;
 		else record.events.push(value);
 		if (record.events.length > 256) record.events.splice(0, record.events.length - 256);
 		if (["done", "error", "receipt"].includes(value.type)) record.terminal = true;
 		studioEvents.set(turnId, record); for (const listener of [...record.listeners]) listener(value);
 	};
-	const unsubscribe = auth.onAuthChange?.(({ kind }) => {
-		if (kind !== "signed_out" && kind !== "replaced") return;
+	// A sign-out, another account, or a provider key or server address that changed: the registry and every runner on it go.
+	const resetRegistry = () => {
 		for (const session of sessions.values()) session.controller?.abort();
 		for (const session of studioSessions.values()) session.controller?.abort();
 		for (const runner of [...workflowRunners.values(), ...studioRunners.values()]) void runner.close?.();
@@ -439,7 +443,9 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		workflowModels = models;
 		workflowModelsPromise = models ? Promise.resolve(models) : null;
 		sessions.clear(); studioSessions.clear(); studioEvents.clear(); studioOwnerTokens.clear();
-	});
+	};
+	const unsubscribe = auth.onAuthChange?.(({ kind }) => { if (kind === "signed_out" || kind === "replaced") resetRegistry(); });
+	const providerRoutes = createProviderRoutes({ auth, getModels: ensureWorkflowModels, onChange: resetRegistry, json, readBody });
 
 	const studioIdentity = host => Object.fromEntries(["workspaceId", "documentEpoch", "sceneId", "sceneEpoch"].map(key => [key, host[key]]));
 	const writeStudioStream = (res, record, after = 0) => {
@@ -473,27 +479,12 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		if (path === "/agent/stop") {
 			const session = studioSessions.get(value.sessionId);
 			if (!session || session.owner !== parseCookies(req).studio_owner || !session.turns.has(value.turnId)) throw new StudioProtocolError("AUTH_REQUIRED", "Studio stop is not owned by this session.");
-			const jobId = value.jobId ?? session.activeJobId;
-			// Explicit ids are checked against every motion job this session admitted.
-			// Retired ids remain in the set so a repeat Stop is idempotent, while an id
-			// admitted by another session is stale even when this session is idle.
-			if (value.jobId && !session.motionJobIds.has(value.jobId)) throw new StudioProtocolError("STALE_TARGET", "Stop does not own that motion job.");
-			// An owned retired id is still stale while another motion job is active:
-			// this Stop cannot acknowledge the current turn's different job.
-			if (value.jobId && session.activeJobId && value.jobId !== session.activeJobId) throw new StudioProtocolError("STALE_TARGET", "Stop does not target the active motion job.");
-			// Only this turn's held editor job can settle the tool quietly. A retired
-			// job from an earlier turn must never silence an unrelated turn's Stop.
-			const acknowledged = Boolean(session.activeJobId) && session.activeJobTurnId === value.turnId;
-			// The editor's outcome, not a sidecar abort, establishes application.
-			let outcome = null;
-			if (jobId) outcome = await session.controlJob('job.cancel', jobId);
-			if (jobId && session.activeJobId === jobId) { session.activeJobId = null; session.activeJobTurnId = null; }
-			// Let the acknowledged job settle its held tool with that outcome before
-			// aborting the model lane. Aborting the shared signal would interrupt the
-			// tool first and lose the editor's proof. Without a held job, abort both.
-			if (!acknowledged) session.controller?.abort();
-			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;
+			// Studio turns hold no editor jobs since 3.0 (motion.compile answers
+			// synchronously), so a Stop names no job: it aborts the turn and the model lane.
+			if (value.jobId) throw new StudioProtocolError("STALE_TARGET", "Stop does not own that motion job.");
+			session.controller?.abort();
+			await session.modelSession?.abort?.("studio stop");
+			json(res, 200, { ok: true, status: "detached" }); 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.");
@@ -516,7 +507,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			studioOwner(req, value.sessionId, true);
 			let 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() };
+			session = { owner: studioOwnerTokens.get(value.sessionId), history: persisted?.history ?? [], persistedItems: persisted?.history?.length ?? 0, meta: persisted?.meta ?? null, turns: new Map(), controller: null, host: null, updatedAt: clock() };
 			studioSessions.set(value.sessionId, session);
 		}
 		session.updatedAt = clock();
@@ -530,7 +521,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		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)) {
+			else if (!["execution_telemetry", "execution_tool_started", "thinking.delta", "tool.compose", "tool.progress"].includes(event.type)) {
 				if (event.type === "tool.start") replySegment = "";
 				turnFrames.push(event);
 			}
@@ -562,49 +553,11 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 				return refreshed;
 			},
 		};
-		// One motion generation per user message, whichever path starts it:
-		// generate_motion below and a run_action job action share this gate.
-		const generation = { used: false, failures: 0 };
-		// The editor's command index (authoritative context) declares each action's
-		// generation and hub timeout; no sidecar list of actions exists.
-		const controlJob = async (action, jobId) => {
-			await admission.refresh();
-			return hub.command('run_action', { name: 'run_action', args: { action, args: { jobId, ...(action === 'job.await' ? { timeoutMs: 300_000 } : {}) } },
-				commandId: randomUUID(), host: admission.host, expectedRevision: admission.revision }, value.context.host.workspaceHandle, { timeoutMs: 300_000 });
-		};
-		session.controlJob = controlJob;
-		const onJob = async started => {
-			const jobId = started.jobId;
-			session.motionJobIds.add(jobId);
-			persistenceMeta.motionJobIds = [...session.motionJobIds];
-			session.activeJobId = jobId; session.activeJobTurnId = value.turnId;
-			const cancel = () => { void controlJob('job.cancel', jobId).catch(error => send({ type: 'error', code: error.code ?? 'CANCEL_FAILED', message: error.message })); };
-			controller.signal.addEventListener('abort', cancel, { once: true });
-			if (controller.signal.aborted) cancel();
-			send({ type: 'job.state', jobId, commandId: started.commandId, state: 'generating', phase: 'generating' });
-			try {
-				const outcome = await controlJob('job.await', jobId);
-				send({ type: 'job.state', jobId, commandId: outcome.commandId, state: outcome.ok ? 'installed' : outcome.code === 'CANCELLED' ? 'cancelled' : 'failed', phase: 'complete' });
-				return outcome;
-			} finally {
-				controller.signal.removeEventListener('abort', cancel);
-				if (session.activeJobId === jobId) { session.activeJobId = null; session.activeJobTurnId = null; }
-			}
-		};
-		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.
-			if (args.source.kind !== 'generate') throw new StudioProtocolError('CAPABILITY_MISSING', 'Private motion artifacts are no longer retained. Use motion.loadVersion for an editor take.');
-			await tools.internal.invoke('inspect_studio', { scope: 'motion', ids: [args.characterId] });
-			const receipt = await tools.internal.invoke('generate_motion', args);
-			if (receipt.ok && receipt.status === 'completed') send({ type: 'receipt', receipt });
-			return receipt;
-		};
+		const tools = createStudioTools({ liveHub: hub, workspaceHandle: value.context.host.workspaceHandle, previsMode: value.context.scene?.previsMode, session: { signal: controller.signal, admission, actionIndex: current?.actionIndex ?? [], baseline: value.context }, resolveImage: async (id, correlation) => hub.command("resolve_studio_image", { imageId: id, ...correlation }, value.context.host.workspaceHandle) });
 		const modelTools = tools.map(tool => ({
 			...tool,
 			handler: async args => {
-				const result = await (tool.name === "generate_motion" ? motion(args) : tool.handler(args));
+				const result = await tool.handler(args);
 				if (!result || !Array.isArray(result.visualRefs) || !result.visualRefs.length) return result;
 					const ref = result.visualRefs.find(item => item?.imageId || item?.id);
 				if (!ref) return result;
@@ -616,9 +569,11 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 		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.
+			// A script that fails after it edited the scene rolls back its own edits, so
+			// the model retries from the document the script started from, never from
+			// half a script; what the turn did before the script stays.
 			handler: async (args, options) => {
+				await turnTransaction.mark();
 				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();
@@ -631,13 +586,13 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			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.
+		} else if ((await import("./studio-context-budget.mjs")).wantsPlan({ text: value.text, characterCount: value.context.scene?.characterCount ?? 0, shots: value.context.shots?.length ?? 0, planSeen: session.planSceneId === value.context.host.sceneId })) {
+			// A staging or coverage request sees the top-view plan, and so does a staged scene's first turn here (once per scene).
 			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 };
+				frameObservation = { kind: "plan", data: match[2], mimeType: match[1], revision: captured.revision ?? value.context.revision?.scene ?? null, receiptId: captured.receiptId }; session.planSceneId = value.context.host.sceneId;
 			} catch (error) {
 				console.warn(`[agent] plan observation skipped: ${error.message}`);
 			}
@@ -675,12 +630,12 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			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";
+			// Off by default: only a turn sent with value.supervisor === true is reviewed.
+			if (supervisor && process.env.COZYCLAY_SUPERVISOR !== "off" && value.supervisor === true && !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 persistenceMeta = { sceneName: value.context?.scene?.name ?? value.context?.sceneName ?? null, firstText: value.text };
 		const modelKey = value.model || (fauxProvider ? `${fauxProvider.provider?.id || fauxProvider.provider || "faux"}/scripted` : "gpt-6-astra");
 		let runner = studioRunners.get(value.sessionId);
 		if (!runner) {
@@ -789,35 +744,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			await session.modelSession.steer(value.text, images);
 			json(res, 200, { ok: true, queued: true }); return true;
 		}
-		if (path === "/agent/providers" && req.method === "GET") {
-			const { providerStatus } = await import("./providers.mjs");
-			try { json(res, 200, { providers: providerStatus({ auth }) }); }
-			catch { json(res, 500, { error: "provider credentials unavailable" }); }
-			return true;
-		}
-		if (/^\/agent\/providers\/[^/]+$/.test(path) && ["PUT", "DELETE"].includes(req.method)) {
-			const { PROVIDERS } = await import("./providers.mjs");
-			const keys = await import("./provider-keys.mjs");
-			const { createCredentialStore } = await import("./credential-store.mjs");
-			const id = path.slice("/agent/providers/".length);
-			if (!PROVIDERS.some((provider) => provider.id === id)) { json(res, 404, { error: "provider not found" }); return true; }
-			const credentials = createCredentialStore({ auth, keys });
-			let key;
-			if (req.method === "PUT") {
-				if (id === "openai-codex") { json(res, 400, { error: "Use ChatGPT sign-in for OpenAI Codex." }); return true; }
-				try {
-					const value = await readBody(req);
-					if (typeof value?.key !== "string" || !value.key.trim()) throw new Error("Invalid key.");
-					key = value.key.trim();
-				} catch { json(res, 400, { error: "a non-empty API key is required" }); return true; }
-			}
-			try {
-				if (req.method === "PUT") await credentials.modify(id, async () => ({ type: "api_key", key }));
-				else await credentials.delete(id);
-				json(res, 200, { ok: true });
-			} catch { json(res, 500, { error: "provider credentials could not be saved" }); }
-			return true;
-		}
+		if (await providerRoutes(req, res, path)) return true;
 		if (path === "/agent/sessions" && req.method === "GET") {
 			const surface = new URL(req.url, "http://127.0.0.1").searchParams.get("surface") || undefined;
 			try { json(res, 200, { sessions: sessionStore.list({ surface }) }); }

package/bin/agent/agent-runner.mjs

@@ -1,5 +1,7 @@
 import { summariseCanvasResult } from "./agent-tools.mjs";
+import { createReasoningFrames } from "./turn-frames.mjs";
 import { sanitizeUpstreamDetail } from "./agent-routes.mjs";
+import { budgetStudioRequest } from "./studio-context-budget.mjs";
 
 const DEFAULT_MODEL = "gpt-6-astra";
 
@@ -228,7 +230,7 @@ function studioObservationMessage(observation) {
 	return {
 		role: "user",
 		content: [
-			{ type: "text", text: `Studio ${observation?.kind === "plan" ? "plan observation (top view)" : "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"} at scene revision ${JSON.stringify(observation?.revision ?? null)}${observation?.receiptId ? `, receipt ${observation.receiptId}` : ""}` },
 			{ type: "image", data: observation.data, mimeType: observation.mimeType },
 		],
 	};
@@ -363,7 +365,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 
 		const ensureHarness = async (input) => {
 			const { pi, models: registry } = await ensureModels();
-			const activePrompt = input.systemPrompt || (input.surface === "studio" ? (await import("./studio-prompt.mjs")).STUDIO_SYSTEM_PROMPT : systemPrompt);
+			const activePrompt = input.systemPrompt || (input.surface === "studio" ? await (await import("./studio-motion-reference.mjs")).studioSystemPrompt() : systemPrompt);
 			const { resolveModel, resolveEffort } = await import("./providers.mjs");
 			const requested = input.model || DEFAULT_MODEL;
 			const slash = requested.indexOf("/");
@@ -396,7 +398,7 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 					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("transform_context", (event) => state.lastInput?.surface === "studio" ? budgetStudioRequest(studioContextDiet(event)) : undefined);
 				state.harness.hooks.on("before_payload", ({ model, payload }) => {
 					if (model?.api !== "anthropic-messages") return undefined;
 					const next = withAnthropicCacheBreakpoints(payload, model);
@@ -418,9 +420,8 @@ 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.
+				// Studio only, on the provider view (studioContextDiet, then studio-context-budget.mjs): the stored
+				// lane and the persisted history keep every context, result, script and image whole.
 				state.unsubscribers.push(state.harness.events.on("turn_end", persist));
 				state.unsubscribers.push(state.harness.events.on("run_end", persist));
 			}
@@ -449,27 +450,25 @@ export function createAgentRunner({ models: suppliedModels, sessionStore, tools
 				queue.push(frame);
 			};
 			const subscribe = (type, listener) => eventUnsubscribers.push(state.harness.events.on(type, listener));
+			// The reasoning summary and the tool call being written, for the panel (turn-frames.mjs).
+			const reasoning = createReasoningFrames(pushFrame, clock);
 			subscribe("message_update", (event) => {
+				reasoning.onMessageEvent(event.event);
 				if (event.event?.type === "text_delta") pushFrame({ type: "text.delta", text: event.event.delta });
 				if (event.event?.type === "error") pushFrame(errorFrame(event.event.error, event.event.reason === "aborted"));
 			});
-			subscribe("tool_start", (event) => {
+			const startTool = (event) => {
 				if (toolStarted.has(event.toolCallId)) return;
 				toolStarted.add(event.toolCallId);
 				toolStartedAt.set(event.toolCallId, clock());
 				const activeTools = state.lastInput?.tools || tools;
 				const tool = (Array.isArray(activeTools) ? activeTools : []).find((candidate) => candidate.name === event.toolName);
 				pushFrame({ type: "tool.start", callId: event.toolCallId, name: event.toolName, label: tool?.label || event.toolName.replaceAll("_", " "), args: summariseCanvasResult(event.args) });
-			});
+			};
+			subscribe("tool_start", startTool);
 			subscribe("tool_end", (event) => {
 				if (toolCompleted.has(event.toolCallId)) return;
-				if (!toolStarted.has(event.toolCallId)) {
-					toolStarted.add(event.toolCallId);
-					toolStartedAt.set(event.toolCallId, clock());
-					const activeTools = state.lastInput?.tools || tools;
-					const tool = (Array.isArray(activeTools) ? activeTools : []).find((candidate) => candidate.name === event.toolName);
-					pushFrame({ type: "tool.start", callId: event.toolCallId, name: event.toolName, label: tool?.label || event.toolName.replaceAll("_", " "), args: summariseCanvasResult(event.args) });
-				}
+				startTool(event);
 				toolCompleted.add(event.toolCallId);
 				const started = toolStartedAt.get(event.toolCallId) ?? clock();
 				const elapsedMs = Math.round(clock() - started);