@lightcone-ai/daemon 0.17.0 → 0.18.0

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

@@ -6,12 +6,17 @@ import { z } from 'zod';
 import { addTitleEffects } from './lib/render.js';
 import { SUPPORTED_PRESETS } from './lib/presets.js';
 import { runSynthesisTtsTool } from '../../../src/tools/synthesize-tts.js';
+import { runListTtsVoicesTool } from '../../../src/tools/list-tts-voices.js';
+import { runPreviewTtsVoiceTool } from '../../../src/tools/preview-tts-voice.js';
+import { runGetDefaultVoiceTool } from '../../../src/tools/get-default-voice.js';
+import { runSetDefaultVoiceTool } from '../../../src/tools/set-default-voice.js';
 import { runPlanVideoSegmentsTool } from '../../../src/tools/plan-video-segments.js';
 import { runComposeVideoV2Tool } from '../../../src/tools/compose-video-v2.js';
 import { runRecordUrlNarrationTool } from '../../../src/tools/record-url-narration.js';
 import { runRenderTextToImageTool } from '../../../src/tools/render-text-to-image.js';
 import { runRenderHtmlToImageTool } from '../../../src/tools/render-html-to-image.js';
 import { runTakePageScreenshotTool } from '../../../src/tools/take-page-screenshot.js';
+import { hasVideoBriefSent } from '../../../src/video-brief-flag.js';
 import { lightconeApi, CURRENT_WORKSPACE_ID, CURRENT_AGENT_ID } from './lib/lightcone-api.js';
 
 const WORKSPACE_DIR = String(process.env.WORKSPACE_DIR ?? '');
