cozyclay 3.0.3 → 3.1.1

package/src/workflow/TaskInline.jsx

@@ -0,0 +1,114 @@
+// Task mode inside the chat (task-board.js; the headless TaskBoard.jsx feeds taskView). A task is one quiet line
+// under the turn that dispatched it; a status line under the header counts them; a line opens the task's own view
+// (its steps, cost, cancel / undo, and an input that talks to that task only), and the chat is one click back.
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { FiChevronDown, FiChevronLeft } from "react-icons/fi";
+import { ko } from "../locale.js";
+import { ACTIVE_STATUSES, TASK_STATUS_COPY, boardGroups, compileState, costLabel, dispatchedTaskIds, progressLine, scopeLabel, taskLine, taskReason, taskView } from "./task-board.js";
+import "./task-board.css";
+export { readStoredTaskMode, storeTaskMode } from "./task-board.js";
+
+const useTaskView = () => useSyncExternalStore(taskView.subscribe, taskView.get, taskView.get);
+const openTask = taskId => taskView.set({ open: taskId });
+
+function TaskRow({ task, activity }) {
+	const line = task.status === "running" && compileState(activity, task.taskId).waiting > 0 ? ko("Compile waits for a free worker", "컴파일 차례 기다리는 중") : taskLine(task);
+	const status = TASK_STATUS_COPY[task.status] ?? task.status;
+	return <button type="button" className="task-row" data-status={task.status} data-task-id={task.taskId} onClick={() => openTask(task.taskId)}
+		title={`${task.title} — ${line}`} aria-label={`${task.title}, ${status}: ${line}`}>
+		<span className="task-dot" aria-hidden="true" />
+		<span className="task-row-title">{task.title}</span>
+		<span className="task-row-line">{line}</span>
+	</button>;
+}
+
+/** The tasks a turn dispatched (`steps`), or with `items` every task no turn in the chat dispatched (a restored chat). */
+export function TaskRows({ steps, items }) {
+	const { board, activity } = useTaskView();
+	const placed = items ? new Set(dispatchedTaskIds(items)) : null;
+	const ids = placed ? board.order.filter(id => !placed.has(id)) : [...new Set(dispatchedTaskIds(steps))].filter(id => board.tasks[id]);
+	if (!ids.length) return null;
+	return <div className="task-rows">{ids.map(id => <TaskRow key={id} task={board.tasks[id]} activity={activity} />)}</div>;
+}
+
+const GROUPS = [["failed", ko("need a look", "확인 필요")], ["running", ko("running", "실행 중")], ["waiting", ko("waiting", "대기")], ["done", ko("done", "완료")]];
+
+export function TaskStrip() {
+	const { board, activity } = useTaskView();
+	const [expanded, setExpanded] = useState(false);
+	if (!board.order.length) return null;
+	const groups = boardGroups(board);
+	const shown = GROUPS.filter(([key]) => groups[key].length);
+	return <div className="task-strip" data-expanded={expanded ? "true" : "false"}>
+		<button type="button" className="task-strip-head" aria-expanded={expanded} onClick={() => setExpanded(value => !value)}>
+			{shown.map(([key, label]) => <span key={key} className="task-strip-count" data-status={key}><span className="task-dot" aria-hidden="true" />{groups[key].length} {label}</span>)}
+			<FiChevronDown className="task-strip-caret" size={12} aria-hidden="true" />
+		</button>
+		{expanded && <div className="task-rows task-strip-list">{shown.flatMap(([key]) => groups[key]).map(task => <TaskRow key={task.taskId} task={task} activity={activity} />)}</div>}
+	</div>;
+}
+
+function TaskFrames({ client, turnId, labelOf }) {
+	const [lines, setLines] = useState([]);
+	useEffect(() => {
+		if (!turnId || !client) return undefined;
+		const controller = new AbortController();
+		let reply = "";
+		client.frames(turnId, frame => {
+			if (frame.type === "text.delta") { reply += frame.text ?? ""; setLines(list => [...list.filter(line => line.kind !== "reply"), { kind: "reply", text: reply }]); return; }
+			const label = frame.type === "tool.done" ? null : progressLine(frame, labelOf);
+			if (frame.type === "tool.start") reply = "";
+			if (label) setLines(list => [...list.filter(line => line.kind !== "reply"), ...(reply ? [{ kind: "said", text: reply }] : []), { kind: frame.type === "error" ? "error" : "tool", text: label }].slice(-40));
+		}, controller.signal).catch(() => {});
+		return () => controller.abort();
+	}, [client, turnId, labelOf]);
+	if (!lines.length) return <p className="task-frames-empty">{ko("No steps yet.", "아직 단계가 없어요.")}</p>;
+	return <ol className="task-frames">{lines.map((line, index) => <li key={index} data-kind={line.kind}>{line.text}</li>)}</ol>;
+}
+
+export function TaskDetail() {
+	const { board, open, client, undo, labelOf } = useTaskView();
+	const task = open ? board.tasks[open] : null;
+	return task ? <OpenTask key={task.taskId} task={task} client={client} undo={undo} labelOf={labelOf} /> : null;
+}
+
+function OpenTask({ task, client, undo, labelOf }) {
+	const [notice, setNotice] = useState("");
+	const [steering, setSteering] = useState("");
+	useEffect(() => {
+		const onKey = event => { if (event.key === "Escape") openTask(null); };
+		window.addEventListener("keydown", onKey);
+		return () => window.removeEventListener("keydown", onKey);
+	}, []);
+	const active = ACTIVE_STATUSES.has(task.status);
+	const cost = costLabel(task.usage);
+	const act = async (run, done) => { setNotice(""); try { await run(); setNotice(done); } catch (error) { setNotice(String(error?.message ?? error)); } };
+	const steer = event => {
+		event.preventDefault();
+		const text = steering.trim();
+		if (text) act(() => client.steer(task.taskId, text), ko("Sent to this task.", "이 작업에 전달함.")).then(() => setSteering(""));
+	};
+	return <section className="task-detail" data-status={task.status} data-task-id={task.taskId} aria-label={task.title}>
+		<header className="task-detail-head">
+			<button type="button" className="agent-ghost-button task-detail-back" onClick={() => openTask(null)} autoFocus><FiChevronLeft size={13} aria-hidden="true" />{ko("Chat", "대화")}</button>
+			<span className="task-detail-title">{task.title}</span>
+		</header>
+		<div className="task-detail-body">
+			<div className="task-detail-meta" data-status={task.status}>
+				<span className="task-dot" aria-hidden="true" />
+				<span>{TASK_STATUS_COPY[task.status] ?? task.status}{cost ? ` · ${cost}` : ""}</span>
+				{active && <button type="button" className="agent-ghost-button task-detail-cancel" onClick={() => act(() => client.cancel(task.taskId), ko("Cancelled; its changes go back.", "취소함: 바뀐 것은 되돌아가요."))}>{ko("Cancel", "취소")}</button>}
+				{task.status === "done" && !task.undone && <button type="button" className="agent-ghost-button task-detail-undo" onClick={() => act(() => undo(task.taskId), ko("Undone.", "되돌림."))}>{ko("Undo task", "작업 되돌리기")}</button>}
+			</div>
+			{task.scope?.length > 0 && <p className="task-detail-scope" title={task.scope.join(", ")}>{ko("Touches", "건드리는 것")}: {[...new Set(task.scope.map(scopeLabel))].join(" · ")}</p>}
+			{task.reason && task.status !== "done" && <p className="task-detail-reason">{taskReason(task.reason)}</p>}
+			{task.notes?.map((text, index) => <p key={index} className="task-detail-note">{text}</p>)}
+			{task.summary?.reply && !active && <p className="task-detail-summary">{task.summary.reply}</p>}
+			<TaskFrames key={task.turnId} client={client} turnId={task.turnId} labelOf={labelOf} />
+			{notice && <p className="task-detail-notice" role="status">{notice}</p>}
+		</div>
+		{task.status === "running" && <form className="task-detail-steer" onSubmit={steer}>
+			<input value={steering} onChange={event => setSteering(event.target.value)} placeholder={ko("Tell this task…", "이 작업에게 지시…")} aria-label={ko("Tell this task", "이 작업에게 지시")} />
+		</form>}
+	</section>;
+}

