cozyclay 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 3.1.1 - 2026-10-23
+
+Sculpt gets new shapes, cutters, detail and materials, and the Studio agent shows its plan and a live sketch.
+
+Sculpt
+
+- New sculpt shapes: loft, convex hull, lathe, tube and extrude, plus an
+  instanced scatter (blade, tuft, flower, leaf, pebble, twig) that fills a
+  part with up to 12000 items. Bad points are refused with their path.
+- Boolean cutters: a part with `op: subtract | intersect` cuts its parent for
+  windows, doors, arches, hollow bowls and cups, notches, half-domes and
+  slices.
+- Surface `detail` (seeded displacement) and colour `gradient` on any shape.
+- Material presets for sculpt parts and primitives: clay, wood, straw, stone,
+  brick, concrete, metal, glass, ceramic, plastic, rubber, fabric, paper and
+  foliage, each with a matte, satin or gloss finish.
+
+Agent
+
+- A step checklist for long Studio turns, pinned under the prompt while the
+  turn runs and restored with the session.
+- A live ghost sketch of the sculpt in the viewport while the agent is still
+  writing the script. It is never picked, saved or exported.
+- The Studio prompt, MCP and Sculpt mode know the new shapes, materials and
+  fields.
+
 ## 3.1.0 - 2026-10-23
 
 Hands that hold, throw and catch with weight, Studio tasks in the chat, faster playback, and a leaner first run.

package/bin/agent/agent-routes.mjs

@@ -379,9 +379,9 @@ 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.
+		// The panel's live frames (turn-frames.mjs, a script's nested calls, a call's sculpt sketch) 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 if (["tool.progress", "sculpt.sketch"].includes(value.type) && previous?.type === value.type && 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;
@@ -425,8 +425,8 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 	};
 	const handleStudioTurn = async (req, res, value, path) => {
 		const { StudioProtocolError, validateStudioContextFreshness } = await import("../../src/studio-agent-protocol.js");
-		const [{ createStudioTools }, { encodeStudioContext }, { createScriptTool }, { runSupervisor, shouldSupervise }] = await Promise.all([
-			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"), import("./script-tool.mjs"), import("./supervisor.mjs"),
+		const [{ createStudioTools }, { encodeStudioContext }, { createScriptTool }, { runSupervisor, shouldSupervise }, { createPlanTool }] = await Promise.all([
+			import("./studio-tools.mjs"), import("../../src/studio-agent-context.js"), import("./script-tool.mjs"), import("./supervisor.mjs"), import("./plan-tool.mjs"),
 		]);
 		const hubDeps = await runtime; const hub = hubDeps.liveHub || liveHub;
 		if (path === "/agent/stop") {
@@ -477,7 +477,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", "thinking.delta", "tool.compose", "tool.progress"].includes(event.type)) {
+			else if (!["execution_telemetry", "execution_tool_started", "thinking.delta", "tool.compose", "tool.progress", "sculpt.sketch"].includes(event.type)) {
 				if (event.type === "tool.start") replySegment = "";
 				turnFrames.push(event);
 			}
@@ -522,7 +522,8 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			},
 		}));
 		const turnTransaction = studioTransaction({ hub, context: current, turnId: value.turnId, admission, task: value.task, signal: controller.signal, plain: Boolean(value.main) });