@@ -128,7 +133,9 @@ server.tool(
   + 'into a single call (segment-level audio is required for plan_video_segments to align video durations).',
   {
     text: z.string().min(1).describe('Narration text for this segment. Will be synthesized as a single mp3.'),
-    voice_id: z.string().optional().describe('TTS voice preset. Omit to use workspace default.'),
+    voice_id: z.string().optional().describe('MiniMax voice_id (e.g. "Chinese (Mandarin)_Warm_Girl"). Omit to use the workspace default. '
+      + 'If neither is set the call fails with tts_default_voice_required — call list_tts_voices to discover options '
+      + 'and set_default_voice once the user picks one.'),
     workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
   },
   async ({ text, voice_id, workspace_id }) => runSynthesisTtsTool({
@@ -140,6 +147,87 @@ server.tool(
   })
 );
 
+// ── TTS voice catalog + workspace preference (added in the voice-selection
+// rebuild — see docs/scenario-content-creation/video-synthesis-design.md).
+// These four tools let the agent discover MiniMax voices, sample them, and
+// persist a workspace-level default — all from inside the IM conversation,
+// no separate UI. There is no fallback default voice: synthesize_tts will
+// throw tts_default_voice_required if neither the request nor the workspace
+// has a voice_id set, which is the agent's cue to run this discovery flow.
+server.tool(
+  'list_tts_voices',
+  'List TTS voices available to the current workspace (system catalog + any cloned voices owned by this workspace). '
+  + 'Use this to show the user options before calling set_default_voice or synthesize_tts. '
+  + 'Filter by language (e.g. "zh-CN"), style_tag (e.g. "recommended", "news", "warm"), or free-text query.',
+  {
+    language: z.string().optional().describe('BCP-47 language tag, e.g. "zh-CN", "en-US".'),
+    origin: z.enum(['system', 'cloned']).optional().describe('Restrict to system catalog or this workspace\'s cloned voices.'),
+    query: z.string().optional().describe('Free-text match against voice_id and display_name.'),
+    style_tag: z.string().optional().describe('Match a single style tag (e.g. "recommended" for the curated shortlist).'),
+    limit: z.number().int().positive().max(200).optional().describe('Max rows to return. Default 100.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ language, origin, query, style_tag, limit, workspace_id }) => runListTtsVoicesTool({
+    language,
+    origin,
+    query,
+    style_tag,
+    limit,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'preview_tts_voice',
+  'Synthesize a short sample so the user can hear a voice before committing. Returns a playable mp3 path + audio_url. '
+  + 'Pass voice_id from list_tts_voices; text is optional (defaults to a neutral Chinese sample sentence).',
+  {
+    voice_id: z.string().min(1).describe('voice_id to preview, from list_tts_voices.'),
+    text: z.string().optional().describe('Custom sample text. Defaults to a short Chinese sentence.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ voice_id, text, workspace_id }) => runPreviewTtsVoiceTool({
+    voice_id,
+    text,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'get_default_voice',
+  'Read the current workspace\'s default TTS voice. Returns null when not set — that is the signal to run the discovery flow '
+  + '(list_tts_voices → user picks → set_default_voice) before doing any synthesis.',
+  {
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ workspace_id }) => runGetDefaultVoiceTool({
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'set_default_voice',
+  'Persist a workspace-level default TTS voice. The voice_id must exist in the workspace\'s visible catalog '
+  + '(system voice or a cloned voice owned by this workspace) — otherwise this tool fails with tts_voice_not_found. '
+  + 'Call this after the user picks from list_tts_voices, OR when the user explicitly asks to change their default.',
+  {
+    voice_id: z.string().min(1).describe('voice_id to make the default. Must be in this workspace\'s catalog.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ voice_id, workspace_id }) => runSetDefaultVoiceTool({
+    voice_id,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
 // ── plan_video_segments (migrated from chat-bridge; TTS decoupled) ────────
 // Pure planner — takes per-segment {text, audio_path, visual_kind, ...} and
 // returns segments with audio_duration_ms / presentation.duration / dwell_ms
@@ -186,10 +274,13 @@ 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. Segments are concatenated in order; outro clips are appended after.\n\n'
+  + 'subtitle_text is provided AND burn_subtitles is not false. 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.',
+  + 'Returns a local mp4 path + size_bytes.\n\n'
+  + 'Dual-version delivery (subtitled + clean): call this tool twice with the SAME segments — first with default '
+  + 'burn_subtitles=true (or omitted), then again with burn_subtitles=false and a different output_path. Only the '
+  + 'final ffmpeg pass repeats; audio, source clips, and the plan_video_segments alignment are all reused.',
   {
     segments: z.array(z.object({
       visual_path: z.string().optional().describe('Absolute path to a single image / video / gif.'),
@@ -207,6 +298,9 @@ server.tool(
     outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end.'),
     resolution: z.string().optional().describe('Output resolution WxH. Default "1080x1920".'),
     output_path: z.string().optional().describe('Absolute output path. Auto-generated if omitted.'),
+    burn_subtitles: z.boolean().optional().describe('Whether to burn subtitle_text into the video. Default true. '
+      + 'Pass false to produce a clean no-subtitle copy (dual-version delivery: run compose_video_v2 twice — '
+      + 'once with default true, once with false + a different output_path — same segments, only one extra ffmpeg pass).'),
   },
   async (args) => {
     const segments = Array.isArray(args?.segments) ? args.segments : [];
@@ -222,6 +316,18 @@ server.tool(
         + 'visual_path/visual_kind for the real media). Call plan_video_segments now and pass its output here.'
       );
     }
+    if (hasNarration && !hasVideoBriefSent({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
+      return toolError(
+        'compose_video_v2 refused: must send a 确认稿 (production-brief) to the user via send_message before '
+        + 'compositing a narration video. The system scans send_message content for a brief — a message that '
+        + 'BOTH asks the user to confirm (确认 / 你看 / OK 吗 / 可以吗 / 同意 / 通过 / 行不行) AND describes '
+        + 'at least two of: 画面 / 时长 / 文案 / 口播 / 字幕 / 顺序 / 口吻 / 分镜 / 配音 — no such message '
+        + 'has been sent in this workspace+agent.\n\n'
+        + '"已生成 TTS" / "开始合成" / progress reports do NOT count. Send a concrete confirmation draft '
+        + 'first (e.g. "我准备这么做：画面是真录屏，时长约 1 分钟，文案如下…，字幕开启，公司顺序 A→B→C，'
+        + '口吻是…—— 你 OK 吗？") and wait for the user to reply OK before calling compose_video_v2 again.'
+      );
+    }
     return runComposeVideoV2Tool({ ...args, workspaceDir: WORKSPACE_DIR });
   }
 );
@@ -265,6 +371,25 @@ server.tool(
     if (isBlockedCvmaxEditorVideoTool('record_url_narration')) {
       return cvmaxEditorVideoToolError('record_url_narration');
     }
+    // record_url_narration is part of the narration-video pipeline (paired
+    // with synthesize_tts + plan_video_segments + compose_video_v2), so it
+    // requires the same 确认稿 gate as compose_video_v2 — catching the skip
+    // earlier saves TTS + recording time.
+    if (!hasVideoBriefSent({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text:
+          'Error: record_url_narration refused: must send a 确认稿 (production-brief) to the user via '
+          + 'send_message before starting a narration recording. The system scans send_message content for '
+          + 'a brief — a message that BOTH asks the user to confirm (确认 / 你看 / OK 吗 / 可以吗 / 同意 / '
+          + '通过 / 行不行) AND describes at least two of: 画面 / 时长 / 文案 / 口播 / 字幕 / 顺序 / 口吻 / '
+          + '分镜 / 配音 — no such message has been sent in this workspace+agent.\n\n'
+          + '"已生成 TTS" / "开始合成" / progress reports do NOT count. Send a concrete confirmation draft '
+          + 'first (e.g. "我准备这么做：画面是真录屏，时长约 1 分钟，文案如下…，字幕开启，公司顺序 A→B→C，'
+          + '口吻是…—— 你 OK 吗？") and wait for the user to reply OK before calling record_url_narration.'
+        }],
+      };
+    }
     return runRecordUrlNarrationTool({
       args,
       currentWorkspaceId: CURRENT_WORKSPACE_ID,

package/package.json

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

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

@@ -254,6 +254,7 @@ export async function composeVideoV2({
   outro_paths = [],
   resolution = '1080x1920',
   output_path,
+  burn_subtitles = true,
 }) {
   if (!Array.isArray(segments) || segments.length === 0) {
     throw new Error('segments must be a non-empty array');
@@ -322,11 +323,16 @@ export async function composeVideoV2({
       // Accept `text` as an alias for `subtitle_text`: plan_video_segments takes
       // segment narration as `text` on input, compose_video_v2's canonical name is
       // `subtitle_text`. Either reaches the burn pass so subtitles aren't silently dropped.
-      const subtitleText = (
-        typeof seg.subtitle_text === 'string' ? seg.subtitle_text
-        : typeof seg.text === 'string' ? seg.text
-        : ''
-      ).trim();
+      // burn_subtitles=false (dual-version delivery: same segments composed once
+      // with subtitles and once without) drops the text here so the burn-in pass
+      // skips entirely — saves the second compose having to mutate the segment array.
+      const subtitleText = burn_subtitles
+        ? (
+            typeof seg.subtitle_text === 'string' ? seg.subtitle_text
+            : typeof seg.text === 'string' ? seg.text
+            : ''
+          ).trim()
+        : '';
       readyClips.push({ path: finalClip, duration: visualClip.duration, transition, subtitleText });
     }
 

package/src/chat-bridge.js

@@ -16,6 +16,7 @@ import { runSubmitToLibraryTool } from './submit-to-library-tool.js';
 // media-tools MCP server (V5 migration). Handlers still live in
 // daemon/src/tools/ as shared modules and are imported there.
 import { runGetLibraryFileTool } from './tools/get-library-file.js';
+import { markVideoBriefSent, looksLikeVideoBrief } from './video-brief-flag.js';
 import { isLeaseInvalidated, clearInvalidatedLease } from './governance-state.js';
 import { classifyLeaseWindow } from './lease-window.js';
 import {
@@ -795,6 +796,15 @@ server.tool('send_message', 'Send a message to a workspace, DM, or thread', {
   content: z.string().describe('Message content'),
 }, async ({ target, content }) => {
   const data = await api('POST', '/send', { target, content });
+  // Heuristic: if this looks like a video-production 确认稿 (asks permission +
+  // describes plan), mark a cross-process flag so media-tools' compose_video_v2
+  // / record_url_narration can verify a brief was actually sent before running.
+  // See daemon/src/video-brief-flag.js for the detection rules.
+  if (looksLikeVideoBrief(content) && AGENT_ID && currentWorkspaceId) {
+    try {
+      markVideoBriefSent({ workspaceId: currentWorkspaceId, agentId: AGENT_ID, content });
+    } catch { /* best-effort; failure to mark is non-fatal */ }
+  }
   return { content: [{ type: 'text', text: `Sent. messageId=${data.messageId} threadTarget=${data.threadTarget}` }] };
 });
 

package/src/mcp-config.js

@@ -89,6 +89,11 @@ const SERVER_BACKED_MCP_SERVERS = new Set([
   'audience-research',
   'hook-pattern-library',
   'weixin-tools',
+  // media-tools (V1–V5 chat-bridge → media-tools migration): synthesize_tts
+  // hits /tts/voiceover and the CvMax editor_in_chief gate + video-brief
+  // checks read CURRENT_AGENT_ID / CURRENT_WORKSPACE_ID. lib/lightcone-api.js
+  // throws at module load without the SERVER_URL/MACHINE_API_KEY/AGENT_ID triple.
+  'media-tools',
 ]);
 
 function baseEnvForServer(serverKey, { serverUrl, authToken, agentId, workspaceId, workspaceDir }) {

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

@@ -22,7 +22,8 @@ function statSizeOrNull(p) {
   try { return fs.statSync(p).size; } catch { return null; }
 }
 
-export async function runComposeVideoV2Tool({ segments, outro_paths, format, resolution, output_path, workspaceDir }) {
+export async function runComposeVideoV2Tool({ segments, outro_paths, format, resolution, output_path, burn_subtitles, workspaceDir }) {
+  const burnSubtitles = burn_subtitles !== false;
   if (!Array.isArray(segments) || segments.length === 0) {
     return toolError('segments must be a non-empty array.');
   }
@@ -72,7 +73,9 @@ export async function runComposeVideoV2Tool({ segments, outro_paths, format, res
   // Warn when narration is present but no subtitle text is — compose_video_v2 burns
   // subtitles only from `subtitle_text` (or its `text` alias); without it the video
   // ships with no captions. Simplest fix: pass plan_video_segments' output verbatim.
-  {
+  // burn_subtitles=false is the explicit "no subtitles" path (dual-version delivery),
+  // so the warning would be noise — suppress it.
+  if (burnSubtitles) {
     const hasSubText = s => (typeof s?.subtitle_text === 'string' && s.subtitle_text.trim())
       || (typeof s?.text === 'string' && s.text.trim());
     const narratedNoSub = segments.filter(s =>
@@ -97,6 +100,7 @@ export async function runComposeVideoV2Tool({ segments, outro_paths, format, res
       outro_paths: outro_paths ?? [],
       resolution: resolution ?? '1080x1920',
       output_path: outPath,
+      burn_subtitles: burnSubtitles,
     });
 
     const lines = [
@@ -106,6 +110,7 @@ export async function runComposeVideoV2Tool({ segments, outro_paths, format, res
       `size_bytes=${result.size_bytes ?? 'unknown'}`,
       `segments=${segments.length}`,
       `outro_clips=${(outro_paths ?? []).length}`,
+      `burn_subtitles=${burnSubtitles}`,
     ];
     for (const w of warnings) lines.push(w);
     return toolText(lines.join('\n'));

package/src/tools/get-default-voice.js

@@ -0,0 +1,48 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+export async function runGetDefaultVoiceTool({
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const params = new URLSearchParams({ workspace_id: targetWorkspaceId });
+
+  let data;
+  try {
+    data = await api('GET', `/tts/preferences?${params.toString()}`);
+  } catch (error) {
+    return toolError(`get_default_voice API error: ${error.message}`);
+  }
+
+  if (!data?.default_voice_id) {
+    return toolText('No default TTS voice set for this workspace. Call list_tts_voices to show the user options, then set_default_voice once they pick one.');
+  }
+
+  const v = data.voice;
+  const lines = [
+    `Default TTS voice for workspace=${data.workspace_id} (provider=${data.provider}):`,
+    `voice_id=${data.default_voice_id}`,
+  ];
+  if (v) {
+    lines.push(`display_name=${v.display_name}`);
+    if (v.language) lines.push(`language=${v.language}`);
+    if (v.gender) lines.push(`gender=${v.gender}`);
+    if (Array.isArray(v.style_tags) && v.style_tags.length) {
+      lines.push(`style_tags=${v.style_tags.join(', ')}`);
+    }
+  } else {
+    lines.push('(voice metadata not found — catalog may have changed; ask user to pick again)');
+  }
+  return toolText(lines.join('\n'));
+}

package/src/tools/list-tts-voices.js

@@ -0,0 +1,58 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+function formatVoiceLine(voice) {
+  const tags = Array.isArray(voice.style_tags) && voice.style_tags.length
+    ? ` [${voice.style_tags.join(', ')}]`
+    : '';
+  const gender = voice.gender ? ` (${voice.gender})` : '';
+  const origin = voice.origin === 'cloned' ? ' • cloned' : '';
+  return `- ${voice.voice_id} — ${voice.display_name}${gender}${tags}${origin}`;
+}
+
+export async function runListTtsVoicesTool({
+  language,
+  origin,
+  query,
+  style_tag,
+  limit,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const params = new URLSearchParams();
+  params.set('workspace_id', targetWorkspaceId);
+  if (language) params.set('language', String(language).trim());
+  if (origin) params.set('origin', String(origin).trim());
+  if (query) params.set('query', String(query).trim());
+  if (style_tag) params.set('style_tag', String(style_tag).trim());
+  if (limit != null && Number.isFinite(Number(limit))) params.set('limit', String(Math.floor(Number(limit))));
+
+  let data;
+  try {
+    data = await api('GET', `/tts/voices?${params.toString()}`);
+  } catch (error) {
+    return toolError(`list_tts_voices API error: ${error.message}`);
+  }
+
+  const voices = Array.isArray(data?.voices) ? data.voices : [];
+  if (!voices.length) {
+    return toolText('No TTS voices match the requested filters.');
+  }
+
+  const lines = [
+    `Found ${voices.length} voice(s) for provider=${data.provider}, workspace=${data.workspace_id}:`,
+    ...voices.map(formatVoiceLine),
+  ];
+  return toolText(lines.join('\n'));
+}

package/src/tools/preview-tts-voice.js

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import path from 'path';
+import os from 'os';
+
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+function inferAudioExt(url) {
+  const clean = String(url ?? '').split('?')[0];
+  const ext = path.extname(clean).toLowerCase();
+  return ['.mp3', '.wav', '.flac', '.aac', '.ogg'].includes(ext) ? ext : '.mp3';
+}
+
+export async function runPreviewTtsVoiceTool({
+  voice_id,
+  text,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const normalizedVoiceId = String(voice_id ?? '').trim();
+  if (!normalizedVoiceId) return toolError('voice_id is required for preview_tts_voice.');
+
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const payload = {
+    workspace_id: targetWorkspaceId,
+    voice_id: normalizedVoiceId,
+  };
+  if (text) payload.text = String(text).trim();
+
+  let data;
+  try {
+    data = await api('POST', '/tts/voices/preview', payload);
+  } catch (error) {
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${normalizedVoiceId}" not found or not visible to this workspace.`);
+    }
+    return toolError(`preview_tts_voice API error: ${error.message}`);
+  }
+
+  const remoteAudioUrl = String(data.audio_url ?? '').trim();
+  if (!remoteAudioUrl) return toolError('preview_tts_voice did not return audio_url.');
+
+  const downloadRes = await fetch(remoteAudioUrl);
+  if (!downloadRes.ok) {
+    return toolError(`Failed to download preview audio (${downloadRes.status}).`);
+  }
+  const fileBuffer = Buffer.from(await downloadRes.arrayBuffer());
+  const outDir = path.join(os.tmpdir(), 'lightcone-tts');
+  mkdirSync(outDir, { recursive: true });
+  const ext = inferAudioExt(remoteAudioUrl);
+  const outPath = path.join(outDir, `tts-preview-${Date.now()}-${randomUUID().slice(0, 8)}${ext}`);
+  writeFileSync(outPath, fileBuffer);
+
+  return toolText([
+    'preview_tts_voice completed.',
+    `voice_id=${data.voice_id}`,
+    `display_name=${data.display_name ?? ''}`,
+    `path=${outPath}`,
+    `audio_url=${remoteAudioUrl}`,
+    `duration_ms=${data.duration_ms ?? 'unknown'}`,
+    `preview_text=${data.preview_text ?? ''}`,
+  ].join('\n'));
+}

package/src/tools/set-default-voice.js

@@ -0,0 +1,44 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+export async function runSetDefaultVoiceTool({
+  voice_id,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const normalizedVoiceId = String(voice_id ?? '').trim();
+  if (!normalizedVoiceId) return toolError('voice_id is required for set_default_voice.');
+
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  let data;
+  try {
+    data = await api('PUT', '/tts/preferences', {
+      workspace_id: targetWorkspaceId,
+      voice_id: normalizedVoiceId,
+    });
+  } catch (error) {
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${normalizedVoiceId}" not found or not visible to this workspace. Use list_tts_voices to discover valid IDs.`);
+    }
+    return toolError(`set_default_voice API error: ${error.message}`);
+  }
+
+  const v = data?.voice;
+  const lines = [
+    `Default TTS voice updated for workspace=${data.workspace_id} (provider=${data.provider}).`,
+    `voice_id=${data.default_voice_id}`,
+  ];
+  if (v?.display_name) lines.push(`display_name=${v.display_name}`);
+  return toolText(lines.join('\n'));
+}

package/src/tools/synthesize-tts.js

@@ -34,12 +34,22 @@ export async function runSynthesisTtsTool({ text, voice_id, workspace_id, curren
     speed: 1,
     format: 'mp3',
   };
-  if (voice_id) payload.voice_preset = String(voice_id).trim();
+  if (voice_id) payload.voice_id = String(voice_id).trim();
 
   let data;
   try {
     data = await api('POST', '/tts/voiceover', payload);
   } catch (error) {
+    // Server contract: tts_default_voice_required means the workspace has no
+    // default and the caller didn't pass voice_id. Surface a clear message so
+    // the agent knows to call list_tts_voices + set_default_voice first.
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_default_voice_required')) {
+      return toolError('No TTS voice selected for this workspace. Call list_tts_voices, let the user pick one, then set_default_voice — or pass voice_id to synthesize_tts.');
+    }
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${voice_id}" not found or not visible to this workspace. Use list_tts_voices to discover valid IDs.`);
+    }
     return toolError(`synthesize_tts API error: ${error.message}`);
   }
 
@@ -63,6 +73,7 @@ export async function runSynthesisTtsTool({ text, voice_id, workspace_id, curren
   return toolText([
     'synthesize_tts completed.',
     `path=${outPath}`,
+    `voice_id=${data.voice_id ?? 'unknown'}`,
     `duration_ms=${data.duration_ms ?? 'unknown'}`,
     `size_bytes=${fileBuffer.length}`,
   ].join('\n'));

package/src/video-brief-flag.js

@@ -0,0 +1,70 @@
+// Cross-process flag for "the agent has sent a video-production 确认稿 (brief)
+// to the user in this workspace+agent context". chat-bridge's send_message
+// tool writes the flag when the outgoing message heuristically looks like a
+// confirmation brief; media-tools' compose_video_v2 and record_url_narration
+// read the flag and refuse to proceed without it.
+//
+// Why a file flag instead of in-process state: send_message lives in
+// chat-bridge (one stdio MCP server), compose_video_v2/record_url_narration
+// live in media-tools (a different stdio MCP server, same machine). Both are
+// spawned by the same codex CLI session per agent, so they share env (notably
+// AGENT_ID / WORKSPACE_ID) but not memory. A flag file under ~/.lightcone is
+// the simplest cross-process medium and survives short-lived MCP restarts.
+//
+// The heuristic is intentionally specific (asks-permission marker AND
+// 2+ plan-describing markers) so casual progress reports like "已生成 TTS"
+// or "画面已就绪" do NOT satisfy it. A motivated agent could game the
+// detection by stuffing keywords into any send_message, but the default
+// codex behavior (which silently skipped the soft prompt rule) is what we
+// need to interrupt — and gaming is observable in chat history.
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const FILE_NAME = 'video-brief-sent.flag';
+
+function flagDir(workspaceId, agentId) {
+  return path.join(os.homedir(), '.lightcone', 'sessions', workspaceId, agentId);
+}
+
+function flagPath(workspaceId, agentId) {
+  return path.join(flagDir(workspaceId, agentId), FILE_NAME);
+}
+
+export function markVideoBriefSent({ workspaceId, agentId, content }) {
+  if (!workspaceId || !agentId) return;
+  const dir = flagDir(workspaceId, agentId);
+  const p = flagPath(workspaceId, agentId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(p, String(content ?? '').slice(0, 4096));
+}
+
+export function hasVideoBriefSent({ workspaceId, agentId } = {}) {
+  if (!workspaceId || !agentId) return false;
+  return existsSync(flagPath(workspaceId, agentId));
+}
+
+// Permission-asking markers — the message must ask the user to decide / OK.
+// 确认 alone is too broad (matches "无需确认" / "已确认硬约束" / "确认收到"); require
+// a specific permission-ask shape: 请确认 / 确认稿 / 你确认 / 确认[吗?？] / 等确认.
+const PERMISSION_MARKERS = [
+  /请.*确认/, /你.*确认/, /确认\s*[吗?？]/, /等.*确认/, /确认稿/,
+  /你看/, /OK\s*吗/i, /可以吗/, /同意吗/, /通过吗/, /行不行/, /如何\?|如何？/,
+];
+
+// Plan-describing markers — must cover at least 2 different aspects of the brief.
+const PLAN_MARKERS = [
+  /画面/, /时长/, /文案/, /口播/, /字幕/, /顺序/, /口吻/, /分镜/, /配音/,
+];
+
+export function looksLikeVideoBrief(content) {
+  if (typeof content !== 'string') return false;
+  // Min length 20 — Chinese is character-dense, a plausible brief like
+  // "请确认：画面/时长/字幕已定。同意吗？" is only ~20 chars but still a valid brief.
+  if (content.length < 20) return false;
+  const hasPermissionAsk = PERMISSION_MARKERS.some(rx => rx.test(content));
+  if (!hasPermissionAsk) return false;
+  const distinctPlanHits = PLAN_MARKERS.filter(rx => rx.test(content)).length;
+  return distinctPlanHits >= 2;
+}