package/src/workflow/agent-client.js

@@ -28,8 +28,9 @@ import { appendAttachments, ATTACHMENT_MAX_COUNT } from "./attachment-image.js";
 import { ko } from "../locale.js";
 import { AGENT_TOOL_CATEGORIES, EXECUTION_TELEMETRY_VALUES } from "../execution-telemetry.js";
 import { STUDIO_VARIANTS, validateReceipt } from "../studio-agent-protocol.js";
-import { requestAgentImage, sidecarRequest, sidecarUrl } from "../agent-image-client.js";
+import { requestAgentImage, sidecarRequest, sidecarUrl } from "../agent-image-client.js"; import { clearSculptSketch, sculptSketchFrame } from "../sculpt-sketch-state.js";
 import { actionLabelsOf, changedLine, scriptNow, stepFields, thinkingLine, withCompose, withThinking, withToolStart, withTurnEnd } from "./agent-turn.js";
+import { isPlanFrame, restoredPlans, withPlanEnd, withPlanFrame } from "./agent-plan.js";
 
 const AGENT_PANEL_WIDTH_KEY = "cozyclay.workflow.agentPanel.width";
 export const AGENT_PANEL_WIDTH_DEFAULT = 360;
@@ -266,27 +267,6 @@ export function storeModel(key, storage = globalThis.localStorage) {
 	}
 }
 