-		const script = createScriptTool({ tools: modelTools, signal: controller.signal, emit: send });
+		// The turn's step checklist (plan-tool.mjs): the model calls it directly or inside a script, and the panel shows it.
+		const plan = createPlanTool({ emit: send }), script = createScriptTool({ tools: [...modelTools, plan.nested], signal: controller.signal, emit: send });
 		const scriptTool = {
 			...script,
 			// A script that fails after it edited the scene rolls back its own edits, so
@@ -604,7 +605,7 @@ export function createAgentHandler({ auth = defaultAuth, codex, models, codexBas
 			for await (const frame of turnTransaction.run(input => session.modelSession.start(input))({
 				surface: "studio", sessionId: value.sessionId, model: modelKey, effort: value.effort,
 				text: value.text, attachments: value.attachments, contextText: encodeStudioContext(value.context) + (value.main?.contextText() ?? ""), frameObservation,
-				reportCost: Boolean(value.task || value.main), context: value.context, tools: value.main ? value.main.tools({ studio: modelTools, hub, admission }) : [...modelTools, scriptTool], systemPrompt: value.main?.systemPrompt ?? (value.context.scene?.previsMode === "storyboard" ? STUDIO_SYSTEM_PROMPT_STORYBOARD : undefined), signal: controller.signal, emit: send,
+				reportCost: Boolean(value.task || value.main), context: value.context, tools: value.main ? value.main.tools({ studio: modelTools, hub, admission }) : [...modelTools, plan.track(scriptTool), plan], systemPrompt: value.main?.systemPrompt ?? (value.context.scene?.previsMode === "storyboard" ? STUDIO_SYSTEM_PROMPT_STORYBOARD : undefined), signal: controller.signal, emit: send,
 				meta: persistenceMeta,
 				quotaEvent: headers => codex?.parseQuotaHeaders ? quotaEvent(codex, headers) : { type: "quota", plan: null, primary: { usedPercent: null, windowMinutes: null, resetAt: null }, credits: { has: null } },
 			})) emitFrame(frame);

package/bin/agent/plan-tool.mjs

@@ -0,0 +1,114 @@
+// The Studio agent's `plan` tool: a short step checklist the Agent panel shows at the top of a long turn ("수레 몸체 ✓ →
+// 진열 소품 ● → 자전거 → 풀밭 → 조명·카메라"), so the user always sees what is under way and what comes next. It is
+// side-effect free: it never reaches the editor, so the scene, undo history and document stay as they are, and it answers
+// at once. Every change goes to the panel as one plan.update frame with the whole list ({ steps: [{ text, status }] }).
+//
+// One plan per turn (agent-routes.mjs makes one for each Studio turn). A script calls it too, as tools.plan, at no model
+// turn of its own (`nested`): there a refusal is returned rather than thrown, so a bookkeeping slip never fails the
+// script or rolls its edits back. The tool a plan change happened in carries the list in its result (`track`), which is
+// how the persisted session history (session-store.mjs transcriptFromHistory) brings the card back after a reload.
+
+const MIN_STEPS = 2, MAX_STEPS = 8, STEP_CHARS = 60;
+const FIELDS = ["steps", "done", "active", "add"];
+
+const DESCRIPTION = [
+	"Show the user a short step checklist in the Agent panel. It changes nothing in the scene, undo history or document, and answers at once.",
+	"For any request with 3 or more visible stages (building a set or several props, a multi-shot sequence), call plan first with short steps, in the same message as your first real call; then mark each step done right after its tool call — inside your script when you use one. Inside a script, tools.plan costs no extra turn.",
+	`{ steps: [${MIN_STEPS}-${MAX_STEPS} labels of a few words, in the user's language] } sets the list (again: replaces it) and step 0 is active; { done: i or [i, …], active?: i } updates it (indexes from 0; after done without active, the next step becomes active); { add: [labels] } appends steps.`,
+].join("\n");
+
+const PARAMETERS = {
+	type: "object",
+	properties: {
+		steps: { type: "array", items: { type: "string" }, description: `${MIN_STEPS}-${MAX_STEPS} short step labels; replaces the plan` },
+		done: { anyOf: [{ type: "integer" }, { type: "array", items: { type: "integer" } }], description: "index or indexes (from 0) of the steps now done" },
+		active: { type: "integer", description: "index of the step now under way" },
+		add: { type: "array", items: { type: "string" }, description: "labels appended as pending steps" },
+	},
+	required: [],
+	additionalProperties: false,
+};
+
+const refusal = message => Object.assign(new Error(message), { code: "INVALID_ARGUMENT" });
+const isRecord = value => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Labels from `field`, trimmed to one line each, or a refusal that says which one is wrong. */
+function labels(field, value, min) {
+	if (!Array.isArray(value) || value.some(text => typeof text !== "string")) throw refusal(`${field} must be an array of short strings (a few words each).`);
+	const texts = value.map(text => text.replace(/\s+/g, " ").trim());
+	const empty = texts.findIndex(text => !text);
+	if (empty !== -1) throw refusal(`${field}[${empty}] is empty.`);
+	const long = texts.findIndex(text => text.length > STEP_CHARS);
+	if (long !== -1) throw refusal(`${field}[${long}] is ${texts[long].length} characters; keep each step under ${STEP_CHARS} (a few words).`);
+	if (texts.length < min) throw refusal(`${field} has ${texts.length} item${texts.length === 1 ? "" : "s"}; a plan has ${MIN_STEPS}-${MAX_STEPS} steps (skip plan for a small request).`);
+	return texts;
+}
+
+/** A step index from `field`, or a refusal naming the plan's range. */
+function index(field, value, count) {
+	if (Number.isInteger(value) && value >= 0 && value < count) return value;
+	throw refusal(`${field} is ${JSON.stringify(value)}; the plan has ${count} steps, so a step index is 0-${count - 1}.`);
+}
+
+/**
+ * The plan after one call: `steps` replaces the list, `add` appends, `done` checks steps off and `active` names the
+ * one under way (any other active step goes back to pending). With no active step left, the step after the last one
+ * just done (else the first pending one) becomes active, so a new plan starts at step 0.
+ */
+function nextPlan(current, args) {
+	if (!isRecord(args)) throw refusal("plan takes an object: { steps: [...] } to set the plan, or { done, active } to update it.");
+	const unknown = Object.keys(args).filter(key => !FIELDS.includes(key));
+	if (unknown.length) throw refusal(`plan has unknown field${unknown.length > 1 ? "s" : ""} ${unknown.map(key => JSON.stringify(key)).join(", ")}; allowed: ${FIELDS.join(", ")}.`);
+	if (!FIELDS.some(key => args[key] !== undefined)) throw refusal(`plan needs steps (${MIN_STEPS}-${MAX_STEPS} short labels) to set the plan, or done/active/add to update it.`);
+	let steps = args.steps === undefined ? current : labels("steps", args.steps, MIN_STEPS).map(text => ({ text, status: "pending" }));
+	if (!steps.length) throw refusal("There is no plan yet: set one with { steps: [...] } first.");
+	if (args.add !== undefined) steps = [...steps, ...labels("add", args.add, 1).map(text => ({ text, status: "pending" }))];
+	if (steps.length > MAX_STEPS) throw refusal(`That makes ${steps.length} steps; a plan has at most ${MAX_STEPS}: merge some.`);
+	const done = args.done === undefined ? [] : Array.isArray(args.done) ? args.done.map((value, i) => index(`done[${i}]`, value, steps.length)) : [index("done", args.done, steps.length)];
+	const active = args.active === undefined ? null : index("active", args.active, steps.length);
+	if (done.includes(active)) throw refusal(`Step ${active} cannot be both done and active.`);
+	steps = steps.map((step, i) => i === active ? { ...step, status: "active" } : done.includes(i) ? { ...step, status: "done" } : active !== null && step.status === "active" ? { ...step, status: "pending" } : step);
+	if (!steps.some(step => step.status === "active")) {
+		const from = done.length ? Math.max(...done) + 1 : 0;
+		const next = steps.findIndex((step, i) => i >= from && step.status === "pending");
+		const advance = next !== -1 ? next : steps.findIndex(step => step.status === "pending");
+		if (advance !== -1) steps = steps.map((step, i) => i === advance ? { ...step, status: "active" } : step);
+	}
+	return steps;
+}
+
+/**
+ * createPlanTool({ emit }) -> the model-facing `plan` tool (bin/agent/pi-tools.mjs toAgentTools shape), plus
+ * `nested` (the same plan for a script's tools.plan: never throws, adds no call to the script's summary or progress)
+ * and `track(tool)` (that tool's result carries `plan` when the plan changed during its call, and `planRefused`
+ * when a nested call was refused).
+ */
+export function createPlanTool({ emit } = {}) {
+	let steps = [], version = 0;
+	const refused = [];
+	const apply = args => {
+		const next = nextPlan(steps, args);
+		if (JSON.stringify(next) !== JSON.stringify(steps)) {
+			steps = next; version += 1;
+			// a failing view never fails the call
+			try { emit?.({ type: "plan.update", steps }); } catch { /* advisory */ }
+		}
+		return { ok: true, plan: steps };
+	};
+	const tool = { name: "plan", label: "Plan", description: DESCRIPTION, parameters: PARAMETERS, handler: async args => apply(args) };
+	return {
+		...tool,
+		nested: { ...tool, quiet: true, handler: async args => {
+			try { return apply(args); } catch (error) {
+				refused.push(error.message);
+				return { ok: false, code: error.code ?? "INVALID_ARGUMENT", message: error.message };
+			}
+		} },
+		track: inner => ({ ...inner, handler: async (...args) => {
+			const seen = version, result = await inner.handler(...args);
+			const notes = refused.splice(0);
+			if (!isRecord(result) || (seen === version && !notes.length)) return result;
+			return { ...result, ...(seen === version ? {} : { plan: steps }), ...(notes.length ? { planRefused: notes } : {}) };
+		} }),
+	};
+}

package/bin/agent/script-tool.mjs

@@ -59,6 +59,8 @@ export function createScriptTool({ tools = [], signal, emit: createdEmit } = {})
 					name: tool.name,
 					description: tool.description,
 					execute: async (args, { signal: nestedSignal }) => {
+						// A quiet tool (plan-tool.mjs) is the panel's own business: no progress frame, no line in the calls summary.
+						if (tool.quiet) return publicData(await tool.handler(args ?? {}, {}));
 						const signals = [nestedSignal, runSignal].filter(Boolean), index = ++started;
 						let result;
 						report(index, tool.name, args, "running");

package/bin/agent/sculpt-sketch.mjs

@@ -0,0 +1,190 @@
+// The live sketch: while the model is still writing a tool call that builds sculpts, the parts it has written so
+// far go to the browser as `sculpt.sketch` frames, which the viewport draws as translucent ghost clay
+// (src/sculpt-sketch.jsx). A `script` call is cut to its longest runnable prefix (sketch-code.mjs) and dry-run with
+// stub tools in a throwaway sandbox (sketch-sandbox.mjs); a direct run_action object.sculpt call is read from pi-ai's
+// partially parsed arguments. A model writing an 8 KB script spends minutes on it; without this the stage stays
+// empty until it runs. Frames only: nothing here reaches the model or the scene, and a failed sketch is no sketch.
+import { declaredNames, runnablePrefix, streamedCode } from "./sketch-code.mjs";
+import { dryRunSketch, SKETCH_MAX_PARTS } from "./sketch-sandbox.mjs";
+
+/** How often a streaming call is sketched again, at most. */
+const SKETCH_MS = 600;
+/** Dry runs in flight across the sidecar: a sketch never competes with the turn for the machine. */
+const MAX_RUNNING = 2;
+const MAX_FRAME_CHARS = 48 * 1024;
+const MAX_GROUPS = 16;
+const MAX_RAW_CHARS = 512 * 1024;
+const COLOR = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+let running = 0;
+let sculptShapes = null;
+// Lazy, like every src/ import of the sidecar: the shapes are read only once a call is sketched.
+const loadShapes = () => (sculptShapes ??= import("../../src/sculpt-shapes.js")
+	.then((module) => ({ shapes: module.SCULPT_SHAPES, keys: module.SCULPT_SHAPE_KEYS }), () => null));
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const tidy = (value) => Math.round(value * 1e4) / 1e4;
+const text = (value, max) => (typeof value === "string" && value.trim() ? value.trim().slice(0, max) : undefined);
+
+/** [x, y, z] from an array of three numbers or an { x, y, z } object (a missing axis is 0), else null. */
+function vector(value) {
+	if (Array.isArray(value)) return value.length === 3 && value.every(finite) ? value.map(tidy) : null;
+	if (!value || typeof value !== "object") return null;
+	const axes = [value.x, value.y, value.z];
+	return axes.some(finite) && axes.every((axis) => axis === undefined || finite(axis)) ? axes.map((axis) => tidy(axis ?? 0)) : null;
+}
+
+/** A part id the recipe accepts ("wheelF" -> "wheel-f"), or "" when nothing is left of it. */
+const sketchId = (value) => typeof value !== "string" ? "" : value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
+	.replace(/[^a-z0-9-]+/g, "-").replace(/^-+/, "").slice(0, 40);
+
+/** A shape field cut to what a ghost needs: numbers rounded, strings and arrays capped, four levels deep. */
+function plain(value, depth = 0) {
+	if (finite(value)) return tidy(value);
+	if (typeof value === "string") return value.slice(0, 40);
+	if (typeof value === "boolean") return value;
+	if (depth > 3 || !value || typeof value !== "object") return undefined;
+	if (Array.isArray(value)) return value.slice(0, 256).map((entry) => plain(entry, depth + 1) ?? null);
+	return Object.fromEntries(Object.entries(value).slice(0, 16).map(([key, entry]) => [key, plain(entry, depth + 1)]).filter(([, entry]) => entry !== undefined));
+}
+
+/** One part as a ghost draws it: geometry, place and colour; looks (material, detail, gradient) stay out, cutters too. */
+function sketchPart(raw, fallbackId, { shapes, keys }) {
+	if (!raw || typeof raw !== "object" || !shapes.includes(raw.shape) || raw.op) return null;
+	const size = vector(raw.size);
+	if (!size) return null;
+	const part = { id: sketchId(raw.id) || fallbackId, shape: raw.shape, size };
+	const position = vector(raw.position), rotation = vector(raw.rotation), parent = sketchId(raw.parent);
+	if (position) part.position = position;
+	if (rotation) part.rotation = rotation;
+	if (typeof raw.color === "string" && COLOR.test(raw.color.trim())) part.color = raw.color.trim();
+	if (parent) part.parent = parent;
+	if (raw.mirror === true) part.mirror = true;
+	for (const key of keys) {
+		const value = plain(raw[key]);
+		if (value !== undefined) part[key] = value;
+	}
+	return part;
+}
+
+/**
+ * sculptSketchGroups(value, env) -> [{ key, name?, target?, placement?, parts }]: the dry run's (or a direct call's)
+ * groups, loosely normalized and capped at SKETCH_MAX_PARTS parts and MAX_FRAME_CHARS of JSON (the last parts go
+ * first). `target` is the sculpt an object.sculpt { id } call rebuilds; `placement` keeps { x, y, z, rot } numbers.
+ */
+export function sculptSketchGroups(value, env) {
+	const groups = [], keys = new Set();
+	let count = 0;
+	for (const raw of (Array.isArray(value?.groups) ? value.groups : []).slice(0, MAX_GROUPS)) {
+		const parts = [], ids = new Set();
+		for (const entry of Array.isArray(raw?.parts) ? raw.parts : []) {
+			if (count >= SKETCH_MAX_PARTS) break;
+			const part = sketchPart(entry, `part-${count}`, env);
+			if (!part) continue;
+			for (let n = 2; ids.has(part.id); n += 1) part.id = `${part.id.replace(/-\d+$/, "").slice(0, 36)}-${n}`;
+			ids.add(part.id);
+			parts.push(part);
+			count += 1;
+		}
+		if (!parts.length) continue;
+		let key = text(raw.key, 16) ?? `g${groups.length}`;
+		while (keys.has(key)) key += "+";
+		keys.add(key);
+		const placement = Object.fromEntries(["x", "y", "z", "rot"].filter((axis) => finite(raw.placement?.[axis])).map((axis) => [axis, tidy(raw.placement[axis])]));
+		const name = text(raw.name, 80), target = text(raw.id, 80);
+		groups.push({ key, ...(name ? { name } : {}), ...(target ? { target } : {}), ...(Object.keys(placement).length ? { placement } : {}), parts });
+	}
+	while (groups.length && JSON.stringify(groups).length > MAX_FRAME_CHARS) {
+		const last = groups.at(-1);
+		last.parts.splice(Math.floor(last.parts.length * 0.8));
+		if (!last.parts.length) groups.pop();
+	}
+	return groups;
+}
+
+/** The groups a script's code shows so far: its longest runnable cut, dry-run. Undefined when there is nothing new. */
+async function scriptGroups(state, env) {
+	const code = streamedCode(state.call, state.raw);
+	// The code only grows while it streams; anything else starts the cut over.
+	if (state.cut && !code.startsWith(state.cutText)) state.cut = null;
+	const cut = runnablePrefix(code, { after: state.cut?.end ?? 0, whole: state.complete }) ?? state.cut;
+	if (!cut || cut.source === state.ran) return undefined;
+	Object.assign(state, { cut, cutText: code.slice(0, cut.end), ran: cut.source });
+	const value = await dryRunSketch(cut.source, declaredNames(cut.source), env);
+	return value ? sculptSketchGroups(value, env) : undefined;
+}
+
+/** The groups a direct run_action object.sculpt call shows so far; while it streams, its last part may be half written. */
+function directGroups(state, env) {
+	const args = state.call.arguments;
+	if (args?.action !== "object.sculpt") return undefined;
+	const inner = args.args ?? {}, parts = Array.isArray(inner.recipe?.parts) ? inner.recipe.parts : [];
+	return sculptSketchGroups({ groups: [{ key: "d", name: inner.name, id: inner.id, placement: inner.placement, parts: state.complete ? parts : parts.slice(0, -1) }] }, env);
+}
+
+/**
+ * createSculptSketch(push, clock) -> { onMessageEvent(event), settled() }. onMessageEvent takes pi's assistant
+ * message events, like turn-frames.mjs; push gets { type: "sculpt.sketch", index, callId?, groups } whenever what a
+ * `script` or run_action call has written so far changes, at most every SKETCH_MS while it streams and once more
+ * when it is complete, and with empty groups when its message fails or ends without running its tools. The browser
+ * drops a call's sketch when its tool.done arrives. settled() resolves once no sketch is running (tests).
+ */
+export function createSculptSketch(push, clock = () => Date.now()) {
+	const calls = new Map();
+	const send = (state, groups) => {
+		const json = JSON.stringify(groups);
+		if (state.closed || json === (state.sent ?? "[]")) return;
+		state.sent = json;
+		try { push({ type: "sculpt.sketch", index: state.index, ...(state.callId ? { callId: state.callId } : {}), groups }); } catch { /* advisory */ }
+	};
+	const clearAll = () => {
+		for (const state of calls.values()) { send(state, []); state.closed = true; }
+		calls.clear();
+	};
+	const schedule = (state) => {
+		if (state.closed) return;
+		if (state.running) { state.again ||= state.complete; return; }
+		if (!state.complete && (clock() - state.at < SKETCH_MS || running >= MAX_RUNNING)) return;
+		state.at = clock();
+		running += 1;
+		state.running = (async () => {
+			const env = await loadShapes();
+			if (!env || state.closed) return;
+			const groups = state.kind === "script" ? await scriptGroups(state, env) : directGroups(state, env);
+			if (groups) send(state, groups);
+		})().catch(() => { /* a failed sketch is no sketch */ }).finally(() => {
+			running -= 1;
+			state.running = null;
+			if (state.again) { state.again = false; schedule(state); }
+		});
+	};
+	const onEvent = (event) => {
+		const type = event?.type;
+		if (type === "error" || (type === "done" && event.reason !== "toolUse")) { clearAll(); return; }
+		if (type !== "toolcall_start" && type !== "toolcall_delta" && type !== "toolcall_end") return;
+		const call = (type === "toolcall_end" && event.toolCall) || event.partial?.content?.[event.contentIndex];
+		if (call?.type !== "toolCall" || (call.name !== "script" && call.name !== "run_action")) return;
+		// contentIndex restarts with every assistant message, so a start begins a new call
+		let state = type === "toolcall_start" ? null : calls.get(event.contentIndex);
+		if (!state || state.kind !== call.name) {
+			// The call this one replaces at its index is over: a sketch of it still running sends nothing.
+			if (calls.has(event.contentIndex)) calls.get(event.contentIndex).closed = true;
+			state = { index: event.contentIndex, kind: call.name, callId: typeof call.id === "string" && call.id ? call.id : null, raw: "", at: clock() };
+			calls.set(event.contentIndex, state);
+		}
+		state.call = call;
+		// A provider that names the call only at its end: later frames carry the id (the browser drops the index-keyed one).
+		if (!state.callId && typeof call.id === "string" && call.id) state.callId = call.id;
+		if (type === "toolcall_delta" && typeof call.arguments?.code !== "string" && state.raw.length < MAX_RAW_CHARS) state.raw += event.delta ?? "";
+		if (type === "toolcall_end") state.complete = true;
+		schedule(state);
+	};
+	return {
+		onMessageEvent(event) {
+			try { onEvent(event); } catch { /* a sketch never stops a turn */ }
+		},
+		async settled() {
+			while ([...calls.values()].some((state) => state.running)) await Promise.all([...calls.values()].map((state) => state.running));
+		},
+	};
+}

package/bin/agent/session-store.mjs

@@ -347,7 +347,8 @@ export function transcriptFromHistory(history = []) {
 		}
 		if (item?.role === "toolResult") {
 			const tool = piCalls.get(item.toolCallId);
-			if (tool) tool.ok = !item.isError;
+			// A result the turn's plan changed in carries the whole list (plan-tool.mjs); the panel keeps its turn's last one.
+			if (tool) tool.ok = !item.isError; if (Array.isArray(item.details?.plan)) transcript.push({ kind: "plan", steps: item.details.plan });
 			const receiptId = item.details?.receiptId;
 			if (receiptId && !seenReceiptIds.has(receiptId)) {
 				seenReceiptIds.add(receiptId);

package/bin/agent/sketch-code.mjs

@@ -0,0 +1,151 @@
+// The runnable part of a `script` the model is still writing, for the live sketch (sculpt-sketch.mjs): the code
+// streamed so far, cut back to the longest stretch of whole lines that compiles once its open brackets are closed.
+// Compile only: node:vm's Script parses the text and never runs it here; the cut then runs in a throwaway sandbox
+// with stub tools (sketch-sandbox.mjs).
+import { Script } from "node:vm";
+
+/** Line ends tried per pass, newest first; a long statement still being written fails them all and the last good cut stays. */
+const MAX_CUTS = 48;
+const ESCAPES = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", v: "\v", 0: "\0" };
+const OPENERS = { "{": "}", "(": ")", "[": "]" };
+// After one of these a `/` starts a regex literal; after a value it divides.
+const REGEX_AFTER = /(?:^|[(,=:[!&|?{};+\-*%<>~^])$/;
+const REGEX_WORDS = new Set(["return", "typeof", "case", "do", "else", "in", "of", "void", "delete", "throw", "new", "await", "yield"]);
+const DECLARED = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=|,\s*([A-Za-z_$][\w$]*)\s*=\s*[[{]/g;
+
+/** A JSON string body decoded up to its closing quote, or up to the last whole character while it is still streaming. */
+function decodeStreamed(body) {
+	let out = "";
+	for (let at = 0; at < body.length; at += 1) {
+		const char = body[at];
+		if (char === "\"") return out;
+		if (char !== "\\") { out += char; continue; }
+		const next = body[at + 1];
+		if (next === undefined) return out;
+		if (next === "u") {
+			const hex = body.slice(at + 2, at + 6);
+			if (!/^[0-9a-fA-F]{4}$/.test(hex)) return out;
+			out += String.fromCharCode(parseInt(hex, 16));
+			at += 5;
+			continue;
+		}
+		out += ESCAPES[next] ?? next;
+		at += 1;
+	}
+	return out;
+}
+
+/** The script's code so far: pi-ai's partially parsed arguments when the provider fills them, else the raw argument JSON. */
+export function streamedCode(call, raw = "") {
+	if (typeof call?.arguments?.code === "string") return call.arguments.code;
+	const start = /"code"\s*:\s*"/.exec(raw);
+	return start ? decodeStreamed(raw.slice(start.index + start[0].length)) : "";
+}
+
+/** Where a template literal's text ends from `at`: { at, open } (open: a `${` expression starts), or null at the end of the text. */
+function templateEnd(code, at) {
+	for (let index = at; index < code.length; index += 1) {
+		if (code[index] === "\\") index += 1;
+		else if (code[index] === "`") return { at: index, open: false };
+		else if (code[index] === "$" && code[index + 1] === "{") return { at: index + 1, open: true };
+	}
+	return null;
+}
+
+/** The index of a regex literal's last flag from its opening `/`, or -1 when the line ends first (then it was a division). */
+function regexEnd(code, at) {
+	let inClass = false;
+	for (let index = at + 1; index < code.length; index += 1) {
+		const char = code[index];
+		if (char === "\n") return -1;
+		if (char === "\\") index += 1;
+		else if (char === "[") inClass = true;
+		else if (char === "]") inClass = false;
+		else if (char === "/" && !inClass) {
+			while (/[a-z]/i.test(code[index + 1] ?? "")) index += 1;
+			return index;
+		}
+	}
+	return -1;
+}
+
+/**
+ * scanCode(code) -> { close, declarations } | null. close: the text that closes every bracket `code` leaves open (a
+ * `try {` gets an empty catch, an open template expression its backquote); declarations: where a `const` or `let`
+ * starts a statement outside every bracket. Null when the code ends inside a string, template text or block
+ * comment. A heuristic: the compile check that follows is the judge.
+ */
+export function scanCode(code) {
+	const stack = [], declarations = [];
+	let last = "", word = "", gap = false;
+	for (let at = 0; at < code.length; at += 1) {
+		const char = code[at];
+		if (/\s/.test(char)) {
+			if (!gap && !stack.length && (word === "const" || word === "let") && code[at - word.length - 1] !== ".") declarations.push(at - word.length);
+			gap = true;
+			continue;
+		}
+		if (char === "/" && code[at + 1] === "/") { const end = code.indexOf("\n", at); if (end < 0) break; at = end; continue; }
+		if (char === "/" && code[at + 1] === "*") { const end = code.indexOf("*/", at + 2); if (end < 0) return null; at = end + 1; continue; }
+		if (char === "\"" || char === "'") {
+			let end = at + 1;
+			for (; end < code.length && code[end] !== char && code[end] !== "\n"; end += 1) if (code[end] === "\\") end += 1;
+			if (code[end] !== char) return null;
+			at = end; last = char; word = ""; gap = false;
+			continue;
+		}
+		const closesTemplate = char === "}" && stack.at(-1) === "}`";
+		if (char === "`" || closesTemplate) {
+			if (closesTemplate) stack.pop();
+			const end = templateEnd(code, at + 1);
+			if (!end) return null;
+			if (end.open) stack.push("}`");
+			at = end.at; last = "`"; word = ""; gap = false;
+			continue;
+		}
+		if (char === "/" && (REGEX_AFTER.test(last) || REGEX_WORDS.has(word))) {
+			const end = regexEnd(code, at);
+			if (end > 0) { at = end; last = "/"; word = ""; gap = false; continue; }
+		}
+		if (OPENERS[char]) stack.push(char === "{" && word === "try" ? "}catch{}" : OPENERS[char]);
+		else if ("})]".includes(char) && stack.at(-1)?.[0] === char) stack.pop();
+		word = /[\w$]/.test(char) ? (!gap && /[\w$]/.test(last) ? word : "") + char : "";
+		last = char; gap = false;
+	}
+	return { close: stack.reverse().join(""), declarations };
+}
+
+/** Whether `text` parses as the body codemode runs it as (an async function), inside the try block the sketch wraps it in. */
+function compiles(text) {
+	try { new Script(`(async (tools, console) => { try {\n${text}\n} finally {} })`); return true; } catch { return false; }
+}
+
+/** `text` with its top-level `const`/`let` turned into `var` (padded to the same length), so the sketch's finally
+ * block still sees what the cut declared when a later line threw. */
+const hoisted = (text, declarations) => declarations.reduceRight((out, at) => `${out.slice(0, at)}${out.startsWith("const", at) ? "var  " : "var"}${out.slice(at + (out.startsWith("const", at) ? 5 : 3))}`, text);
+
+/**
+ * runnablePrefix(code, { after = 0, whole = false }) -> { end, source } | null: the longest cut of `code` at a line
+ * end past `after` (or all of it, when `whole`: the call is complete) whose text compiles with its open brackets
+ * closed. A cut inside a line could hold half a number, so a streaming call is cut at line ends only. `source` is
+ * that text, hoisted, plus its closers.
+ */
+export function runnablePrefix(code, { after = 0, whole = false } = {}) {
+	const cuts = whole ? [code.length] : [];
+	for (let at = code.lastIndexOf("\n"); at > after && cuts.length < MAX_CUTS; at = code.lastIndexOf("\n", at - 1)) cuts.push(at);
+	for (const end of cuts) {
+		const text = code.slice(0, end), scanned = scanCode(text);
+		if (!scanned || !text.trim()) continue;
+		const body = hoisted(text, scanned.declarations);
+		if (compiles(`${body}\n${scanned.close}`)) return { end, source: `${body}\n${scanned.close}` };
+		if (scanned.close && compiles(body)) return { end, source: body };
+	}
+	return null;
+}
+
+/** The names `source` declares (`var S = [`, `, D = [`), whose arrays of parts the sandbox looks at once the cut has run. */
+export function declaredNames(source) {
+	const names = new Set();
+	for (const match of source.matchAll(DECLARED)) if (names.size < 40) names.add(match[1] ?? match[2]);
+	return [...names].filter((name) => !name.startsWith("__cozy"));
+}