feat(agent): generalize filler removal into removeWords

Any cut chosen by transcript word IDs (fillers, a flubbed phrase, a duplicate take) now goes through one tool. Words consecutive in the transcript become a single trim, so a phrase leaves no inter-word gaps playing.

Author: EtienneLescot

electron/ai-edition/agent-tools.test.ts

@@ -183,7 +183,7 @@ describe("the mutating-tool table", () => {
 				"removeClip",
 				"removeModifier",
 				"removeTrim",
-				"removeFillerWords",
+				"removeWords",
 				"replaceTimeline",
 				"setAnnotation",
 				"setAudio",
@@ -2385,7 +2385,7 @@ describe("getTranscriptWords", () => {
 	});
 });
 
-describe("removeFillerWords", () => {
+describe("removeWords", () => {
 	function repeatedWordDocument(): AxcutDocument {
 		const base = fixtureDocument();
 		return {
@@ -2409,7 +2409,7 @@ describe("removeFillerWords", () => {
 			"filler",
 			"meaningful",
 		]);
-		const result = run(before, "removeFillerWords", { wordIds: ["filler"] });
+		const result = run(before, "removeWords", { wordIds: ["filler"] });
 		expect(result.ok).toBe(true);
 		const next = result.document as AxcutDocument;
 		const trim = next.timeline.trimRanges.at(-1);
@@ -2438,6 +2438,52 @@ describe("removeFillerWords", () => {
 		expect(next.timeline.trimRanges).toHaveLength(before.timeline.trimRanges.length + 1);
 	});
 
+	it("cuts consecutive words as one span, gaps included, and the others apart", () => {
+		const base = fixtureDocument();
+		const before: AxcutDocument = {
+			...base,
+			transcripts: [
+				{
+					...base.transcripts[0],
+					words: [
+						{ id: "word_1", segmentId: "seg_1", startSec: 1, endSec: 1.2, text: "so" },
+						{ id: "word_2", segmentId: "seg_1", startSec: 1.4, endSec: 1.5, text: "I" },
+						{ id: "word_3", segmentId: "seg_1", startSec: 1.6, endSec: 1.9, text: "mean" },
+						{ id: "word_4", segmentId: "seg_1", startSec: 2.2, endSec: 2.4, text: "the" },
+						{ id: "word_5", segmentId: "seg_1", startSec: 3, endSec: 3.2, text: "um" },
+					],
+				},
+			],
+		};
+		const result = run(before, "removeWords", { wordIds: ["word_3", "word_5", "word_2"] });
+		expect(result.ok).toBe(true);
+		const added = result.document?.timeline.trimRanges.slice(before.timeline.trimRanges.length);
+		expect(added?.map(({ startSec, endSec }) => [startSec, endSec])).toEqual([
+			[1.4, 1.9],
+			[3, 3.2],
+		]);
+		const removed = JSON.parse(result.resultJson).removed;
+		expect(removed.map((word: { wordId: string }) => word.wordId)).toEqual([
+			"word_2",
+			"word_3",
+			"word_5",
+		]);
+		expect(removed[1].trimRangeId).toBe(removed[0].trimRangeId);
+		expect(removed[2].trimRangeId).not.toBe(removed[0].trimRangeId);
+	});
+
+	it("refuses a duplicated or already-cut word without cutting anything", () => {
+		const before = repeatedWordDocument();
+		const duplicated = run(before, "removeWords", { wordIds: ["filler", "filler"] });
+		expect(duplicated.ok).toBe(false);
+		expect(duplicated.document).toBeUndefined();
+		const cut = run(before, "removeWords", { wordIds: ["filler"] }).document as AxcutDocument;
+		const again = run(cut, "removeWords", { wordIds: ["meaningful", "filler"] });
+		expect(again.ok).toBe(false);
+		expect(again.document).toBeUndefined();
+		expect(again.resultJson).toContain("already cut");
+	});
+
 	it("preserves addTrim warnings when removing a filler cuts a zoom transition", () => {
 		const before = repeatedWordDocument();
 		before.timeline.trimRanges = [];
@@ -2452,14 +2498,14 @@ describe("removeFillerWords", () => {
 		});
 		const expected = JSON.parse(directTrim.resultJson).cutTransitions;
 		expect(expected.length).toBeGreaterThan(0);
-		const removed = run(zoomed, "removeFillerWords", { assetId: "asset_1", wordIds: ["filler"] });
+		const removed = run(zoomed, "removeWords", { assetId: "asset_1", wordIds: ["filler"] });
 		expect(removed.ok).toBe(true);
 		expect(JSON.parse(removed.resultJson).cutTransitions).toEqual(expected);
 	});
 
 	it("refuses an invalid ID atomically, including when another ID is valid", () => {
 		const before = repeatedWordDocument();
-		const result = run(before, "removeFillerWords", { wordIds: ["filler", "missing"] });
+		const result = run(before, "removeWords", { wordIds: ["filler", "missing"] });
 		expect(result.ok).toBe(false);
 		expect(result.document).toBeUndefined();
 		expect(result.resultJson).toContain("Unknown transcript word ID: missing");
@@ -2479,7 +2525,7 @@ describe("removeFillerWords", () => {
 			assetId: "asset_2",
 			words: [{ id: "other_filler", segmentId: "seg_1", startSec: 4, endSec: 4.2, text: "um" }],
 		});
-		const result = run(before, "removeFillerWords", { wordIds: ["other_filler"] });
+		const result = run(before, "removeWords", { wordIds: ["other_filler"] });
 		expect(result.ok).toBe(true);
 		expect(result.document?.timeline.trimRanges.at(-1)).toMatchObject({
 			assetId: "asset_2",
@@ -2503,7 +2549,7 @@ describe("removeFillerWords", () => {
 		});
 		const read = JSON.parse(run(before, "getTranscriptWords", { assetId: "asset_2" }).resultJson);
 		expect(read.words[0].id).toBe("word_1");
-		const result = run(before, "removeFillerWords", {
+		const result = run(before, "removeWords", {
 			assetId: "asset_2",
 			wordIds: [read.words[0].id],
 		});
@@ -2516,10 +2562,10 @@ describe("removeFillerWords", () => {
 			result.document?.timeline.trimRanges.filter((trim) => trim.assetId === "asset_1"),
 		).toEqual(before.timeline.trimRanges);
 		expect(result.document?.transcripts).toEqual(before.transcripts);
-		const ambiguous = run(before, "removeFillerWords", { wordIds: ["word_1"] });
+		const ambiguous = run(before, "removeWords", { wordIds: ["word_1"] });
 		expect(ambiguous.ok).toBe(false);
 		expect(ambiguous.document).toBeUndefined();
-		const unknownAsset = run(before, "removeFillerWords", {
+		const unknownAsset = run(before, "removeWords", {
 			assetId: "missing_asset",
 			wordIds: ["word_1"],
 		});
@@ -2530,7 +2576,7 @@ describe("removeFillerWords", () => {
 	it("refuses invalid timestamps without guessing a span", () => {
 		const before = repeatedWordDocument();
 		before.transcripts[0].words[0].endSec = Number.NaN;
-		const result = run(before, "removeFillerWords", { wordIds: ["filler"] });
+		const result = run(before, "removeWords", { wordIds: ["filler"] });
 		expect(result.ok).toBe(false);
 		expect(result.document).toBeUndefined();
 		expect(result.resultJson).toContain("invalid source timestamps");
@@ -2542,7 +2588,7 @@ describe("removeFillerWords", () => {
 			...before.timeline.clips[0],
 			id: "duplicate_clip",
 		});
-		const result = run(before, "removeFillerWords", { wordIds: ["filler"] });
+		const result = run(before, "removeWords", { wordIds: ["filler"] });
 		expect(result.ok).toBe(false);
 		expect(result.document).toBeUndefined();
 		expect(result.resultJson).toContain("exactly one clip; found 2");
@@ -2551,7 +2597,7 @@ describe("removeFillerWords", () => {
 	it("honours project edit consent", () => {
 		const result = executeAgentTool(
 			repeatedWordDocument(),
-			"removeFillerWords",
+			"removeWords",
 			JSON.stringify({ wordIds: ["filler"] }),
 			{ editsAllowed: false },
 		);

electron/ai-edition/agent-tools.ts

@@ -425,7 +425,7 @@ export const addTrimsArgs = z.object({
 	ranges: z.array(z.union([addTrimArgs, z.unknown()])).min(1),
 });
 
-export const removeFillerWordsArgs = z.object({
+export const removeWordsArgs = z.object({
 	assetId: z.string().min(1).optional(),
 	wordIds: z.array(z.string().min(1)).min(1),
 });
@@ -625,7 +625,7 @@ export const OPENSCREEN_TOOL_NAMES = [
 	"getTranscriptWords",
 	"getCursorTrack",
 	"setWordText",
-	"removeFillerWords",
+	"removeWords",
 	"addTrim",
 	"addTrims",
 	"setTrim",
@@ -697,7 +697,7 @@ export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set([
 	// Writes the transcript, not the timeline — but it writes the document, so it is a
 	// consented edit like any other.
 	"setWordText",
-	"removeFillerWords",
+	"removeWords",
 	"addTrim",
 	"addTrims",
 	"addZooms",
@@ -1527,8 +1527,8 @@ export function executeAgentTool(
 			};
 		}
 
-		case "removeFillerWords": {
-			const parsed = removeFillerWordsArgs.safeParse(args);
+		case "removeWords": {
+			const parsed = removeWordsArgs.safeParse(args);
 			if (!parsed.success) return failure(parsed.error.message);
 			const { assetId: selectedAssetId, wordIds } = parsed.data;
 			if (new Set(wordIds).size !== wordIds.length) {
@@ -1549,6 +1549,7 @@ export function executeAgentTool(
 				text: string;
 				assetId: string;
 				clipId: string;
+				index: number;
 				startSec: number;
 				endSec: number;
 			}> = [];
@@ -1558,9 +1559,9 @@ export function executeAgentTool(
 						(transcript) => selectedAssetId === undefined || transcript.assetId === selectedAssetId,
 					)
 					.flatMap((transcript) =>
-						transcript.words
-							.filter((word) => word.id === wordId)
-							.map((word) => ({ assetId: transcript.assetId, word })),
+						transcript.words.flatMap((word, index) =>
+							word.id === wordId ? [{ assetId: transcript.assetId, word, index }] : [],
+						),
 					);
 				if (matches.length !== 1) {
 					return failure(
@@ -1569,7 +1570,7 @@ export function executeAgentTool(
 							: `Word ID ${wordId} appears more than once in the transcripts. Pass the assetId used for getTranscriptWords. Nothing was modified.`,
 					);
 				}
-				const { assetId, word } = matches[0];
+				const { assetId, word, index } = matches[0];
 				const asset = document.assets.find((candidate) => candidate.id === assetId);
 				if (!asset || isGeneratedAssetId(assetId) || word.source === "synth") {
 					return failure(`Word ${wordId} has no recorded source asset. Nothing was modified.`);
@@ -1609,61 +1610,88 @@ export function executeAgentTool(
 				) {
 					return failure(`Word ${wordId} is already cut by a trim. Nothing was modified.`);
 				}
-				selected.push({ wordId, text: word.text, assetId, clipId: clip.id, startSec, endSec });
+				selected.push({
+					wordId,
+					text: word.text,
+					assetId,
+					clipId: clip.id,
+					index,
+					startSec,
+					endSec,
+				});
+			}
+
+			// Words that follow one another in the transcript go out as ONE cut: a phrase or a
+			// flubbed take cut word by word would leave the gaps between its words playing.
+			selected.sort((a, b) => a.assetId.localeCompare(b.assetId) || a.index - b.index);
+			const runs: Array<typeof selected> = [];
+			for (const word of selected) {
+				const last = runs.at(-1)?.at(-1);
+				if (
+					last?.assetId === word.assetId &&
+					last.clipId === word.clipId &&
+					last.index + 1 === word.index
+				) {
+					runs.at(-1)?.push(word);
+				} else {
+					runs.push([word]);
+				}
 			}
 
 			let current = document;
 			const removed: Array<Record<string, unknown>> = [];
-			for (const word of selected) {
+			for (const run of runs) {
+				const first = run[0];
+				const ids = run.map((word) => word.wordId).join(", ");
 				const execution = executeAgentTool(
 					current,
 					"addTrim",
 					JSON.stringify({
-						assetId: word.assetId,
-						clipId: word.clipId,
-						startSec: word.startSec,
-						endSec: word.endSec,
-						reason: "filler word",
+						assetId: first.assetId,
+						clipId: first.clipId,
+						startSec: first.startSec,
+						endSec: run[run.length - 1].endSec,
+						reason: "removed words",
 					}),
 					options,
 				);
 				if (!execution.ok || !execution.document) {
-					return failure(
-						`Could not cut word ${word.wordId}: ${execution.resultJson}. Nothing was modified.`,
-					);
+					return failure(`Could not cut ${ids}: ${execution.resultJson}. Nothing was modified.`);
 				}
 				const { trimRangeId } = JSON.parse(execution.resultJson) as { trimRangeId: string };
 				const trim = execution.document.timeline.trimRanges.find(
 					(range) => range.id === trimRangeId,
 				);
-				const clip = current.timeline.clips.find((candidate) => candidate.id === word.clipId);
-				const asset = current.assets.find((candidate) => candidate.id === word.assetId);
+				const clip = current.timeline.clips.find((candidate) => candidate.id === first.clipId);
+				const asset = current.assets.find((candidate) => candidate.id === first.assetId);
 				const clipEnd = clip?.sourceEndSec ?? asset?.durationSec;
 				if (
 					!trim ||
 					!clip ||
 					clipEnd === undefined ||
-					trim.clipId !== word.clipId ||
+					trim.clipId !== first.clipId ||
 					!Number.isFinite(trim.startSec) ||
 					!Number.isFinite(trim.endSec) ||
 					trim.startSec < clip.sourceStartSec ||
 					trim.endSec > clipEnd ||
 					trim.endSec <= trim.startSec
 				) {
-					return failure(`Cut for word ${word.wordId} left its clip. Nothing was modified.`);
+					return failure(`Cut for ${ids} left its clip. Nothing was modified.`);
 				}
 				current = execution.document;
-				removed.push({
-					wordId: word.wordId,
-					text: word.text,
-					assetId: word.assetId,
-					clipId: word.clipId,
-					wordStartSec: word.startSec,
-					wordEndSec: word.endSec,
-					trimRangeId,
-					startSec: trim.startSec,
-					endSec: trim.endSec,
-				});
+				for (const word of run) {
+					removed.push({
+						wordId: word.wordId,
+						text: word.text,
+						assetId: word.assetId,
+						clipId: word.clipId,
+						wordStartSec: word.startSec,
+						wordEndSec: word.endSec,
+						trimRangeId,
+						startSec: trim.startSec,
+						endSec: trim.endSec,
+					});
+				}
 			}
 			return {
 				ok: true,
@@ -1674,7 +1702,7 @@ export function executeAgentTool(
 					removed,
 					...cutTransitionsReport(document, current),
 				}),
-				summary: `removed ${removed.length} filler word${removed.length === 1 ? "" : "s"}`,
+				summary: `removed ${removed.length} word${removed.length === 1 ? "" : "s"}`,
 			};
 		}
 

electron/ai-edition/deep-agent/service.test.ts

@@ -60,7 +60,7 @@ const ARGS: Record<string, unknown> = {
 	getTranscriptWords: {},
 	getCursorTrack: {},
 	setWordText: { wordId: "word_1", text: "Hullo" },
-	removeFillerWords: { wordIds: ["word_1"] },
+	removeWords: { wordIds: ["word_1"] },
 	addTrim: { startSec: 1, endSec: 2 },
 	addTrims: { ranges: [{ startSec: 1, endSec: 2 }] },
 	setTrim: { trimRangeId: "trim_1", startSec: 1, endSec: 2 },