-/** The supervisor switch (#728): off unless the author turned it on. It rides
- * on every Studio turn as `supervisor: true|false`; the sidecar reviews only a
- * turn sent with `true`, and its own COZYCLAY_SUPERVISOR=off still wins. */
-const AGENT_SUPERVISOR_KEY = "cozyclay.agent.supervisor";
-
-export function readStoredSupervisor(storage = globalThis.localStorage) {
-	try {
-		return storage?.getItem(AGENT_SUPERVISOR_KEY) === "on";
-	} catch {
-		return false;
-	}
-}
-
-export function storeSupervisor(enabled, storage = globalThis.localStorage) {
-	try {
-		storage?.setItem(AGENT_SUPERVISOR_KEY, enabled ? "on" : "off");
-	} catch {
-		// Private-mode storage denial must never break the toggle.
-	}
-}
-
 /** The model to open with: the remembered key when it is still advertised,
  * otherwise the first model the sidecar listed. */
 export function preferredModel(models, stored = readStoredModel()) {
@@ -653,6 +633,10 @@ export function keyRefusedMessage(raw) {
 	return `The model provider refused the credentials${status || reason ? ` (${[status, reason].filter(Boolean).join(": ")})` : ""}.`;
 }
 
+/** True when the agent server itself did not answer: plain `vite` without the sidecar (503/502/404), a dead
+ * port (network error, no status), or an HTML fallback where JSON was expected. Any other status is the server's own answer. */
+export const agentServerUnavailable = (error) => !Number.isFinite(error?.status) || [404, 502, 503].includes(error.status);
+
 export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalThis), surface, capture = track, now = () => performance.now() } = {}) {
 	const activeTurns = new Map();
 	const request = (path, init) => sidecarRequest(fetchImpl, path, init);
@@ -744,7 +728,7 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 		},
 		/** Streams sidecar events to `onEvent`. Resolves when the turn ends. */
 		async turn(turnRequest, onEvent, signal) {
-			const { sessionId, text, attachFrame, model, effort, attachments, supervisor } = turnRequest;
+			const { sessionId, text, attachFrame, model, effort, attachments, supervisor, tasks } = turnRequest;
 			const attached = Array.isArray(attachments) && attachments.length ? { attachments } : {};
 			const studio = turnRequest.surface === "studio";
 			const turnId = studio ? turnRequest.turnId : null;
@@ -803,9 +787,10 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 				})
 				: JSON.stringify({ sessionId, text, attachFrame, model, ...(effort ? { effort } : {}), ...attached, ...(telemetry.turnId ? { turn_id: telemetry.turnId } : {}) });
 			try {
-				const response = await fetchImpl(sidecarUrl("/agent/turn"), {
+				// Task mode (the panel's Tasks switch): the turn goes to the main agent, which answers at once and runs tasks.
+				const response = await fetchImpl(sidecarUrl(studio && tasks ? "/agent/main" : "/agent/turn"), {
 					method: "POST",
-					headers: { "content-type": "application/json", accept: "text/event-stream" },
+					headers: { "content-type": "application/json", accept: "text/event-stream", ...(studio && tasks ? { "x-cozyclay-tasks": "on" } : {}) },
 					body,
 					signal,
 				});
@@ -1341,6 +1326,8 @@ export function createAgentChatStore({
 			});
 			return;
 		}
+		// The turn's step checklist (bin/agent/plan-tool.mjs): one card under the prompt; the plan call itself is no step.
+		if (isPlanFrame(event)) { setItems((items) => withPlanFrame(items, event, newId)); return; }
 		if (event?.type === "tool.start") {
 			setItems((items) => withToolStart(items, { kind: "tool", id: event.callId || newId(), callId: event.callId, name: event.name, label: event.label, args: event.args, status: "running", startedAt: clock(), ...stepFields(event.name, event.args, actionLabels) }));
 			return;
@@ -1422,11 +1409,10 @@ export function createAgentChatStore({
 		set({ sessionId: newId(), turnId: null, items: [], pendingAttachments: [], rateLimit: null, lastPrompt: "", turnStartedAt: null, lastTurn: null });
 	};
 	const restore = (transcript, sessionId = state.sessionId) => {
-		abandonSupervisorNotes();
-		seenReceipts.clear();
-		settledActions.clear();
+		abandonSupervisorNotes(); seenReceipts.clear(); settledActions.clear();
 		const restoredReceiptIds = new Set();
-		const restored = (Array.isArray(transcript) ? transcript : []).flatMap((item) => {
+		// Each turn's plan card comes back under its prompt, settled by how the turn ended (agent-plan.js).
+		const restored = restoredPlans((Array.isArray(transcript) ? transcript : []).flatMap((item) => {
 			if (item?.kind === "user" || item?.kind === "assistant") {
 				const attachments = Array.isArray(item.attachments) ? item.attachments.filter((entry) => typeof entry?.dataUrl === "string") : [];
 				return [{ kind: item.kind, id: newId(), text: String(item.text ?? ""), ...(attachments.length ? { attachments } : {}) }];
@@ -1441,8 +1427,8 @@ export function createAgentChatStore({
 				return [{ kind: "receipt", id: `receipt:${item.receiptId || newId()}`, receiptId: item.receiptId, summary: item.summary || "Receipt", receipt: { status: "applied", warnings: [], verification: { status: "verified" } } }];
 			}
 			if (item?.kind === "failure") return [{ kind: "failure", id: newId(), failure: { code: item.code || "upstream", message: String(item.message || "The turn failed."), recovery: { action: "retry", retryAllowed: true } } }];
-			return [];
-		});
+			return item?.kind === "plan" ? [{ kind: "plan", id: newId(), steps: item.steps }] : [];
+		}));
 		const lastPrompt = [...restored].reverse().find((item) => item.kind === "user")?.text || "";
 		set({ sessionId, turnId: null, items: restored, rateLimit: null, lastPrompt, turnStartedAt: null, lastTurn: null, streaming: false });
 		return restored;
@@ -1454,6 +1440,8 @@ export function createAgentChatStore({
 			return () => listeners.delete(listener);
 		},
 		setDraft: (draft) => set({ draft: String(draft ?? "") }),
+		/** A reply the main agent made on its own (task mode: a task ended while nobody was talking to it). */
+		note: (text) => { if (String(text ?? "").trim()) set({ items: [...state.items, { kind: "assistant", id: newId(), text: String(text) }] }); },
 		/** Pictures pasted or dropped into the composer. Returns what was taken and
 		 * what had to be refused, so the composer can say so instead of a picture
 		 * vanishing on its way in. */
@@ -1511,15 +1499,16 @@ export function createAgentChatStore({
 					attachFrame: Boolean(options.attachFrame),
 					model: options.model,
 					effort: options.effort ?? undefined,
-					...(typeof options.supervisor === "boolean" ? { supervisor: options.supervisor } : {}),
-				}, applyEvent, signal);
+					...(typeof options.supervisor === "boolean" ? { supervisor: options.supervisor } : {}), ...(options.tasks ? { tasks: true } : {}),
+				}, (event) => { sculptSketchFrame(event); applyEvent(event); }, signal);
 			} catch (error) {
 				if (!signal.aborted) applyEvent({ type: "error", code: "upstream", message: String(error?.message || error) });
 			} finally {
 				if (controller?.signal === signal) controller = null;
-				// A turn the author already replaced owns none of this state.
+				// A turn the author already replaced owns none of this state. Its live sculpt sketch
+				// (the ghost clay of a call still being written) ends with it, whatever ended it.
 				if (activeTurn === turn) {
-					wireTurnId = null;
+					wireTurnId = null; clearSculptSketch();
 					// Ending with nothing on screen is a failure, not a result.
 					if (!turn.produced && !turn.failure && !signal.aborted) {
 						turn.failure = { code: "no_output", message: "The turn ended without a response.", recovery: { action: "retry", retryAllowed: true } };
@@ -1529,7 +1518,7 @@ export function createAgentChatStore({
 					activeTurn = null;
 					// The end state stays in the transcript with the turn's steps (agent-turn.js withTurnEnd).
 					const lastTurn = { status: signal.aborted ? "stopped" : turn.failure ? "failed" : "done", endedAt, durationMs: endedAt - startedAt, failure: turn.failure };
-					set({ streaming: false, turnStartedAt: null, lastTurn, items: withTurnEnd(state.items, lastTurn, newId) });
+					set({ streaming: false, turnStartedAt: null, lastTurn, items: withPlanEnd(withTurnEnd(state.items, lastTurn, newId), lastTurn.status) });
 					if (studio && turn.reviewable && options.supervisor === true && !signal.aborted) requestSupervisorNote(turnId);
 				}
 			}

package/src/workflow/agent-panel.css

@@ -287,7 +287,8 @@
 	cursor: pointer;
 }
 
-.agent-menu button:hover { background: var(--agent-hover, #2b3040); color: var(--agent-text-strong, #f5f7ff); }
+.agent-menu button[disabled] { opacity: 0.45; cursor: not-allowed; }
+.agent-menu button:not([disabled]):hover { background: var(--agent-hover, #2b3040); color: var(--agent-text-strong, #f5f7ff); }
 
 /* --- account strip ----------------------------------------------------- */
 
@@ -869,6 +870,18 @@
 /* The second way in on the signed-out card: a key or a server of one's own. */
 .agent-state-card .agent-use-key { align-self: center; }
 
+/* No agent server behind the page: a quiet status (icon + words), not an alert. */
+.agent-offline-icon { align-self: center; color: var(--agent-text-muted); }
+.agent-offline-card code {
+	padding: 0 var(--agent-space-1);
+	border-radius: var(--agent-radius-sm);
+	background: var(--agent-bg-sunken);
+	color: var(--agent-text);
+	font-size: var(--agent-font-sm);
+}
+.agent-offline-retry { align-self: center; display: inline-flex; align-items: center; gap: var(--agent-space-2); }
+.agent-signin-error { align-self: center; max-width: 32ch; }
+
 .agent-primary-button {
 	align-self: center;
 	border: 1px solid var(--agent-accent-edge);

package/src/workflow/agent-plan.css

@@ -0,0 +1,93 @@
+/* A turn's step checklist (AgentPlanCard.jsx); colours, sizes and motion come from agent-panel.css. */
+.agent-plan-row[data-plan-live="true"] {
+	position: sticky;
+	top: calc(-1 * var(--agent-space-5));
+	z-index: 1;
+	/* the transcript's own colour above the card, so steps scrolling under it never show through the gap */
+	padding-top: var(--agent-space-2);
+	margin-top: calc(-1 * var(--agent-space-2));
+	background: var(--agent-bg);
+}
+
+.agent-plan {
+	--agent-plan-mark: 11px;
+	display: flex;
+	flex-direction: column;
+}
+
+.agent-plan-row[data-plan-live="true"] .agent-plan { box-shadow: 0 6px 14px -8px #000c; }
+
+.agent-plan-head {
+	display: flex;
+	align-items: center;
+	gap: var(--agent-space-3);
+	padding: var(--agent-space-2) var(--agent-space-4);
+	color: var(--agent-text-soft, var(--agent-text));
+	font-size: var(--agent-font-md);
+}
+
+.agent-plan-title { flex: none; font-weight: 600; }
+
+.agent-plan-bar {
+	flex: 1;
+	height: 3px;
+	overflow: hidden;
+	border-radius: var(--agent-radius-pill);
+	background: var(--agent-track);
+}
+
+.agent-plan-fill {
+	display: block;
+	height: 100%;
+	background: var(--agent-ok);
+	transform: scaleX(var(--agent-plan-done, 0));
+	transform-origin: left;
+	transition: transform var(--agent-motion);
+}
+
+.agent-plan-count { flex: none; color: var(--agent-text-dim); font: var(--agent-font-sm) ui-monospace, monospace; font-variant-numeric: tabular-nums; }
+
+.agent-plan-steps {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+	margin: 0;
+	padding: var(--agent-space-1) 0 var(--agent-space-2);
+	border-top: 1px solid var(--agent-border);
+	list-style: none;
+}
+
+.agent-plan-step {
+	display: flex;
+	align-items: center;
+	gap: var(--agent-space-3);
+	min-width: 0;
+	padding: 2px var(--agent-space-4);
+	color: var(--agent-text-muted);
+	font-size: var(--agent-font-md);
+	line-height: 1.4;
+}
+
+.agent-plan-text { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.agent-plan-step.done { color: var(--agent-text-dim); }
+.agent-plan-step.active { background: color-mix(in srgb, var(--agent-accent) 12%, transparent); color: var(--agent-text); }
+.agent-plan-step.unfinished { color: var(--agent-text-dim); }
+.agent-plan-step.unfinished .agent-plan-text { font-style: italic; }
+
+.agent-plan-mark { flex: none; width: var(--agent-plan-mark); height: var(--agent-plan-mark); }
+.agent-plan-mark.done { color: var(--agent-ok); }
+.agent-plan-mark.unfinished { color: var(--agent-warn); }
+.agent-plan-mark.pending { border: 1.5px solid var(--agent-border-strong); border-radius: var(--agent-radius-pill); }
+/* the step under way: an accent ring whose centre breathes while the turn runs */
+.agent-plan-mark.active { position: relative; border: 1.5px solid var(--agent-accent); border-radius: var(--agent-radius-pill); }
+.agent-plan-mark.active::after { content: ""; position: absolute; inset: 2px; border-radius: var(--agent-radius-pill); background: var(--agent-accent); }
+.agent-plan[data-plan-state="live"] .agent-plan-mark.active::after { animation: agent-pulse 1.4s ease-in-out infinite; }
+
+/* A finished turn's card is a record: it keeps its rows but no longer pulls the eye. */
+.agent-plan:not([data-plan-state="live"]) .agent-plan-fill { background: var(--agent-text-dim); }
+.agent-plan[data-plan-state="done"] .agent-plan-fill { background: var(--agent-ok); }
+
+@media (prefers-reduced-motion: reduce) {
+	.agent-plan[data-plan-state="live"] .agent-plan-mark.active::after { animation: none; }
+	.agent-plan-fill { transition: none; }
+}

package/src/workflow/agent-plan.js

@@ -0,0 +1,59 @@
+// A turn's step checklist as the agent panel keeps it (AgentPlanCard.jsx draws it): the sidecar's plan tool
+// (bin/agent/plan-tool.mjs) sends the whole list in every plan.update frame, and the chat store (agent-client.js) keeps
+// one plan card per turn, right under the turn's prompt. The card never claims more than happened: when the turn ends,
+// the step still under way counts as done only if the turn succeeded, and is left unfinished when it failed or stopped.
+// Pure data, like agent-turn.js.
+
+const STATUSES = new Set(["pending", "active", "done"]);
+const MAX_STEPS = 12, TEXT_MAX = 80;
+
+/** A frame's steps as the card keeps them, or null when they are not a plan. */
+function planSteps(steps) {
+	if (!Array.isArray(steps) || !steps.length || steps.length > MAX_STEPS) return null;
+	const kept = steps.map(step => ({ text: String(step?.text ?? "").replace(/\s+/g, " ").trim().slice(0, TEXT_MAX), status: step?.status }));
+	return kept.every(step => step.text && STATUSES.has(step.status)) ? kept : null;
+}
+
+/** Whether a frame belongs to the plan: its update, or the plan tool's own call (the card shows it, never a step row). */
+export const isPlanFrame = event => event?.type === "plan.update" || (event?.name === "plan" && ["tool.compose", "tool.start", "tool.progress"].includes(event?.type));
+
+/** items after a plan frame: the turn's one plan card, under its prompt, takes the frame's list whole. */
+export function withPlanFrame(items, event, newId) {
+	const steps = event?.type === "plan.update" ? planSteps(event.steps) : null;
+	if (!steps) return items;
+	const prompt = items.findLastIndex(item => item.kind === "user" && !item.steered);
+	const at = items.findIndex((item, i) => i > prompt && item.kind === "plan");
+	if (at !== -1) return items.map((item, i) => i === at ? { ...item, steps } : item);
+	return [...items.slice(0, prompt + 1), { kind: "plan", id: newId(), steps }, ...items.slice(prompt + 1)];
+}
+
+/** A plan whose turn ended ("done", "failed" or "stopped"): the step under way is done only when the turn succeeded. */
+export function settledPlan(plan, status) {
+	const outcome = status === "done" || status === "stopped" ? status : "failed";
+	return { ...plan, outcome, steps: plan.steps.map(step => step.status === "active" ? { ...step, status: outcome === "done" ? "done" : "unfinished" } : step) };
+}
+
+/** items at the end of a turn: its plan card settles (settledPlan); earlier turns' cards already have. */
+export const withPlanEnd = (items, status) => items.map(item => item.kind === "plan" && !item.outcome ? settledPlan(item, status) : item);
+
+/**
+ * A restored transcript's plans (session-store.mjs lists one per change): each turn keeps its last list, under its
+ * prompt; the plan tool's own calls go; and the card settles by how the turn ended: failed when a failure follows, done
+ * when the turn ends on the reply, else stopped (the history ends mid-turn: the panel reloaded while it ran).
+ */
+export function restoredPlans(items) {
+	const turns = [];
+	for (const item of items) {
+		if (item.kind === "tool" && item.name === "plan") continue;
+		if (item.kind === "user" || !turns.length) turns.push([]);
+		turns.at(-1).push(item);
+	}
+	return turns.flatMap(turn => {
+		const rest = turn.filter(item => item.kind !== "plan"), plan = turn.findLast(item => item.kind === "plan");
+		const steps = plan ? planSteps(plan.steps) : null;
+		if (!steps) return rest;
+		const status = rest.some(item => item.kind === "failure") ? "failed" : rest.at(-1)?.kind === "assistant" ? "done" : "stopped";
+		const prompt = rest[0]?.kind === "user" ? 1 : 0;
+		return [...rest.slice(0, prompt), settledPlan({ ...plan, steps }, status), ...rest.slice(prompt)];
+	});
+}

package/src/workflow/attachment-image.js

@@ -10,6 +10,7 @@
  * Anything under it is sent verbatim: no re-encode, no generation loss.
  */
 import { fileToDataUrl, imageFileFromTransfer } from "./clipboard-image.js";
+import { isVideoFile, videoContactSheet } from "./attachment-video.js";
 
 export const ATTACHMENT_MAX_COUNT = 4;
 export const ATTACHMENT_MAX_DIMENSION = 1600;
@@ -19,8 +20,9 @@ export const ATTACHMENT_JPEG_QUALITY = 0.85;
  * rest here rather than letting the sidecar reject a turn the author sent. */
 const ATTACHMENT_TYPES = Object.freeze(["image/png", "image/jpeg", "image/webp"]);
 export const ATTACHMENT_LIMIT_NOTICE = "Up to 4 images per message";
-export const ATTACHMENT_TYPE_NOTICE = "Attach a PNG, JPEG or WebP image";
-export const ATTACHMENT_FAILED_NOTICE = "That image could not be attached";
+export const ATTACHMENT_TYPE_NOTICE = "Attach a PNG, JPEG or WebP image, or a video";
+export const ATTACHMENT_FAILED_NOTICE = "That image or video could not be attached";
+export const ATTACHMENT_ACCEPT = [...ATTACHMENT_TYPES, "video/*"].join(",");
 
 const EXTENSION_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp" };
 
@@ -57,7 +59,8 @@ export function attachmentFilesFromTransfer(transfer) {
 	const images = [];
 	let unsupported = 0;
 	for (const file of candidates) {
-		if (attachmentType(file)) images.push(file);
+		// A video travels as a contact sheet image (attachment-video.js).
+		if (attachmentType(file) || isVideoFile(file)) images.push(file);
 		else if (String(file?.type ?? "").startsWith("image/")) unsupported += 1;
 	}
 	return { images, unsupported };
@@ -155,6 +158,10 @@ export function attachmentName(file) {
  * media type is the resolved one: a file dragged in without a type would
  * otherwise be labelled PNG whatever its bytes are. */
 export async function attachmentFromFile(file, options = {}) {
+	if (isVideoFile(file)) {
+		const sheet = await videoContactSheet(file);
+		return { dataUrl: await blobToDataUrl(sheet.blob, "image/jpeg"), name: sheet.name };
+	}
 	const { readDataUrl = fileToDataUrl, ...shrink } = options;
 	const type = attachmentType(file) ?? "image/png";
 	const read = await readDataUrl(file);

package/src/workflow/attachment-video.js

@@ -0,0 +1,91 @@
+/**
+ * A video the author attaches to a turn. The turn envelope carries images
+ * only, and the models behind it read pictures, not clips, so the composer
+ * turns a video into one contact sheet: evenly spaced frames in a grid, each
+ * stamped with its time. It costs one attachment slot and keeps the order of
+ * the action legible to the model.
+ */
+
+const VIDEO_EXTENSIONS = new Set(["mp4", "m4v", "mov", "webm", "ogv", "mkv"]);
+const SHEET_FRAMES = 9;
+const SHEET_COLUMNS = 3;
+const SHEET_CELL_WIDTH = 480;
+const SHEET_JPEG_QUALITY = 0.85;
+
+export function isVideoFile(file) {
+	const declared = String(file?.type ?? "").toLowerCase();
+	if (declared) return declared.startsWith("video/");
+	const extension = String(file?.name ?? "").toLowerCase().match(/\.([a-z0-9]+)$/)?.[1];
+	return VIDEO_EXTENSIONS.has(extension);
+}
+
+function sheetTimes(duration, count) {
+	return Array.from({ length: count }, (_, index) => (index + 0.5) * duration / count);
+}
+
+function formatSheetTime(seconds) {
+	const minutes = Math.floor(seconds / 60);
+	return `${minutes}:${(seconds - minutes * 60).toFixed(1).padStart(4, "0")}`;
+}
+
+function nextEvent(target, name) {
+	return new Promise((resolve, reject) => {
+		const done = () => { target.removeEventListener(name, done); target.removeEventListener("error", failed); resolve(); };
+		const failed = () => { target.removeEventListener(name, done); target.removeEventListener("error", failed); reject(new Error("this browser cannot decode that video")); };
+		target.addEventListener(name, done);
+		target.addEventListener("error", failed);
+	});
+}
+
+/**
+ * One video file as a JPEG contact sheet `{ blob, name }`. Decoding happens in
+ * a detached <video>; a codec the browser cannot play rejects instead of
+ * producing a black sheet.
+ */
+export async function videoContactSheet(file, { doc = globalThis.document, frames = SHEET_FRAMES } = {}) {
+	const url = URL.createObjectURL(file);
+	const video = doc.createElement("video");
+	video.muted = true;
+	video.playsInline = true;
+	video.preload = "auto";
+	try {
+		const loaded = nextEvent(video, "loadeddata");
+		video.src = url;
+		await loaded;
+		const { duration, videoWidth, videoHeight } = video;
+		if (!Number.isFinite(duration) || duration <= 0 || !videoWidth || !videoHeight) throw new Error("that video has no usable length or size");
+		const cellWidth = Math.min(SHEET_CELL_WIDTH, videoWidth);
+		const cellHeight = Math.round(cellWidth * videoHeight / videoWidth);
+		const canvas = doc.createElement("canvas");
+		canvas.width = cellWidth * SHEET_COLUMNS;
+		canvas.height = cellHeight * Math.ceil(frames / SHEET_COLUMNS);
+		const context = canvas.getContext("2d");
+		if (!context) throw new Error("this browser cannot draw video frames — no 2D context");
+		context.fillStyle = "#000";
+		context.fillRect(0, 0, canvas.width, canvas.height);
+		context.font = `600 ${Math.max(12, Math.round(cellHeight / 12))}px system-ui, sans-serif`;
+		context.textBaseline = "top";
+		for (const [index, time] of sheetTimes(duration, frames).entries()) {
+			const seeked = nextEvent(video, "seeked");
+			video.currentTime = time;
+			await seeked;
+			const x = (index % SHEET_COLUMNS) * cellWidth;
+			const y = Math.floor(index / SHEET_COLUMNS) * cellHeight;
+			context.drawImage(video, x, y, cellWidth, cellHeight);
+			const stamp = `${index + 1} · ${formatSheetTime(time)}`;
+			const pad = 6;
+			const box = context.measureText(stamp).width + pad * 2;
+			context.fillStyle = "rgba(0, 0, 0, 0.6)";
+			context.fillRect(x + 4, y + 4, box, Math.round(cellHeight / 12) + pad * 2);
+			context.fillStyle = "#fff";
+			context.fillText(stamp, x + 4 + pad, y + 4 + pad);
+		}
+		const blob = await new Promise((resolve, reject) => canvas.toBlob((result) => result ? resolve(result) : reject(new Error("the contact sheet could not be encoded")), "image/jpeg", SHEET_JPEG_QUALITY));
+		const base = String(file?.name ?? "").trim() || "video";
+		return { blob, name: `${base.slice(0, 70)} (${frames} frames over ${duration.toFixed(1)}s)` };
+	} finally {
+		video.removeAttribute("src");
+		video.load();
+		URL.revokeObjectURL(url);
+	}
+}