@lightcone-ai/daemon 0.20.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\nMULTI-SECTION OUTPUT (recommended for any URL with ≥2 sections): pass `output_paths` as an array with one path per plan.sections entry. 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. This avoids the per-segment scroll-back-to-top reset that happens when the agent splits N sections into N separate record_url_narration calls — that pattern reopens the browser and re-navigates for each segment, which looks visually disjointed even though the per-segment timing is correct.\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,9 +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 for the CONSOLIDATED master recording. Default tmp/wx3_video/recorded-{ts}.mp4. When output_paths is also provided, this still receives the full continuous recording for verification/debugging.'),
-    output_paths: z.array(z.string()).optional().describe('Multi-section output mode. Pass an array of N workspace-relative paths matching plan.sections length. The tool records ONCE continuously then slices the result into N mp4s at section boundaries (derived from phase_start / phase_end events). RECOMMENDED whenever a URL has ≥2 sections — keeps visual flow natural between sections instead of reopening the browser per segment.'),
-    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.20.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

@@ -367,21 +367,26 @@ export async function recordUrlNarration({
   const normalizedViewport = normalizeViewport(viewport);
   const normalizedFps = normalizeInteger(fps, DEFAULT_FPS);
   const resolvedOutputPaths = normalizeOutputPaths(outputPaths);
-  // When multi-section output is requested, the count must match plan.sections
-  // 1:1 — otherwise the agent will end up with audio/visual misalignment when
-  // it feeds these into plan_video_segments. Fail loud rather than silently
-  // truncating or padding.
-  if (resolvedOutputPaths && resolvedOutputPaths.length !== phases.length) {
+  // 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;
   }
-  if (resolvedOutputPaths) {
-    for (const p of resolvedOutputPaths) {
-      mkdirSync(path.dirname(p), { recursive: true });
-    }
+  for (const p of resolvedOutputPaths) {
+    mkdirSync(path.dirname(p), { recursive: true });
   }
 
   mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
@@ -501,43 +506,40 @@ export async function recordUrlNarration({
       ? eventsLog.reduce((max, ev) => Math.max(max, Number(ev?.t_ms) || 0), 0)
       : 0;
 
-    // Multi-section output: 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
+    // 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.
-    let sectionOutputs = null;
-    if (resolvedOutputPaths) {
-      const cutPoints = deriveSectionCutPoints(eventsLog, phases.length);
-      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),
-        });
+    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,

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

@@ -257,40 +257,49 @@ export async function runRecordUrlNarrationTool({
   }
 
   try {
-    const { resolvedOutputPath, resolvedEventsPath } = resolveRecordUrlNarrationPaths({
-      workspaceDir,
-      outputPath: validatedInput.output_path,
-      eventsPath: validatedInput.events_path,
-      nowMs,
-    });
-
-    mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
-    mkdirSync(path.dirname(resolvedEventsPath), { recursive: true });
-
-    // Multi-section mode: caller passed output_paths. Validate it 1:1 with
-    // plan.sections so the recorder can slice the continuous recording into
-    // per-section mp4s without ambiguity.
-    let resolvedOutputPaths = null;
+    // 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) {
-      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.`,
-        );
-      }
+    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(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,
@@ -298,24 +307,11 @@ export async function runRecordUrlNarrationTool({
       settle_ms: validatedInput.settle_ms,
     });
 
-    // Single-output mode (legacy): same one-line summary as before.
-    if (!resolvedOutputPaths) {
-      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'}`,
-      );
-    }
-
-    // Multi-section mode: one section block per output mp4, plus the
-    // consolidated master mp4 path for debugging / verification.
     const sections = Array.isArray(recorderOutput?.sections) ? recorderOutput.sections : [];
     const lines = [
-      'Recorded URL narration (multi-section).',
-      `master_video_path=${resolvedOutputPath}`,
+      'Recorded URL narration.',
       `events_path=${resolvedEventsPath}`,
+      `master_video_path=${masterPath}`,
       `total_duration_ms=${deriveDurationMs(recorderOutput) ?? 'unknown'}`,
       `sections=${sections.length}`,
     ];