feat: add waitForRecording MCP tool for user-controlled takes

electron/electron-env.d.ts

@@ -46,6 +46,10 @@ interface Window {
 				meta: import("../src/native/contracts").CompositorSharedFrameMeta,
 			) => void,
 		) => () => void;
+		reportRecordingOutcome?: (
+			outcome: import("../src/lib/recordingSession").RecordingOutcome,
+		) => Promise<{ success: boolean }>;
+
 		getSources: (opts: Electron.SourcesOptions) => Promise<ProcessedDesktopSource[]>;
 		switchToEditor: () => Promise<void>;
 		switchToHud: () => Promise<void>;

electron/ipc/handlers.ts

@@ -18,6 +18,7 @@ import {
 	shell,
 	systemPreferences,
 } from "electron";
+import { z } from "zod";
 import { DEFAULT_WEBCAM_QUALITY, type WebcamQualityId } from "../../src/hooks/webcamCaptureTarget";
 import {
 	type AxcutDocument,
@@ -88,6 +89,7 @@ import { McpController } from "../mcp/mcp-controller";
 import { McpSettingsStore } from "../mcp/mcp-settings-store";
 import { createMediaTools, type MediaToolDeps, type RecordRequest } from "../mcp/media-tools";
 import { createToolRunner, type McpToolDeps } from "../mcp/openscreen-mcp-server";
+import { RecordingCompletion } from "../mcp/recording-completion";
 import { type AudioPeaksResult, getAudioPeaks } from "../media/audioPeaks";
 import {
 	readCursorRecordingFile as readCursorRecordingFileFrom,
@@ -1985,15 +1987,17 @@ export function registerIpcHandlers(
 ) {
 	/** The HUD is recording a take, the user's or an MCP client's. Set by `setAppRecording` only. */
 	let appRecording = false;
+	const recordingCompletion = new RecordingCompletion();
 	/**
 	 * Every start and stop of a take goes through here: the browser path's `set-recording-state`
 	 * and the native paths, which start and stop in this process. The MCP recorder waits on it
 	 * for a client's take to start, and the tray shows it. A native path that called
 	 * `onRecordingStateChange` itself left the MCP recorder waiting on a take already running.
 	 */
-	const setAppRecording = (recording: boolean, sourceName: string) => {
+	const setAppRecording = (recording: boolean, sourceName: string, recordingId?: number) => {
+		if (recording && recordingId !== undefined) recordingCompletion.started(recordingId);
 		appRecording = recording;
-		mcpAppRecorder.recordingChanged(recording);
+		mcpAppRecorder.recordingChanged(recording, recordingId);
 		onRecordingStateChange?.(recording, sourceName);
 	};
 	const appSettings = new AppSettingsStore(app.getPath("userData"));
@@ -2782,7 +2786,7 @@ export function registerIpcHandlers(
 				// "Screen" }`, so the tray confidently displayed the name of a
 				// window the capture had never been told about.
 				linuxNativeCaptureSourceLabel = linuxSourceLabel(session.grantedSourceKind);
-				setAppRecording(true, linuxNativeCaptureSourceLabel);
+				setAppRecording(true, linuxNativeCaptureSourceLabel, recordingId);
 
 				return { success: true, recordingId, path: outputPath };
 			} catch (error) {
@@ -3078,7 +3082,7 @@ export function registerIpcHandlers(
 				});
 
 				const source = selectedSource || { name: "Screen" };
-				setAppRecording(true, source.name);
+				setAppRecording(true, source.name, recordingId);
 
 				// Reported at start, not at stop: the helper decides the camera is a
 				// lost cause during its own init — before it announces "Recording
@@ -3350,7 +3354,7 @@ export function registerIpcHandlers(
 					: 0;
 
 			const source = selectedSource || { name: "Screen" };
-			setAppRecording(true, source.name);
+			setAppRecording(true, source.name, recordingId);
 
 			return {
 				success: true,
@@ -4154,7 +4158,7 @@ export function registerIpcHandlers(
 			}
 
 			const source = selectedSource || { name: "Screen" };
-			setAppRecording(recording, source.name);
+			setAppRecording(recording, source.name, recordingId);
 		},
 	);
 
@@ -4896,10 +4900,46 @@ export function registerIpcHandlers(
 		setCurrentRecordingSessionState(normalizedSession);
 		currentVideoPath = normalizedSession?.screenVideoPath ?? null;
 		currentProjectPath = null;
-		if (normalizedSession) mcpAppRecorder.takeSaved(normalizedSession.screenVideoPath);
+		if (normalizedSession) {
+			mcpAppRecorder.takeSaved(normalizedSession.screenVideoPath);
+			// Every capture path stamps the session's `createdAt` with its recordingId (the
+			// `Date.now()` it started at), so it names the take `recordingCompletion` tracks.
+			// Any other session (an opened file) carries a fresh `Date.now()` and matches none.
+			recordingCompletion.saved(normalizedSession.createdAt, normalizedSession.screenVideoPath);
+		}
 		return { success: true, session: currentRecordingSession };
 	});
 
+	// A renderer acknowledgement of the actual hand-off, after the duration and
+	// automatic zoom saves. An imported/opened project never emits this signal.
+	const recordingOutcomeSchema = z.discriminatedUnion("status", [
+		z.object({
+			recordingId: z.number().finite(),
+			status: z.literal("ready"),
+			projectId: z.string(),
+		}),
+		z.object({
+			recordingId: z.number().finite(),
+			status: z.enum(["failed", "cancelled"]),
+			message: z.string(),
+		}),
+	]);
+	ipcMain.handle("recording-outcome", async (_, input: unknown) => {
+		const parsed = recordingOutcomeSchema.safeParse(input);
+		if (!parsed.success) return { success: false };
+		const outcome = parsed.data;
+		if (outcome.status !== "ready") {
+			recordingCompletion.failed(outcome.recordingId, outcome.message);
+			mcpAppRecorder.recordingFinished(outcome.recordingId);
+			return { success: true };
+		}
+		await recordingCompletion.projectReady(outcome.recordingId, outcome.projectId, (id) =>
+			aiEditionDocuments.getProject(id),
+		);
+		mcpAppRecorder.recordingFinished(outcome.recordingId);
+		return { success: true };
+	});
+
 	ipcMain.handle("get-current-recording-session", () => {
 		if (!currentRecordingSession) {
 			return { success: false };
@@ -5183,6 +5223,8 @@ export function registerIpcHandlers(
 		host: mcpToolDeps.host,
 	});
 	const mcpMedia = createMediaTools({
+		recordingActive: () => recordingCompletion.isActive(),
+		waitForRecording: (timeoutMs, signal) => recordingCompletion.wait(timeoutMs, signal),
 		transport: "http",
 		// Recording and exporting change things too: the same switch as edits.
 		editsAllowed: mcpToolDeps.editsAllowed,

electron/ipc/recordingStateRouting.test.ts

@@ -36,7 +36,7 @@ describe("recording state routing", () => {
 		const setter = source.slice(source.indexOf("const setAppRecording"));
 		const body = setter.slice(0, setter.indexOf("};"));
 		expect(body).toContain("appRecording = recording");
-		expect(body).toContain("mcpAppRecorder.recordingChanged(recording)");
+		expect(body).toContain("mcpAppRecorder.recordingChanged(recording, recordingId)");
 		expect(body).toContain("onRecordingStateChange?.(recording, sourceName)");
 	});
 

electron/mcp/app-recorder.test.ts

@@ -157,6 +157,20 @@ describe("an MCP take in the app", () => {
 		expect(editor.applied).toEqual([]);
 	});
 
+	it("releases only the client take whose app lifecycle finished", async () => {
+		const { recorder, calls } = setup();
+		const starting = recorder.start(REQUEST);
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		recorder.recordingChanged(true, 7);
+		await starting;
+		recorder.recordingFinished(6);
+		await expect(recorder.start(REQUEST)).rejects.toThrow("already recording");
+		recorder.recordingChanged(false, 7);
+		recorder.recordingFinished(7);
+		expect(calls.filter((call) => call === "restore")).toHaveLength(1);
+		await expect(started(recorder, calls)).resolves.toBeDefined();
+	});
+
 	it("refuses a take while one records, or while the editor holds unsaved changes", async () => {
 		const busy = setup({ isRecording: () => true });
 		await expect(busy.recorder.start(REQUEST)).rejects.toThrow("already recording");

electron/mcp/app-recorder.ts

@@ -103,7 +103,9 @@ export interface AppRecorderDeps {
 
 export interface AppRecorder extends TakeRecorder {
 	/** The app's recording state changed (`set-recording-state`). */
-	recordingChanged(recording: boolean): void;
+	recordingChanged(recording: boolean, recordingId?: number): void;
+	/** A completed or failed app take no longer owns the recording bar. */
+	recordingFinished(recordingId: number): void;
 	/** The recording bar handed a saved take to the editor (`set-current-recording-session`). */
 	takeSaved(videoPath: string): void;
 }
@@ -145,6 +147,7 @@ interface Deferred<T> {
 }
 
 interface ClientTake {
+	recordingId?: number;
 	phase: "starting" | "recording" | "saving";
 	/** Resolves with when capture started. */
 	started: Deferred<number>;
@@ -214,10 +217,16 @@ export function createAppRecorder(deps: AppRecorderDeps): AppRecorder {
 	}
 
 	return {
-		recordingChanged(recording) {
+		recordingFinished(recordingId) {
+			if (current?.recordingId !== recordingId) return;
+			current.restore();
+			current = null;
+		},
+		recordingChanged(recording, recordingId) {
 			if (!current) return;
 			if (recording && current.phase === "starting") {
 				current.phase = "recording";
+				current.recordingId = recordingId;
 				current.started.resolve(Date.now());
 			} else if (!recording && current.phase === "recording") {
 				// The take is captured: the bar's own settings can come back while it saves.

electron/mcp/media-tools.test.ts

@@ -26,6 +26,7 @@ import {
 	createToolRunner,
 	type McpToolDeps,
 } from "./openscreen-mcp-server";
+import { RecordingCompletion } from "./recording-completion";
 
 /** The runner windows: records what was asked, answers like a runner would. */
 class FakeRunners {
@@ -1069,3 +1070,174 @@ describe("the media tools in the app", () => {
 		expect(exportPath.description).not.toContain("working directory, ending");
 	});
 });
+
+describe("waitForRecording through MCP", () => {
+	const clients: Client[] = [];
+	afterEach(async () => {
+		for (const client of clients.splice(0)) await client.close();
+	});
+	async function observing(
+		completion: RecordingCompletion,
+		overrides: Partial<MediaToolDeps> = {},
+	) {
+		const deps: McpToolDeps = {
+			transport: "http",
+			host: { snapshot: async () => null, apply: async () => "no-editor" },
+			projects: documents,
+			editsAllowed: () => false,
+			version: "test",
+		};
+		let subscribed: () => void = () => undefined;
+		const subscription = new Promise<void>((resolve) => {
+			subscribed = resolve;
+		});
+		const media = createMediaTools({
+			...stdioDeps,
+			transport: "http",
+			recordingActive: () => completion.isActive(),
+			editsAllowed: () => false,
+			waitForRecording: (timeout, signal) => {
+				const waiting = completion.wait(timeout, signal);
+				subscribed();
+				return waiting;
+			},
+			...overrides,
+		});
+		const server = createOpenScreenMcpServer(deps, createToolRunner(deps), media);
+		const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+		await server.connect(serverSide);
+		const observer = new Client({ name: "observer", version: "1" });
+		await observer.connect(clientSide);
+		clients.push(observer);
+		return { observer, subscription };
+	}
+
+	it("returns the stopRecording fields for a user take while MCP edits is off, without recording commands", async () => {
+		const project = await documents.createProject("User take");
+		const completion = new RecordingCompletion();
+		completion.started(42, 1_000);
+		const { observer, subscription } = await observing(completion);
+		const waiting = observer.callTool({ name: "waitForRecording", arguments: {} });
+		await subscription;
+		completion.saved(42, videoPath);
+		completion.completed(42, {
+			projectId: project.project.id,
+			videoPath,
+			durationSec: 12,
+			autoZooms: 2,
+		});
+		const result = await waiting;
+		expect(result.isError).toBeFalsy();
+		expect(JSON.parse(textOf(result as CallToolResult))).toEqual({
+			projectId: project.project.id,
+			videoPath,
+			durationSec: 12,
+			autoZooms: 2,
+			recordingStartedAt: 1_000,
+			checkpointId: expect.any(String),
+		});
+		expect(runners.started).toEqual([]);
+	});
+
+	it("gives setPointerTrack the waited-for take's start, as stopRecording does", async () => {
+		const project = await documents.createProject("User take");
+		const completion = new RecordingCompletion();
+		completion.started(42, 1_000);
+		const sent: unknown[] = [];
+		const { observer, subscription } = await observing(completion, {
+			runTool: async (_name, args) => {
+				sent.push(args);
+				return { content: [{ type: "text", text: "ok" }] };
+			},
+		});
+		const waiting = observer.callTool({ name: "waitForRecording", arguments: {} });
+		await subscription;
+		completion.saved(42, videoPath);
+		completion.completed(42, {
+			projectId: project.project.id,
+			videoPath,
+			durationSec: 12,
+			autoZooms: 0,
+		});
+		await waiting;
+		await observer.callTool({
+			name: "setPointerTrack",
+			arguments: { projectId: project.project.id, events: [{ at: 1, x: 0.5, y: 0.5 }] },
+		});
+		expect(sent).toContainEqual(expect.objectContaining({ takes: { [videoPath]: 1_000 } }));
+	});
+
+	it("releases a client take after the user finishes it, so startRecording can record again", async () => {
+		const completion = new RecordingCompletion();
+		let id = 0;
+		const recorder: TakeRecorder = {
+			start: async () => {
+				completion.started(++id);
+				return {
+					startedAt: id,
+					stop: async () => {
+						throw new Error("wait must never stop the take");
+					},
+				};
+			},
+		};
+		const { observer, subscription } = await observing(completion, {
+			recorder,
+			editsAllowed: () => true,
+		});
+		expect(
+			(await observer.callTool({ name: "startRecording", arguments: {} })).isError,
+		).toBeFalsy();
+		const waiting = observer.callTool({ name: "waitForRecording", arguments: {} });
+		await subscription;
+		completion.saved(1, videoPath);
+		completion.completed(1, { projectId: "proj_take", videoPath, durationSec: 12, autoZooms: 0 });
+		await waiting;
+		expect(
+			(await observer.callTool({ name: "startRecording", arguments: {} })).isError,
+		).toBeFalsy();
+		expect(id).toBe(2);
+	});
+
+	it.each([
+		0,
+		-1,
+		1.5,
+		3601,
+		"10",
+	])("validates timeoutSec=%s before observing", async (timeoutSec) => {
+		const completion = new RecordingCompletion();
+		const { observer } = await observing(completion);
+		const result = await observer.callTool({ name: "waitForRecording", arguments: { timeoutSec } });
+		expect(result.isError).toBe(true);
+		expect(textOf(result as CallToolResult)).toContain("validation");
+	});
+
+	it("reports no active recording as a tool error", async () => {
+		const { observer } = await observing(new RecordingCompletion());
+		const result = await observer.callTool({ name: "waitForRecording", arguments: {} });
+		expect(result.isError).toBe(true);
+		expect(textOf(result as CallToolResult)).toContain("No recording");
+	});
+
+	it("propagates MCP cancellation and leaves the user's take available", async () => {
+		const completion = new RecordingCompletion();
+		completion.started(42);
+		const { observer, subscription } = await observing(completion);
+		const abort = new AbortController();
+		const waiting = expect(
+			observer.callTool({ name: "waitForRecording", arguments: {} }, undefined, {
+				signal: abort.signal,
+			}),
+		).rejects.toThrow();
+		await subscription;
+		abort.abort();
+		await waiting;
+		// Flush the MCP cancellation notification, then the same take still completes.
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		const retry = completion.wait(1000, new AbortController().signal);
+		completion.saved(42, videoPath);
+		completion.completed(42, { projectId: "proj_take", videoPath, durationSec: 12, autoZooms: 0 });
+		await expect(retry).resolves.toMatchObject({ projectId: "proj_take" });
+	});
+});