@clubnet/seedclub 0.2.21 → 0.2.23

package/assets/extensions/seedclub/commands/transcript-intent.ts

@@ -1,9 +1,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, extname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { api } from "../api-client.js";
+import { makeProgressCallRenderer, makeProgressResultRenderer } from "../tool-utils.js";
 import { getSessionContext } from "../tools/utility.js";
 
 interface ProgramSummary {
@@ -14,6 +15,7 @@ interface ProgramSummary {
 
 interface TranscriptIntent {
 	person?: string;
+	people?: string[];
 	date?: string;
 	time?: string;
 	outDir?: string;
@@ -27,6 +29,7 @@ interface TranscriptCandidate {
 	eventDate: string;
 	person: string;
 	vtt: string;
+	vttMode?: "native" | "generated_from_text";
 	videoUrl?: string | null;
 	audioUrl?: string | null;
 	fileNameHint?: string | null;
@@ -173,6 +176,18 @@ function isLikelyTranscriptRequest(input: string) {
 	);
 }
 
+function isExplicitTranscriptExportRequest(input: string) {
+	const text = normalizeWhitespace(input).toLowerCase();
+	if (!text || text.startsWith("/")) return false;
+	if (!hasTranscriptArtifactWord(text)) return false;
+	if (isTranscriptInventoryQuestion(text)) return false;
+
+	const hasExportVerb = /\b(download|export|save|write|pull|grab)\b/.test(text);
+	const hasPathHint = /(?:^|\s)(~\/|\/[^\s]+|downloads?\/|desktop\/)/.test(text);
+	const shortArtifactPrompt = /\b(today(?:'s|s)?|yesterday(?:'s|s)?|tomorrow(?:'s|s)?|recent|latest|\d{1,2}(?::\d{2})?\s*(?:am|pm))\b/.test(text);
+	return hasExportVerb || hasPathHint || shortArtifactPrompt;
+}
+
 function trimQuotes(value: string) {
 	return value.replace(/^['\"]|['\"]$/g, "");
 }
@@ -296,6 +311,14 @@ function parseIntent(input: string): TranscriptIntent {
 	const text = normalizeWhitespace(input);
 	const intent: TranscriptIntent = {};
 
+	const betweenPair = text.match(/\bbetween\s+([\w'. -]{2,80}?)\s*(?:and|&)\s*([\w'. -]{2,80}?)(?=\s+(?:from|on|in|at|for|transcripts?|vtt|interviews?|calls?|meetings?|date|to)\b|[?.!,]|$)/i);
+	if (betweenPair?.[1] && betweenPair?.[2]) {
+		const first = normalizePersonQuery(betweenPair[1]);
+		const second = normalizePersonQuery(betweenPair[2]);
+		const people = [first, second].filter((value): value is string => !!value);
+		if (people.length) intent.people = Array.from(new Set(people));
+	}
+
 	const personWith = text.match(/\bwith\s+([\w'. -]{2,80}?)(?=\s+(?:from|on|in|at|for|transcripts?|vtt|interviews?|calls?|meetings?|date|to)\b|$)/i);
 	if (personWith?.[1]) intent.person = normalizePersonQuery(personWith[1]);
 
@@ -314,6 +337,10 @@ function parseIntent(input: string): TranscriptIntent {
 		}
 	}
 
+	if ((!intent.people || !intent.people.length) && intent.person) {
+		intent.people = [intent.person];
+	}
+
 	const latestN = text.match(/\b(?:last|latest|most recent)\s+(\d{1,2})\b/i);
 	if (latestN?.[1]) {
 		intent.latestCount = Math.max(1, Math.min(20, Number.parseInt(latestN[1], 10)));
@@ -324,6 +351,9 @@ function parseIntent(input: string): TranscriptIntent {
 	}
 
 	intent.date = parseDateHint(text);
+	if ((intent.people?.length ?? 0) > 1 && /\b(?:both|between|across|and|&)\b/i.test(text)) {
+		intent.date = undefined;
+	}
 
 	const explicitTimeMatch = text.match(/\b(?:at|time)\s+(\d{1,2}(?::\d{2})?\s*(?:am|pm)|(?:[01]?\d|2[0-3]):[0-5]\d)\b/i);
 	const bareTimeMatch = text.match(/\b((?:[1-9]|1[0-2])(?::\d{2})?\s*(?:am|pm)|(?:[01]?\d|2[0-3]):[0-5]\d)\b/i);
@@ -344,7 +374,8 @@ function resolveOutputDir(programSlug: string, requested?: string): string {
 		const raw = requested.replace(/^~(?=$|\/)/, homedir());
 		return resolve(raw);
 	}
-	return join(homedir(), "Downloads", "seedclub", "transcripts", programSlug);
+	const safeProgram = sanitizeFilePart(programSlug || "", "transcripts");
+	return join(homedir(), "Downloads", safeProgram || "transcripts");
 }
 
 function sanitizeFilePart(value: string, fallback: string) {
@@ -357,6 +388,17 @@ function sanitizeFilePart(value: string, fallback: string) {
 	return normalized || fallback;
 }
 
+function hasNamedPerson(value: string | null | undefined) {
+	if (typeof value !== "string") return false;
+	const normalized = value.trim().toLowerCase();
+	if (!normalized) return false;
+	return !["unassigned", "unknown", "unknown guest"].includes(normalized);
+}
+
+function hasTranscriptSourceRef(candidate: TranscriptCandidate) {
+	return !!(candidate.assetId || candidate.meetingId);
+}
+
 function parseTimeFilter(input?: string): { hour: number; minute?: number } | null {
 	if (!input) return null;
 	const value = input.trim().toLowerCase();
@@ -449,17 +491,93 @@ function exactNormalizedTextMatch(query: string, target: string) {
 	return t.includes(q);
 }
 
-function ensureVtt(asset: any): string | null {
-	const candidates = [asset?.transcript_edited, asset?.transcript_vtt];
+function normalizeTranscriptText(value: string): string {
+	return value.replace(/\r\n/g, "\n").trim();
+}
+
+function isLikelyVtt(value: string): boolean {
+	const text = value.trim();
+	if (!text) return false;
+	return /^WEBVTT\b/i.test(text) || /\d{2}:\d{2}:\d{2}[\.,]\d{3}\s+-->\s+\d{2}:\d{2}:\d{2}[\.,]\d{3}/.test(text);
+}
+
+function toTimestamp(totalSeconds: number): string {
+	const ms = Math.max(0, Math.floor(totalSeconds * 1000));
+	const h = Math.floor(ms / 3600000);
+	const m = Math.floor((ms % 3600000) / 60000);
+	const s = Math.floor((ms % 60000) / 1000);
+	const milli = ms % 1000;
+	return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}.${String(milli).padStart(3, "0")}`;
+}
+
+function textToSyntheticVtt(text: string): string | null {
+	const normalized = normalizeTranscriptText(text);
+	if (!normalized) return null;
+
+	const sections = normalized
+		.split(/\n\s*\n+/)
+		.map((value) => value.trim())
+		.filter(Boolean)
+		.slice(0, 500);
+	if (!sections.length) return null;
+
+	let cursor = 0;
+	const cues: string[] = [];
+	for (const section of sections) {
+		const charCount = section.length;
+		const duration = Math.max(2, Math.min(10, Math.ceil(charCount / 28)));
+		const start = toTimestamp(cursor);
+		const end = toTimestamp(cursor + duration);
+		cues.push(`${start} --> ${end}\n${section}`);
+		cursor += duration;
+	}
+
+	return `WEBVTT\n\n${cues.join("\n\n")}`;
+}
+
+function extractTranscriptText(obj: any): string | null {
+	const candidates = [
+		obj?.transcript_edited,
+		obj?.transcript_raw,
+		obj?.merged_text,
+		obj?.transcript_text,
+		obj?.merged_transcript,
+	];
 	for (const candidate of candidates) {
-		if (typeof candidate === "string" && candidate.trim()) return candidate;
+		if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
 	}
 	return null;
 }
 
-async function listCandidateAssets(programSlug: string, partyId?: string, eventDate?: string) {
+function resolveVttContent(source: any): { vtt: string; mode: "native" | "generated_from_text" } | null {
+	const explicitVtt = typeof source?.transcript_vtt === "string" ? source.transcript_vtt.trim() : "";
+	if (explicitVtt) return { vtt: explicitVtt, mode: "native" };
+
+	const mergedVtt = typeof source?.merged_vtt === "string" ? source.merged_vtt.trim() : "";
+	if (mergedVtt) return { vtt: mergedVtt, mode: "native" };
+
+	const maybeVtt = extractTranscriptText(source);
+	if (typeof maybeVtt === "string" && maybeVtt.trim()) {
+		if (isLikelyVtt(maybeVtt)) return { vtt: maybeVtt.trim(), mode: "native" };
+		const generated = textToSyntheticVtt(maybeVtt);
+		if (generated) return { vtt: generated, mode: "generated_from_text" };
+	}
+
+	return null;
+}
+
+function ensureVtt(asset: any): string | null {
+	return resolveVttContent(asset)?.vtt ?? null;
+}
+
+async function listCandidateAssets(
+	programSlug: string,
+	partyId?: string,
+	eventDate?: string,
+	assetKind: "full_conversation" | "clip" = "full_conversation",
+) {
 	const response = await api.get<any>(`/programs/${programSlug}/media/assets`, {
-		asset_kind: "full_conversation",
+		asset_kind: assetKind,
 		party_id: partyId,
 		event_date: eventDate,
 	});
@@ -515,16 +633,6 @@ function applyLatestFilter<T>(rows: T[], latestCount: number | undefined, sortFn
 	return sorted.slice(0, latestCount);
 }
 
-function filterAssetsByPersonText(assets: any[], personQuery?: string) {
-	if (!personQuery?.trim()) return assets;
-	return assets.filter((asset) => {
-		const haystack = [asset?.title, asset?.key_question, asset?.file_name]
-			.filter((v) => typeof v === "string" && v.trim())
-			.join(" ");
-		return exactNormalizedTextMatch(personQuery, haystack);
-	});
-}
-
 function personFromMeetingTitle(title?: string | null): string | null {
 	if (!title || typeof title !== "string") return null;
 	const cleaned = title.replace(/\s+on\s+11am$/i, "").trim();
@@ -532,8 +640,8 @@ function personFromMeetingTitle(title?: string | null): string | null {
 }
 
 function toCandidateFromAsset(asset: any, fallbackPerson: string): TranscriptCandidate | null {
-	const vtt = ensureVtt(asset);
-	if (!vtt) return null;
+	const resolvedVtt = resolveVttContent(asset);
+	if (!resolvedVtt) return null;
 	const eventDate = pickDate(asset);
 	return {
 		source: "full_conversation_asset",
@@ -541,7 +649,8 @@ function toCandidateFromAsset(asset: any, fallbackPerson: string): TranscriptCan
 		meetingId: asset?.meeting_id ?? null,
 		eventDate,
 		person: pickPersonName(asset, fallbackPerson),
-		vtt,
+		vtt: resolvedVtt.vtt,
+		vttMode: resolvedVtt.mode,
 		videoUrl: asset?.storage_url ?? null,
 		audioUrl: asset?.audio_url ?? null,
 		fileNameHint: asset?.file_name ?? null,
@@ -561,7 +670,8 @@ async function listFallbackTranscriptCandidates(programSlug: string, intent: Tra
 		rows = rows.filter((row: any) => row?.transcript?.event_date === intent.date);
 	}
 
-	if (intent.person?.trim()) {
+	const peopleQueries = Array.from(new Set([...(intent.people ?? []), ...(intent.person ? [intent.person] : [])].filter(Boolean)));
+	if (peopleQueries.length) {
 		const personFiltered = rows.filter((row: any) => {
 			const haystack = [
 				row?.meeting?.title,
@@ -570,7 +680,7 @@ async function listFallbackTranscriptCandidates(programSlug: string, intent: Tra
 			]
 				.filter((v: unknown) => typeof v === "string" && v.trim())
 				.join(" ");
-			return exactNormalizedTextMatch(intent.person!, haystack);
+			return peopleQueries.some((query) => exactNormalizedTextMatch(query, haystack));
 		});
 		if (personFiltered.length) {
 			rows = personFiltered;
@@ -594,8 +704,8 @@ async function listFallbackTranscriptCandidates(programSlug: string, intent: Tra
 
 	const candidates: TranscriptCandidate[] = [];
 	for (const row of rows) {
-		const vtt = typeof row?.transcript?.merged_vtt === "string" ? row.transcript.merged_vtt.trim() : "";
-		if (!vtt) continue;
+		const resolvedVtt = resolveVttContent(row?.transcript ?? {});
+		if (!resolvedVtt) continue;
 		const eventDate = typeof row?.transcript?.event_date === "string" ? row.transcript.event_date : new Date().toISOString().slice(0, 10);
 		const person = pickPersonFromTranscriptRow(row, intent.person?.trim() || "unassigned");
 		const sortTimestamp = /^\d{4}-\d{2}-\d{2}$/.test(eventDate)
@@ -607,7 +717,8 @@ async function listFallbackTranscriptCandidates(programSlug: string, intent: Tra
 			meetingId: row?.transcript?.meeting_id ?? row?.meeting?.id ?? null,
 			eventDate,
 			person,
-			vtt,
+			vtt: resolvedVtt.vtt,
+			vttMode: resolvedVtt.mode,
 			videoUrl: null,
 			audioUrl: null,
 			fileNameHint: null,
@@ -655,14 +766,6 @@ function pickPersonFromTranscriptRow(row: any, fallback: string): string {
 	return "unassigned";
 }
 
-function pickVideoFileName(asset: any): string {
-	const fileName = typeof asset?.file_name === "string" ? asset.file_name.trim() : "";
-	if (fileName) return fileName;
-	const fromUrl = typeof asset?.storage_url === "string" ? basename(asset.storage_url.split("?")[0] || "") : "";
-	if (fromUrl) return fromUrl;
-	return `${sanitizeFilePart(asset?.id || "video", "video")}.mp4`;
-}
-
 function toFileUri(path: string) {
 	const normalized = path.replace(/\\/g, "/");
 	return `file://${encodeURI(normalized)}`;
@@ -689,19 +792,52 @@ function buildTranscriptDownloadSummary(manifest: Array<Record<string, unknown>>
 		.join("\n");
 }
 
-function buildTranscriptCandidateSummary(candidates: TranscriptCandidate[], outDir: string) {
-	const rows = candidates.slice(0, 10).map((candidate) => {
+function planCandidateFileNames(candidates: TranscriptCandidate[]) {
+	const used = new Set<string>();
+	return candidates.map((candidate) => {
+		const safePerson = sanitizeFilePart(candidate.person, "unassigned");
+		const safeMeeting = sanitizeFilePart(candidate.meetingId || "no-meeting", "no-meeting");
+		const baseName = `${candidate.eventDate}__${safePerson}__${safeMeeting}`;
+		let fileName = `${baseName}.vtt`;
+		let suffix = 2;
+		while (used.has(fileName)) {
+			fileName = `${baseName}__${suffix}.vtt`;
+			suffix += 1;
+		}
+		used.add(fileName);
+		return { candidate, fileName };
+	});
+}
+
+function buildExportBatchFolderName(planned: Array<{ candidate: TranscriptCandidate; fileName: string }>) {
+	if (!planned.length) return "batch";
+	if (planned.length === 1) {
+		const row = planned[0].candidate;
+		const safePerson = sanitizeFilePart(row.person || "guest", "guest");
+		const safeDate = sanitizeFilePart(row.eventDate || "date", "date");
+		return `${safePerson}&${safeDate}`;
+	}
+
+	const dates = Array.from(new Set(planned.map((row) => row.candidate.eventDate).filter(Boolean))).sort();
+	const firstDate = dates[0] ?? "date";
+	const lastDate = dates[dates.length - 1] ?? firstDate;
+	const datePart = firstDate === lastDate ? firstDate : `${firstDate}_to_${lastDate}`;
+	return `batch--${sanitizeFilePart(datePart, "range")}--${planned.length}`;
+}
+
+function buildTranscriptCandidateSummary(planned: Array<{ candidate: TranscriptCandidate; fileName: string }>, outDir: string) {
+	const rows = planned.slice(0, 10).map(({ candidate, fileName }) => {
 		const date = candidate.eventDate || "unknown date";
 		const person = candidate.person || "Unknown guest";
-		return `- ${date} - ${person}`;
+		return `- ${date} - ${person} -> ${fileName}`;
 	});
 
-	if (candidates.length > rows.length) {
-		rows.push(`- ...and ${candidates.length - rows.length} more`);
+	if (planned.length > rows.length) {
+		rows.push(`- ...and ${planned.length - rows.length} more`);
 	}
 
 	return [
-		`Found ${candidates.length} transcript file${candidates.length === 1 ? "" : "s"}.`,
+		`Found ${planned.length} transcript file${planned.length === 1 ? "" : "s"}.`,
 		rows.length ? rows.join("\n") : null,
 		`Download to ${outDir}?`,
 	]
@@ -721,19 +857,12 @@ async function openPathWithSystem(agent: ExtensionAPI, targetPath: string) {
 	await agent.exec("xdg-open", [targetPath]);
 }
 
-async function offerOpenDownloadedPath(
-	agent: ExtensionAPI,
-	ctx: any,
-	outDir: string,
-	manifestPath: string,
-	videoDir?: string,
-) {
-	const options = ["Open folder", "Open index.json", ...(videoDir ? ["Open videos folder"] : []), "Done"];
+async function offerOpenDownloadedPath(agent: ExtensionAPI, ctx: any, outDir: string, videoDir?: string) {
+	const options = ["Open folder", ...(videoDir ? ["Open videos folder"] : []), "Done"];
 	const choice = await ctx.ui.select(`Transcripts saved to ${outDir}`, options);
 	if (!choice || choice === "Done") return;
 
-	const target =
-		choice === "Open folder" ? outDir : choice === "Open index.json" ? manifestPath : videoDir || outDir;
+	const target = choice === "Open folder" ? outDir : videoDir || outDir;
 	try {
 		await openPathWithSystem(agent, target);
 	} catch {
@@ -741,51 +870,6 @@ async function offerOpenDownloadedPath(
 	}
 }
 
-async function maybeDownloadVideos(
-	ctx: any,
-	candidates: TranscriptCandidate[],
-	outDir: string,
-	manifest: Array<Record<string, unknown>>,
-): Promise<string | null> {
-	const downloadable = candidates.filter((item) => typeof item.videoUrl === "string" && item.videoUrl.trim());
-	if (!downloadable.length) return null;
-
-	const choice = await ctx.ui.select(`Also download ${downloadable.length} full video file(s)?`, [
-		"Download videos",
-		"Skip",
-	]);
-	if (choice !== "Download videos") {
-		ctx.ui.notify(
-			`${buildTranscriptDownloadSummary(manifest, outDir)}\n\nSkipped video download. Say 'download the videos too' if you want them next.`,
-			"info",
-		);
-		return null;
-	}
-
-	const videoDir = join(outDir, "videos");
-	await mkdir(videoDir, { recursive: true });
-
-	for (const candidate of downloadable) {
-		const url = String(candidate.videoUrl);
-		const originalName = pickVideoFileName({ file_name: candidate.fileNameHint, storage_url: candidate.videoUrl, id: candidate.assetId });
-		const ext = extname(originalName) || ".mp4";
-		const stem = sanitizeFilePart(originalName.replace(ext, ""), "video");
-		const filePath = join(videoDir, `${stem}${ext}`);
-
-		ctx.ui.notify(`Downloading video: ${originalName}`, "info");
-		const response = await fetch(url);
-		if (!response.ok) {
-			ctx.ui.notify(`Failed to download ${originalName}: HTTP ${response.status}`, "warning");
-			continue;
-		}
-		const bytes = Buffer.from(await response.arrayBuffer());
-		await writeFile(filePath, bytes);
-	}
-
-	ctx.ui.notify(`${buildTranscriptDownloadSummary(manifest, outDir)}\n\nVideos saved to ${videoDir}`, "info");
-	return videoDir;
-}
-
 async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args: TranscriptExportArgs) {
 	const request = args.request?.trim();
 	if (!request) {
@@ -827,15 +911,29 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 		};
 	}
 
-	ctx.ui.notify(`Looking up full-conversation VTT files in ${program.slug}...`, "info");
-	let assets = await listCandidateAssets(program.slug, args.partyId, intent.date);
-	assets = await filterByMeetingTime(assets, intent.time);
-	assets = assets.filter((asset) => !!ensureVtt(asset));
-	if (intent.person && !args.partyId) {
-		const personFilteredAssets = filterAssetsByPersonText(assets, intent.person);
-		if (personFilteredAssets.length) {
-			assets = personFilteredAssets;
+	const filterAssetsForIntent = async (inputAssets: any[]) => {
+		let filtered = await filterByMeetingTime(inputAssets, intent.time);
+		filtered = filtered.filter((asset) => !!ensureVtt(asset));
+		if (!args.partyId) {
+			const peopleQueries = Array.from(new Set([...(intent.people ?? []), ...(intent.person ? [intent.person] : [])].filter(Boolean)));
+			if (peopleQueries.length) {
+				const personFilteredAssets = filtered.filter((asset) => {
+					const haystack = [asset?.title, asset?.key_question, asset?.file_name]
+						.filter((v) => typeof v === "string" && v.trim())
+						.join(" ");
+					return peopleQueries.some((query) => exactNormalizedTextMatch(query, haystack));
+				});
+				if (personFilteredAssets.length) filtered = personFilteredAssets;
+			}
 		}
+		return filtered;
+	};
+
+	ctx.ui.notify(`Looking up full-conversation VTT files in ${program.slug}...`, "info");
+	let assets = await filterAssetsForIntent(await listCandidateAssets(program.slug, args.partyId, intent.date, "full_conversation"));
+	if (!assets.length) {
+		ctx.ui.notify(`No full-conversation VTT found. Checking clip transcript text to generate VTT in ${program.slug}...`, "info");
+		assets = await filterAssetsForIntent(await listCandidateAssets(program.slug, args.partyId, intent.date, "clip"));
 	}
 
 	let candidates = assets
@@ -845,7 +943,7 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 	candidates = applyLatestFilter(candidates, intent.latestCount, (row) => row.sortTimestamp);
 
 	if (!candidates.length) {
-		ctx.ui.notify("No matching full-conversation VTT files found. Checking meeting transcript rows...", "info");
+		ctx.ui.notify("No matching asset transcript content found. Checking meeting transcript rows...", "info");
 		candidates = await listFallbackTranscriptCandidates(program.slug, intent);
 	}
 
@@ -860,10 +958,39 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 		};
 	}
 
-	const outDir = resolveOutputDir(program.slug, intent.outDir);
+	const unresolvedSource = candidates.filter((candidate) => !hasTranscriptSourceRef(candidate));
+	const unresolvedPerson = candidates.filter((candidate) => !hasNamedPerson(candidate.person));
+
+	if (unresolvedSource.length || unresolvedPerson.length) {
+		const unresolvedRows = candidates
+			.filter((candidate) => !hasTranscriptSourceRef(candidate) || !hasNamedPerson(candidate.person))
+			.slice(0, 5)
+			.map((candidate) => {
+				const sourceRef = hasTranscriptSourceRef(candidate) ? "ok" : "missing-source";
+				const personRef = hasNamedPerson(candidate.person) ? "ok" : "missing-person";
+				return `- ${candidate.eventDate} :: ${candidate.person || "unknown"} [${sourceRef}; ${personRef}]`;
+			})
+			.join("\n");
+
+		const message = `Strict transcript export guard blocked this download. ${
+			unresolvedSource.length
+		} row(s) are missing source reference (assetId/meetingId), and ${unresolvedPerson.length} row(s) are missing a named person.`;
+		ctx.ui.notify(`${message}${unresolvedRows ? `\n${unresolvedRows}` : ""}`, "warning");
+		return {
+			program: program.slug,
+			request,
+			count: 0,
+			files: [],
+			message,
+		};
+	}
+
+	const baseOutDir = resolveOutputDir(program.slug, intent.outDir);
+	const planned = planCandidateFileNames(candidates);
+	const outDir = intent.outDir ? baseOutDir : join(baseOutDir, buildExportBatchFolderName(planned));
 	if (!intent.outDir && ctx.hasUI !== false) {
 		const choice = await ctx.ui.select(
-			buildTranscriptCandidateSummary(candidates, outDir),
+			buildTranscriptCandidateSummary(planned, outDir),
 			["Download", "Cancel"],
 		);
 		if (choice !== "Download") {
@@ -871,7 +998,7 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 				program: program.slug,
 				request,
 				cancelled: true,
-				count: candidates.length,
+				count: planned.length,
 				files: [],
 				message: "Transcript download cancelled.",
 			};
@@ -880,21 +1007,9 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 
 	await mkdir(outDir, { recursive: true });
 
-	const used = new Set<string>();
 	const manifest: Array<Record<string, unknown>> = [];
 
-	for (const candidate of candidates) {
-		const safePerson = sanitizeFilePart(candidate.person, "unassigned");
-		const safeMeeting = sanitizeFilePart(candidate.meetingId || "no-meeting", "no-meeting");
-		const baseName = `${candidate.eventDate}__${safePerson}__${safeMeeting}`;
-		let fileName = `${baseName}.vtt`;
-		let suffix = 2;
-		while (used.has(fileName)) {
-			fileName = `${baseName}__${suffix}.vtt`;
-			suffix += 1;
-		}
-		used.add(fileName);
-
+	for (const { candidate, fileName } of planned) {
 		await writeFile(join(outDir, fileName), candidate.vtt, "utf8");
 		manifest.push({
 			file: fileName,
@@ -903,6 +1018,7 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 			meetingId: candidate.meetingId ?? null,
 			eventDate: candidate.eventDate,
 			person: candidate.person,
+			vttMode: candidate.vttMode ?? "native",
 			videoUrl: candidate.videoUrl ?? null,
 			audioUrl: candidate.audioUrl ?? null,
 		});
@@ -919,21 +1035,25 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 		};
 	}
 
-	const manifestPath = join(outDir, "index.json");
-	await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
-
+	const generatedCount = manifest.filter((row: any) => row?.vttMode === "generated_from_text").length;
 	const summary = buildTranscriptDownloadSummary(manifest, outDir);
-	ctx.ui.notify(summary, "info");
+	ctx.ui.notify(
+		generatedCount > 0
+			? `${summary}\n\nGenerated ${generatedCount} VTT file${generatedCount === 1 ? "" : "s"} from transcript text.`
+			: summary,
+		"info",
+	);
 
-	const videoDir = ctx.hasUI === false ? null : await maybeDownloadVideos(ctx, candidates, outDir, manifest);
-	if (ctx.hasUI !== false) await offerOpenDownloadedPath(agent, ctx, outDir, manifestPath, videoDir ?? undefined);
+	if (ctx.hasUI !== false) await offerOpenDownloadedPath(agent, ctx, outDir);
+	const downloadableVideoCount = candidates.filter((item) => typeof item.videoUrl === "string" && item.videoUrl.trim()).length;
 
 	return {
 		program: program.slug,
 		request,
 		outDir,
-		manifestPath,
-		videoDir,
+		manifestPath: null,
+		videoDir: null,
+		downloadableVideoCount,
 		count: manifest.length,
 		files: manifest,
 		message: summary,
@@ -941,6 +1061,22 @@ async function exportTranscriptsForRequest(agent: ExtensionAPI, ctx: any, args:
 }
 
 export function registerTranscriptIntentInterceptor(pi: ExtensionAPI) {
+	let exportSucceededThisTurn = false;
+	let exportSucceededWithoutPersonThisTurn = false;
+	const successfulPersonKeys = new Set<string>();
+	const pendingExportArgs = new Map<string, { programSlug: string; person: string }>();
+
+	const resetExportGuardState = () => {
+		exportSucceededThisTurn = false;
+		exportSucceededWithoutPersonThisTurn = false;
+		successfulPersonKeys.clear();
+		pendingExportArgs.clear();
+	};
+
+	pi.on("turn_start", () => {
+		resetExportGuardState();
+	});
+
 	pi.registerTool({
 		name: "seedclub_export_transcripts",
 		label: "Export Transcripts",
@@ -953,9 +1089,14 @@ export function registerTranscriptIntentInterceptor(pi: ExtensionAPI) {
 			person: Type.Optional(Type.String({ description: "Optional exact guest/person text confirmed before calling this tool." })),
 			date: Type.Optional(Type.String({ description: "Optional event date in YYYY-MM-DD format." })),
 			time: Type.Optional(Type.String({ description: "Optional time qualifier, e.g. 2pm or 14:00." })),
-			outDir: Type.Optional(Type.String({ description: "Optional output directory. Defaults to ~/Downloads/seedclub/transcripts/<program-slug>/." })),
+			outDir: Type.Optional(Type.String({ description: "Optional output directory. Defaults to ~/Downloads/<program-slug>/ with a per-request subfolder." })),
 			latestCount: Type.Optional(Type.Number({ description: "Optional latest-result count, max 20." })),
 		}),
+		renderCall: makeProgressCallRenderer("Exporting transcript files", (args) => args?.programSlug || args?.person || args?.date || undefined),
+		renderResult: makeProgressResultRenderer("Transcript export complete", (details) => {
+			const count = typeof details?.count === "number" ? details.count : 0;
+			return `${count} file${count === 1 ? "" : "s"}`;
+		}),
 		execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
 			try {
 				const result = await exportTranscriptsForRequest(pi, ctx, params);
@@ -966,9 +1107,24 @@ export function registerTranscriptIntentInterceptor(pi: ExtensionAPI) {
 						isError: true,
 					};
 				}
+				const previewFiles = Array.isArray((result as any).files)
+					? (result as any).files.slice(0, 8).map((row: any) => row?.file).filter(Boolean)
+					: [];
 				return {
 					content: [{ type: "text" as const, text: result.message }],
-					details: result,
+					details: {
+						program: (result as any).program ?? null,
+						request: (result as any).request ?? null,
+						outDir: (result as any).outDir ?? null,
+						manifestPath: (result as any).manifestPath ?? null,
+						videoDir: (result as any).videoDir ?? null,
+						downloadableVideoCount: (result as any).downloadableVideoCount ?? 0,
+						count: (result as any).count ?? 0,
+						cancelled: (result as any).cancelled === true,
+						filesPreview: previewFiles,
+						moreFiles: Math.max(0, ((result as any).count ?? 0) - previewFiles.length),
+						message: (result as any).message ?? null,
+					},
 				};
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
@@ -982,6 +1138,56 @@ export function registerTranscriptIntentInterceptor(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.on("tool_call", async (event) => {
+		if (event.toolName !== "seedclub_export_transcripts") return;
+		const request = typeof event.input?.request === "string" ? event.input.request : "";
+		if (!isExplicitTranscriptExportRequest(request)) {
+			return {
+				block: true,
+				reason:
+					"seedclub_export_transcripts is only for explicit transcript/VTT file download requests. Use transcript discovery/review tools for analysis or recap questions.",
+			};
+		}
+
+		const programSlug = typeof event.input?.programSlug === "string" ? event.input.programSlug.trim().toLowerCase() : "";
+		const personRaw = typeof event.input?.person === "string" ? event.input.person : "";
+		const personKey = normalizeFuzzyText(personRaw || "");
+		const scopedKey = `${programSlug}::${personKey}`;
+
+		if (exportSucceededWithoutPersonThisTurn) {
+			return {
+				block: true,
+				reason: "A transcript export already succeeded in this turn. Reuse the returned transcript instead of exporting again.",
+			};
+		}
+
+		if (exportSucceededThisTurn) {
+			if (!personKey || successfulPersonKeys.has(scopedKey)) {
+				return {
+					block: true,
+					reason: "Transcript already exported for this person in this turn.",
+				};
+			}
+		}
+
+		pendingExportArgs.set(event.toolCallId, { programSlug, person: personKey });
+	});
+
+	pi.on("tool_result", async (event) => {
+		if (event.toolName !== "seedclub_export_transcripts") return;
+		const pending = pendingExportArgs.get(event.toolCallId);
+		pendingExportArgs.delete(event.toolCallId);
+		if (event.isError) return;
+		const count = typeof (event.details as any)?.count === "number" ? (event.details as any).count : 0;
+		if (count <= 0) return;
+		exportSucceededThisTurn = true;
+		if (!pending?.person) {
+			exportSucceededWithoutPersonThisTurn = true;
+			return;
+		}
+		successfulPersonKeys.add(`${pending.programSlug}::${pending.person}`);
+	});
+
 	pi.on("before_agent_start", async (event) => {
 		if (!isLikelyTranscriptRequest(event.prompt)) return;
 		return {
@@ -992,6 +1198,9 @@ IMPORTANT SEED CLUB TRANSCRIPT EXPORT ROUTING:
 - Keep the user's prompt in normal conversation context.
 - If person/date/program constraints are not clear, ask or use metadata tools first; do not let seedclub_export_transcripts perform fuzzy disambiguation.
 - Prefer calling seedclub_export_transcripts only after the constraints are exact, with request set to the user's original prompt.
+- Avoid chaining high-payload media/transcript tools for export asks when seedclub_export_transcripts can satisfy the request.
+- For transcript export requests, download transcripts only in the tool. If videos are available, ask as a follow-up in chat instead of prompting inside the tool.
+- Once a transcript export succeeds for the identified person in this turn, stop calling transcript export again.
 - Do not answer by dumping transcript text or raw JSON into chat.`,
 		};
 	});