@lightcone-ai/daemon 0.19.0 → 0.21.0

package/mcp-servers/official/media-tools/index.js

@@ -272,16 +272,15 @@ server.tool(
 // tails, and re-records (Task #25/#26 trial).
 server.tool(
   'compose_video_v2',
-  'Compose a video from a list of segments using ffmpeg. Each segment has a visual source (image / scroll / '
-  + 'carousel / video / gif), optional audio, and optional subtitle text. Subtitles are burned in when '
-  + 'subtitle_text is provided AND burn_subtitles is not false. Segments are concatenated in order; outro clips are appended after.\n\n'
+  'Compose video(s) from a list of segments using ffmpeg. Each segment has a visual source (image / scroll / '
+  + 'carousel / video / gif), optional audio, and optional subtitle text. Segments are concatenated in order; '
+  + 'outro clips are appended after.\n\n'
   + 'When any segment has audio_path, MUST be preceded by plan_video_segments in the same session '
-  + '(plan_video_segments fills duration/subtitle_text/audio_path mechanically; manual alignment is rejected). '
-  + 'Returns a local mp4 path + size_bytes.\n\n'
-  + 'Dual / multi-version delivery (e.g. subtitled+voiced + clean silent): pass the variants[] array — one call '
-  + 'runs the heavy per-segment ffmpeg work ONCE and only diverges at audio mux + concat + subtitle burn per '
-  + 'variant. That is ~1.2-1.4× single-version time vs ~2× when calling this tool twice. Each variant chooses '
-  + 'its own burn_subtitles and include_audio independently.',
+  + '(plan_video_segments fills duration/subtitle_text/audio_path mechanically; manual alignment is rejected).\n\n'
+  + 'Outputs are controlled by variants[] — ALWAYS required. Single output is variants:[{output_path:"..."}]. '
+  + 'Multi-output (e.g. 字幕+配音 版 + 无声无字幕 clean 版) is variants:[{output_path:"sub.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}]. '
+  + 'The heavy per-segment ffmpeg work runs ONCE across all variants — only audio mux + concat + subtitle burn '
+  + 'repeat per variant. Two-variant delivery is ~1.2-1.4× single-variant time, not 2×.',
   {
     segments: z.array(z.object({
       visual_path: z.string().optional().describe('Absolute path to a single image / video / gif.'),
@@ -296,20 +295,15 @@ server.tool(
       subtitle_text: z.string().optional().describe('Narration text to burn as subtitle. Displayed for the full segment duration.'),
       transition: z.enum(['cut', 'fade', 'crossfade']).optional().describe('Transition to next segment. Default cut.'),
     })).describe('Ordered list of video segments.'),
-    outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end.'),
+    outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end (shared across all variants).'),
     resolution: z.string().optional().describe('Output resolution WxH. Default "1080x1920".'),
-    output_path: z.string().optional().describe('Absolute output path (single-output mode). Auto-generated if omitted. Ignored when variants[] is provided.'),
-    burn_subtitles: z.boolean().optional().describe('Single-output mode only: whether to burn subtitle_text. Default true. '
-      + 'For producing multiple variants in one call, use variants[] instead.'),
     variants: z.array(z.object({
       output_path: z.string().describe('Absolute output path for this variant. Each variant must use a unique path.'),
       burn_subtitles: z.boolean().optional().describe('Whether to burn subtitle_text into THIS variant. Default true.'),
       include_audio: z.boolean().optional().describe('Whether to mux segment.audio_path into THIS variant. Default true. '
-        + 'Pass false for a fully silent copy (skips audio mux entirely; segment.audio_path is ignored for this variant).'),
-    })).optional().describe('Multi-output mode: one call produces all variants. '
-      + 'Visual segment processing (the heavy work) runs once; each variant only repeats audio mux + concat + optional subtitle burn. '
-      + 'Typical use: [{output_path:"with-sub.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}] '
-      + 'to deliver a subtitled+voiced version and a silent clean version together.'),
+        + 'Pass false for a fully silent copy (segment.audio_path ignored for this variant).'),
+    })).min(1).describe('Required: one entry per output file. Single output = 1-element array. '
+      + 'Multi-output dual delivery example: [{output_path:"with-sub-voice.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}].'),
   },
   async (args) => {
     const segments = Array.isArray(args?.segments) ? args.segments : [];
@@ -348,7 +342,7 @@ server.tool(
 // audio in production runs (Tasks #20/#25/#26), forcing re-records.
 server.tool(
   'record_url_narration',
-  'Record a silent video of a URL by driving Chromium on an Xvfb display and capturing it with Playwright recordVideo, driven by a video plan; ffmpeg then transcodes the recording to mp4. Outputs a silent mp4 that can be passed to compose_video_v2 as a video-kind segment with an audio_path for narration.\n\nUse this as the canonical recording step for URL-narration videos. Falls back: if the page needs interactions outside the visual_action vocabulary (clicks, waits, OCR loops), use Monitor (Bash) with custom Playwright instead.\n\nMUST be preceded by plan_video_segments in the same session — feed plan_video_segments\'s `segments` array as `plan.sections` so dwell_ms aligns mechanically with TTS audio_duration_ms (hand-written dwell_ms has drifted and forced re-records in production).\n\nRuntime requirements: this tool only works on a Linux daemon machine with Xvfb + Chromium + ffmpeg installed (ffmpeg is used to transcode the recording to mp4; no x11grab device support needed). macOS / Windows daemons will fail at startup.',
+  'Record silent mp4s of a URL by driving Chromium on an Xvfb display and capturing it with Playwright recordVideo, then ffmpeg-transcoding. Each output mp4 can be passed to compose_video_v2 as a video-kind segment with an audio_path for narration.\n\nUse this as the canonical recording step for URL-narration videos. Falls back: if the page needs interactions outside the visual_action vocabulary (clicks, waits, OCR loops), use Monitor (Bash) with custom Playwright instead.\n\nMUST be preceded by plan_video_segments in the same session — feed plan_video_segments\'s `segments` array as `plan.sections` so dwell_ms aligns mechanically with TTS audio_duration_ms (hand-written dwell_ms has drifted and forced re-records in production).\n\nALWAYS pass output_paths as an array with one mp4 path per plan.sections entry (single-section recording is a 1-element array). The tool records the URL ONCE continuously (one browser session, one scrollTop, natural scroll flow through all sections), then slices the recording at section boundaries via ffmpeg. There is NO mode that records N sections in N separate calls — that pattern reopened the browser and re-scrolled-from-top for each segment, which looked visually disjointed. One URL = one call.\n\nRuntime requirements: this tool only works on a Linux daemon machine with Xvfb + Chromium + ffmpeg installed (ffmpeg is used to transcode the recording to mp4; no x11grab device support needed). macOS / Windows daemons will fail at startup.',
   {
     url: z.string().describe('Page URL to record'),
     plan: z.record(z.any()).describe(
@@ -367,8 +361,9 @@ server.tool(
       + 'frag.short.recruitment_url_mode_policy). Pick a different target_y in the 标题/岗位 '
       + 'information area and rewrite that section.'
     ),
-    output_path: z.string().optional().describe('Workspace-relative output mp4 path. Default tmp/wx3_video/recorded-{ts}.mp4'),
-    events_path: z.string().optional().describe('Workspace-relative events.json path. Default ${output_path}.events.json'),
+    output_paths: z.array(z.string()).min(1).describe('REQUIRED. Workspace-relative mp4 paths, one per plan.sections entry (single-section is a 1-element array). The tool records ONCE continuously and slices the result at section boundaries (derived from phase_start / phase_end events) — each section produces exactly one of these mp4s.'),
+    output_path: z.string().optional().describe('Optional debug-only path for the CONSOLIDATED master recording (the full continuous webm transcoded). Auto-generated under tmp/ if omitted. Agents normally do not need to set this — they consume output_paths.'),
+    events_path: z.string().optional().describe('Workspace-relative events.json path. Default ${master}.events.json'),
     viewport: z.object({
       width: z.number().optional(),
       height: z.number().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightcone-ai/daemon",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/_vendor/video/composer-v2/index.js

@@ -249,54 +249,41 @@ async function applyFadeTransition({ clipA, clipB, tmpDir, style = 'fade' }) {
   return outPath;
 }
 
-// compose_video_v2 supports two modes:
+// compose_video_v2 — ONE shape: caller passes variants[]. Single-output is
+// just variants of length 1. Multi-output (subtitled+voiced + clean silent)
+// is the same call with more variants. There is no top-level output_path or
+// burn_subtitles shortcut — it added a second pattern, and agents
+// consistently defaulted to the simpler one even when multi-output was
+// requested, so the dual-version optimization went unused.
 //
-//   1. Legacy single-output: pass output_path (+ optional burn_subtitles).
-//      Returns { path, duration_ms, size_bytes, variants: [..1 entry..] }.
-//
-//   2. Multi-variant: pass variants=[{output_path, burn_subtitles?, include_audio?}, ...].
-//      Visual segment processing runs ONCE (the heavy part — per-segment ffmpeg
-//      transcode/scale/scroll). Each variant then diverges only at audio mux +
-//      concat + subtitle burn — typically a few seconds per extra variant.
-//      Returns { variants: [{path, duration_ms, size_bytes, burn_subtitles,
-//      include_audio}, ...] }.
-//
-// Use the multi-variant mode when shipping the same content with different
-// subtitle/audio combinations (e.g. subtitled+voiced + clean silent). Calling
-// the legacy mode twice produces correct outputs but redoes per-segment work.
+// Visual segment processing runs ONCE; each variant diverges only at audio
+// mux + concat + subtitle burn (~seconds per extra variant).
 export async function composeVideoV2({
   segments = [],
   outro_paths = [],
   resolution = '1080x1920',
-  output_path,
-  burn_subtitles = true,
   variants,
 }) {
   if (!Array.isArray(segments) || segments.length === 0) {
     throw new Error('segments must be a non-empty array');
   }
 
-  // Normalize variants. If caller did not pass an explicit variants array,
-  // synthesize a single variant from the legacy output_path + burn_subtitles.
-  // include_audio defaults to true (auto-include any segment.audio_path).
-  const normalizedVariants = (Array.isArray(variants) && variants.length > 0)
-    ? variants.map((v, idx) => {
-        if (!v || typeof v !== 'object') {
-          throw new Error(`variants[${idx}]: must be an object`);
-        }
-        const outPath = String(v.output_path ?? '').trim();
-        if (!outPath) throw new Error(`variants[${idx}]: output_path is required`);
-        return {
-          output_path: outPath,
-          burn_subtitles: v.burn_subtitles !== false,
-          include_audio: v.include_audio !== false,
-        };
-      })
-    : [{
-        output_path: output_path ?? path.join(os.tmpdir(), `lightcone-video-${Date.now()}.mp4`),
-        burn_subtitles: burn_subtitles !== false,
-        include_audio: true,
-      }];
+  if (!Array.isArray(variants) || variants.length === 0) {
+    throw new Error('variants must be a non-empty array. Single output is variants:[{output_path:"..."}].');
+  }
+
+  const normalizedVariants = variants.map((v, idx) => {
+    if (!v || typeof v !== 'object') {
+      throw new Error(`variants[${idx}]: must be an object`);
+    }
+    const outPath = String(v.output_path ?? '').trim();
+    if (!outPath) throw new Error(`variants[${idx}]: output_path is required`);
+    return {
+      output_path: outPath,
+      burn_subtitles: v.burn_subtitles !== false,
+      include_audio: v.include_audio !== false,
+    };
+  });
 
   // Disallow two variants writing to the same file — would race on disk.
   const seenOutputs = new Set();
@@ -485,15 +472,8 @@ export async function composeVideoV2({
       });
     }
 
-    // Legacy single-output callers (didn't pass variants) get the same flat
-    // shape they used to get, plus the variants array for forward-compat.
-    const first = variantOutputs[0];
-    return {
-      path: first.path,
-      duration_ms: first.duration_ms,
-      size_bytes: first.size_bytes,
-      variants: variantOutputs,
-    };
+    // Always return variants[]. Single-output callers read variants[0].
+    return { variants: variantOutputs };
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
   }

package/src/_vendor/video/recorder/index.js

@@ -215,12 +215,128 @@ async function transcodeWebmToMp4({
   });
 }
 
+// Frame-accurate slice of an mp4 — re-encodes to honour the exact start/end
+// instead of snapping to the nearest keyframe (which `-c copy` would do, and
+// can drift by several seconds with libx264's default ~250-frame GOP).
+// Re-encoding short clips (≤30s) at preset=veryfast is fast (<1s typical),
+// so we trade a bit of CPU for being able to align section cuts to the
+// per-segment TTS the rest of the pipeline expects.
+async function cutMp4Slice({
+  inputPath,
+  outputPath,
+  startMs,
+  durationMs,
+  fps = DEFAULT_FPS,
+  ffmpegBin = 'ffmpeg',
+} = {}) {
+  const startSec = Math.max(0, Number(startMs) || 0) / 1000;
+  const durationSec = Math.max(0.05, Number(durationMs) || 0) / 1000;
+  const args = [
+    '-y',
+    '-i', inputPath,
+    '-ss', startSec.toFixed(3),
+    '-t', durationSec.toFixed(3),
+    '-an',
+    '-c:v', 'libx264',
+    '-preset', 'veryfast',
+    '-pix_fmt', 'yuv420p',
+    ...(Number.isFinite(Number(fps)) && Number(fps) > 0 ? ['-r', String(fps)] : []),
+    '-movflags', '+faststart',
+    outputPath,
+  ];
+  await new Promise((resolve, reject) => {
+    const proc = spawn(ffmpegBin, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const errChunks = [];
+    proc.stderr?.on('data', (chunk) => errChunks.push(chunk));
+    proc.once('error', (err) => {
+      const wrapped = new Error(`ffmpeg_spawn_failed:${err.message}`);
+      wrapped.code = 'FFMPEG_SPAWN_FAILED';
+      reject(wrapped);
+    });
+    proc.on('close', (code) => {
+      if (code === 0) return resolve();
+      const wrapped = new Error(
+        `ffmpeg_cut_failed:code=${code}: ${Buffer.concat(errChunks).toString().slice(-2000)}`
+      );
+      wrapped.code = 'FFMPEG_CUT_FAILED';
+      reject(wrapped);
+    });
+  });
+}
+
+// Derive per-section cut points from eventsLog. phase_start.t_ms / phase_end.t_ms
+// are recorded against the trimmed mp4 timeline (head trim already happened),
+// so we can use them as-is.
+function deriveSectionCutPoints(eventsLog, phaseCount) {
+  if (!Array.isArray(eventsLog) || eventsLog.length === 0) {
+    throw new Error('events_log_empty');
+  }
+  const starts = new Map();
+  const ends = new Map();
+  for (const ev of eventsLog) {
+    if (!ev || typeof ev !== 'object') continue;
+    const id = ev.phase_id;
+    const t = Number(ev.t_ms);
+    if (!id || !Number.isFinite(t)) continue;
+    if (ev.action === 'phase_start' && !starts.has(id)) starts.set(id, t);
+    if (ev.action === 'phase_end') ends.set(id, t);
+  }
+  // Walk phases in order to preserve plan ordering even if events arrived
+  // out-of-order (they shouldn't, but guard against it).
+  const orderedIds = [];
+  for (const ev of eventsLog) {
+    if (ev?.action === 'phase_start' && !orderedIds.includes(ev.phase_id)) {
+      orderedIds.push(ev.phase_id);
+    }
+  }
+  if (orderedIds.length !== phaseCount) {
+    throw new Error(`events_phase_count_mismatch:expected=${phaseCount}:got=${orderedIds.length}`);
+  }
+  return orderedIds.map((id) => {
+    const startMs = starts.get(id);
+    const endMs = ends.get(id);
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+      throw new Error(`phase_timing_missing:${id}`);
+    }
+    if (endMs <= startMs) {
+      throw new Error(`phase_timing_invalid:${id}:start=${startMs}:end=${endMs}`);
+    }
+    return { phase_id: id, start_ms: startMs, end_ms: endMs, duration_ms: endMs - startMs };
+  });
+}
+
+function normalizeOutputPaths(rawList) {
+  if (rawList == null) return null;
+  if (!Array.isArray(rawList)) {
+    const error = new Error('output_paths_must_be_array');
+    error.code = 'OUTPUT_PATHS_MUST_BE_ARRAY';
+    throw error;
+  }
+  if (rawList.length === 0) return null;
+  return rawList.map((entry, idx) => {
+    const normalized = normalizeText(entry);
+    if (!normalized) {
+      const error = new Error(`output_paths[${idx}]_empty`);
+      error.code = 'OUTPUT_PATHS_ENTRY_EMPTY';
+      throw error;
+    }
+    return path.resolve(normalized);
+  });
+}
+
 export async function recordUrlNarration({
   plan,
   output_path,
   outputPath = output_path,
   events_path,
   eventsPath = events_path,
+  // Multi-section output: pass an array of N paths matching plan.sections length
+  // to record once continuously and slice the result into N per-section mp4s.
+  // The browser stays open for the whole recording, so visuals flow naturally
+  // between sections (no scroll-back-to-top between each, no page reload). When
+  // omitted, behaves exactly like before — single mp4 at outputPath.
+  output_paths,
+  outputPaths = output_paths,
   url,
   viewport = DEFAULT_VIEWPORT,
   fps = DEFAULT_FPS,
@@ -234,6 +350,7 @@ export async function recordUrlNarration({
   launchChromiumFn = launchChromiumMobile,
   openPageFn = openPageAndSettle,
   transcodeFn = transcodeWebmToMp4,
+  cutFn = cutMp4Slice,
   nowMs = () => Date.now(),
 } = {}) {
   const zoom = Number.isFinite(Number(page_zoom)) && Number(page_zoom) > 0 ? Number(page_zoom) : 1.1;
@@ -249,6 +366,28 @@ export async function recordUrlNarration({
   const resolvedUrl = resolveUrl({ url, plan });
   const normalizedViewport = normalizeViewport(viewport);
   const normalizedFps = normalizeInteger(fps, DEFAULT_FPS);
+  const resolvedOutputPaths = normalizeOutputPaths(outputPaths);
+  // output_paths is REQUIRED. Single-section recordings just pass an array
+  // of one. Removing the optional path forces 1:1 alignment with plan.sections
+  // and eliminates the "default to single output_path master" pattern that
+  // led agents to call this tool once per section instead of once per URL.
+  if (!resolvedOutputPaths) {
+    const error = new Error(
+      'output_paths is required — one entry per plan.sections (single section is a 1-element array).',
+    );
+    error.code = 'OUTPUT_PATHS_REQUIRED';
+    throw error;
+  }
+  if (resolvedOutputPaths.length !== phases.length) {
+    const error = new Error(
+      `output_paths_count_mismatch:expected=${phases.length}:got=${resolvedOutputPaths.length}`,
+    );
+    error.code = 'OUTPUT_PATHS_COUNT_MISMATCH';
+    throw error;
+  }
+  for (const p of resolvedOutputPaths) {
+    mkdirSync(path.dirname(p), { recursive: true });
+  }
 
   mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
   mkdirSync(path.dirname(resolvedEventsPath), { recursive: true });
@@ -367,12 +506,45 @@ export async function recordUrlNarration({
       ? eventsLog.reduce((max, ev) => Math.max(max, Number(ev?.t_ms) || 0), 0)
       : 0;
 
+    // Slice the consolidated mp4 at section boundaries (derived from
+    // phase_start / phase_end events). All slices come from the SAME
+    // continuous recording, so the visual flow between sections stays
+    // natural — no browser reload, no scroll-back-to-top per segment.
+    const cutPoints = deriveSectionCutPoints(eventsLog, phases.length);
+    const sectionOutputs = [];
+    for (let i = 0; i < cutPoints.length; i += 1) {
+      const cut = cutPoints[i];
+      const outPath = resolvedOutputPaths[i];
+      await cutFn({
+        inputPath: resolvedOutputPath,
+        outputPath: outPath,
+        startMs: cut.start_ms,
+        durationMs: cut.duration_ms,
+        fps: normalizedFps,
+      });
+      const sliceStat = await stat(outPath);
+      if (!sliceStat.isFile() || sliceStat.size <= 0) {
+        const error = new Error(`section_slice_empty:${outPath}`);
+        error.code = 'SECTION_SLICE_EMPTY';
+        throw error;
+      }
+      sectionOutputs.push({
+        phase_id: cut.phase_id,
+        video_path: outPath,
+        start_ms: cut.start_ms,
+        end_ms: cut.end_ms,
+        duration_ms: cut.duration_ms,
+        size_bytes: Number(sliceStat.size ?? 0),
+      });
+    }
+
     return {
-      video_path: resolvedOutputPath,
+      master_video_path: resolvedOutputPath,
       events_path: resolvedEventsPath,
       events_log: eventsLog,
       duration_ms: lastTms > 0 ? lastTms : null,
       display,
+      sections: sectionOutputs,
     };
   } catch (error) {
     primaryError = error;

package/src/tools/compose-video-v2.js

@@ -27,14 +27,31 @@ export async function runComposeVideoV2Tool({
   outro_paths,
   format,
   resolution,
+  variants,
+  // Trapping legacy params: agents that still pass these from older prompts
+  // need an explicit error so they migrate, not silent fallback.
   output_path,
   burn_subtitles,
-  variants,
   workspaceDir,
 }) {
+  if (output_path != null || burn_subtitles != null) {
+    return toolError(
+      'compose_video_v2: output_path and burn_subtitles are no longer accepted at the top level. '
+      + 'Pass variants:[{output_path, burn_subtitles?, include_audio?}] — single output is a '
+      + '1-element array. See frag.short.video_synthesis_tools.',
+    );
+  }
+
   if (!Array.isArray(segments) || segments.length === 0) {
     return toolError('segments must be a non-empty array.');
   }
+  if (!Array.isArray(variants) || variants.length === 0) {
+    return toolError(
+      'compose_video_v2: variants[] is required. Single output is variants:[{output_path:"..."}]. '
+      + 'Multi-output dual delivery (字幕版 + 无字幕版) is variants:[{output_path:"sub.mp4"}, '
+      + '{output_path:"clean.mp4", burn_subtitles:false, include_audio:false}].',
+    );
+  }
 
   const imagePaths = [];
   for (let i = 0; i < segments.length; i++) {
@@ -69,34 +86,24 @@ export async function runComposeVideoV2Tool({
     }
   }
 
-  // Normalize variants. If caller passed a variants[] array, that takes
-  // priority — multi-output mode. Otherwise build a single-element variants
-  // array from the legacy output_path + burn_subtitles params.
+  // Normalize variants. Each entry needs an output_path; flags default to
+  // burn_subtitles=true, include_audio=true.
   const outDir = workspaceDir
     ? path.join(workspaceDir, 'artifacts', 'video')
     : path.join(os.tmpdir(), 'lightcone-video');
 
-  let normalizedVariants;
-  if (Array.isArray(variants) && variants.length > 0) {
-    normalizedVariants = variants.map((v, idx) => {
-      if (!v || typeof v !== 'object') {
-        return null; // surfaced below
-      }
-      const outPath = String(v.output_path ?? '').trim()
-        || path.join(outDir, `composed-${Date.now()}-${idx}-${randomUUID().slice(0, 8)}.mp4`);
-      return {
-        output_path: outPath,
-        burn_subtitles: v.burn_subtitles !== false,
-        include_audio: v.include_audio !== false,
-      };
-    });
-    if (normalizedVariants.some(v => v === null)) {
-      return toolError('variants must be an array of objects, each with { output_path, burn_subtitles?, include_audio? }.');
-    }
-  } else {
-    const burnSubtitles = burn_subtitles !== false;
-    const outPath = output_path ?? path.join(outDir, `composed-${Date.now()}-${randomUUID().slice(0, 8)}.mp4`);
-    normalizedVariants = [{ output_path: outPath, burn_subtitles: burnSubtitles, include_audio: true }];
+  const normalizedVariants = variants.map((v, idx) => {
+    if (!v || typeof v !== 'object') return null;
+    const outPath = String(v.output_path ?? '').trim()
+      || path.join(outDir, `composed-${Date.now()}-${idx}-${randomUUID().slice(0, 8)}.mp4`);
+    return {
+      output_path: outPath,
+      burn_subtitles: v.burn_subtitles !== false,
+      include_audio: v.include_audio !== false,
+    };
+  });
+  if (normalizedVariants.some(v => v === null)) {
+    return toolError('variants must be an array of objects, each with { output_path, burn_subtitles?, include_audio? }.');
   }
 
   const warnings = [];
@@ -135,31 +142,16 @@ export async function runComposeVideoV2Tool({
       variants: normalizedVariants,
     });
 
-    const outputs = Array.isArray(result?.variants) && result.variants.length > 0
-      ? result.variants
-      : [{ path: result.path, duration_ms: result.duration_ms, size_bytes: result.size_bytes,
-           burn_subtitles: normalizedVariants[0].burn_subtitles,
-           include_audio: normalizedVariants[0].include_audio }];
-
-    const lines = ['compose_video_v2 completed.'];
-    if (outputs.length === 1) {
-      const v = outputs[0];
+    const outputs = Array.isArray(result?.variants) ? result.variants : [];
+    const lines = ['compose_video_v2 completed.', `variants=${outputs.length}`];
+    outputs.forEach((v, idx) => {
+      lines.push(`--- variant ${idx} ---`);
       lines.push(`path=${v.path}`);
       lines.push(`duration_ms=${v.duration_ms}`);
       lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
       lines.push(`burn_subtitles=${v.burn_subtitles}`);
       lines.push(`include_audio=${v.include_audio}`);
-    } else {
-      lines.push(`variants=${outputs.length}`);
-      outputs.forEach((v, idx) => {
-        lines.push(`--- variant ${idx} ---`);
-        lines.push(`path=${v.path}`);
-        lines.push(`duration_ms=${v.duration_ms}`);
-        lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
-        lines.push(`burn_subtitles=${v.burn_subtitles}`);
-        lines.push(`include_audio=${v.include_audio}`);
-      });
-    }
+    });
     lines.push(`segments=${segments.length}`);
     lines.push(`outro_clips=${(outro_paths ?? []).length}`);
     for (const w of warnings) lines.push(w);

package/src/tools/record-url-narration.js

@@ -181,6 +181,21 @@ export function resolveRecordUrlNarrationPaths({
   };
 }
 
+function resolveOutputPaths(rawList, { workspaceDir }) {
+  if (rawList == null) return null;
+  if (!Array.isArray(rawList)) {
+    throw new Error('output_paths must be an array of file paths (one per section).');
+  }
+  if (rawList.length === 0) return null;
+  return rawList.map((entry, idx) => {
+    const normalized = normalizeText(entry);
+    if (!normalized) {
+      throw new Error(`output_paths[${idx}] is empty — every entry must be a non-empty path.`);
+    }
+    return path.resolve(workspaceDir, normalized);
+  });
+}
+
 export async function runRecordUrlNarrationTool({
   args = {},
   currentWorkspaceId = '',
@@ -242,33 +257,72 @@ export async function runRecordUrlNarrationTool({
   }
 
   try {
-    const { resolvedOutputPath, resolvedEventsPath } = resolveRecordUrlNarrationPaths({
+    // output_paths is REQUIRED. The legacy "default output_path master file"
+    // mode is gone — agents kept defaulting to one-call-per-section because
+    // that was the lowest-friction path. Now every recording is sliced, even
+    // single-section ones (which are just a 1-element output_paths array).
+    let resolvedOutputPaths;
+    try {
+      resolvedOutputPaths = resolveOutputPaths(validatedInput.output_paths, { workspaceDir });
+    } catch (error) {
+      return toolError(`Error: ${error.message}`);
+    }
+    if (!resolvedOutputPaths) {
+      return toolError(
+        'Error: output_paths is required — one workspace-relative mp4 path per plan.sections entry. '
+        + 'Single-section recording is a 1-element array. Multi-section recording records once '
+        + 'continuously (one browser session, one scrollTop) and slices the result at section '
+        + 'boundaries. See frag.short.video_synthesis_tools.',
+      );
+    }
+    const planSectionCount = (planSegments(validatedInput.plan) ?? []).length;
+    if (resolvedOutputPaths.length !== planSectionCount) {
+      return toolError(
+        `Error: output_paths length (${resolvedOutputPaths.length}) must match `
+        + `plan.sections length (${planSectionCount}). Each section produces exactly one mp4 — `
+        + `don't pad or truncate.`,
+      );
+    }
+
+    // The master / events JSON paths are agent-optional debug artifacts.
+    // Default master to a tmp path next to the first output; events default
+    // to <master>.events.json. Agent can override either if they care.
+    const { resolvedOutputPath: masterPath, resolvedEventsPath } = resolveRecordUrlNarrationPaths({
       workspaceDir,
       outputPath: validatedInput.output_path,
       eventsPath: validatedInput.events_path,
       nowMs,
     });
-
-    mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
+    mkdirSync(path.dirname(masterPath), { recursive: true });
     mkdirSync(path.dirname(resolvedEventsPath), { recursive: true });
 
     const recorderOutput = await recordUrlNarrationFn({
       url: validatedInput.url,
       plan: validatedInput.plan,
-      output_path: resolvedOutputPath,
+      output_path: masterPath,
       events_path: resolvedEventsPath,
+      output_paths: resolvedOutputPaths,
       viewport: validatedInput.viewport,
       fps: validatedInput.fps,
       settle_ms: validatedInput.settle_ms,
     });
 
-    return toolText(
-      `Recorded URL narration.\n`
-      + `video_path=${resolvedOutputPath}\n`
-      + `events_path=${resolvedEventsPath}\n`
-      + `duration_ms=${deriveDurationMs(recorderOutput) ?? 'unknown'}\n`
-      + `phases=${derivePhaseCount({ plan: validatedInput.plan, recorderOutput }) ?? 'n/a'}`
-    );
+    const sections = Array.isArray(recorderOutput?.sections) ? recorderOutput.sections : [];
+    const lines = [
+      'Recorded URL narration.',
+      `events_path=${resolvedEventsPath}`,
+      `master_video_path=${masterPath}`,
+      `total_duration_ms=${deriveDurationMs(recorderOutput) ?? 'unknown'}`,
+      `sections=${sections.length}`,
+    ];
+    sections.forEach((s, idx) => {
+      lines.push(`--- section ${idx} (${s.phase_id}) ---`);
+      lines.push(`video_path=${s.video_path}`);
+      lines.push(`start_ms=${s.start_ms}`);
+      lines.push(`duration_ms=${s.duration_ms}`);
+      lines.push(`size_bytes=${s.size_bytes ?? 'unknown'}`);
+    });
+    return toolText(lines.join('\n'));
   } catch (error) {
     return toolError(`Error: ${error.message}`);
   }