aimakeall-mcp 0.11.0 → 0.13.0

package/lib/cloud-tools.mjs

@@ -27,8 +27,11 @@ import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
 import { registerComposerTools } from "./composer-tools.mjs";
-import { productionFields, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
+import { registerReviewTools } from "./review-tools.mjs";
+import { productionFields, visualProductionFields, sceneVisual, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
 import { saveProductionContext, readProductionContext, durationReview, reviewProductionPayload } from "./production-context.mjs";
+import { TTS_PROVIDERS, buildTtsRequestBody, estimateTtsSubtitleLines, requestTtsBinary, resolveTtsSelection } from "./tts-workflow.mjs";
+import { assertI2vAllowed, findSceneWebImage, resolveVisualSettings, sceneWebSearchQuery } from "./visual-production.mjs";
 
 // 여러 파일을 base64 로 싣는 요청의 인코딩 크기 합이 서버 JSON 상한을 넘지 않게 사전 검사.
 // 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
@@ -36,6 +39,11 @@ const BODY_BUDGET_BYTES = SERVER_JSON_BODY_LIMIT_BYTES - 512 * 1024; // 바디
 
 // 컴패니언 계약 상수 — companion/index.cjs 의 MAX_SHOT_COUNT 와 맞춘다.
 const COMPANION_MAX_SHOTS = 18;
+const ttsFallbackFields = {
+  allowProviderFallback: z.boolean().optional().describe("확정된 일시 거절 때만 대체 공급자 허용. 처리 결과 불명·인증·정책 오류는 재합성하지 않음"),
+  fallbackVoices: z.object(Object.fromEntries(TTS_PROVIDERS.map((provider) => [provider,
+    z.object({ voiceId: z.string().min(1) }).optional()]))).optional().describe("선택한 목소리를 대신해도 되는 공급자별 보이스 ID. 미지정이면 명시 보이스를 다른 목소리로 변경하지 않음"),
+};
 
 function assertEncodedBudget(filePaths, { context = "요청" } = {}) {
   let total = 0;
@@ -145,13 +153,21 @@ function describeLocalError(error) {
 }
 
 export function wrapCloudHandler(config, handler) {
-  return async (args) => {
+  return async (args, extra) => {
     if (!config.pat) return textResult(NO_PAT_GUIDE, { isError: true });
     try {
-      return await handler(args);
+      return await handler(args, extra);
     } catch (error) {
       if (error instanceof AimakeallApiError) {
         const retry = error.retryAfterSeconds ? ` (${error.retryAfterSeconds}초 후 재시도)` : "";
+        if (error.partialProviderUsage || error.accountCostEvents.length || error.fallbackStatus) {
+          return textResult(JSON.stringify({ error: error.message, code: error.errorCode, status: error.status,
+            provider: error.provider, fallbackStatus: error.fallbackStatus, fallbackReason: error.fallbackReason,
+            fallbackAvailable: error.fallbackAvailable, capability: error.capability,
+            accountCostEvents: error.accountCostEvents, acceptedTaskCosts: error.acceptedTaskCosts,
+            partialProviderUsage: error.partialProviderUsage, usage: error.usage,
+            guidance: "접수된 비용과 실패 사유를 확인하세요. 결과 불명 작업이나 지정한 보이스를 자동 재생성/교체하지 마세요." }, null, 2), { isError: true });
+        }
         return textResult(`${error.message}${retry}`, { isError: true });
       }
       return textResult(`요청 실패: ${describeLocalError(error)}`, { isError: true });
@@ -165,6 +181,7 @@ function trimPlanScenes(scenes) {
     durationSec: scene?.durationSec,
     idx: scene?.idx,
     imagePrompt: scene?.imagePrompt,
+    webSearchQuery: sceneWebSearchQuery(scene),
     label: scene?.label,
     ratio: scene?.ratio,
     sceneNarration: scene?.sceneNarration,
@@ -184,11 +201,13 @@ function trimAnalysis(analysis) {
 
 export function registerCloudTools(server, config, api) {
   registerComposerTools(server, config, api);
+  registerReviewTools(server, config, api, { wrap: handler => wrapCloudHandler(config, handler) });
   async function completedGenerationResult(job, includePreview) {
     const payload = job.result || {};
     const resultBody = { generationJobId: job.id, status: job.status, kind: job.kind,
       model: payload.model, taskId: payload.taskId, providerTasks: job.providerTasks };
     if (job.kind === "image") {
+      resultBody.source = "ai";
       resultBody.imageUrl = payload.imageUrl || undefined;
       let inlineImage = null;
       if (!payload.imageUrl && payload.imageDataUrl) {
@@ -285,10 +304,11 @@ export function registerCloudTools(server, config, api) {
       videoModel: z.string().optional().describe("기본 kie-grok-imagine"),
       videoSecondsPerScene: z.number().min(0).max(30).optional().describe("씬당 영상 초 (0이면 영상 미포함)"),
       videoQuality: z.string().optional().describe("기본 720p"),
-      ttsProvider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("기본 typecast"),
+      ttsProvider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 계정별 자동 우선순위. Edge/Supertonic2는 TTS 공급자 비용 0"),
       ttsChars: z.number().int().min(0).max(20000).optional().describe("내레이션 글자 수"),
     },
     wrapCloudHandler(config, async (input) => {
+      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider, validateCredentials: false })).provider };
       const payload = await api.request("/api/tracker/cost/estimate", { body: input, method: "POST", timeoutMs: 30_000 });
       return jsonResult(payload);
     }),
@@ -299,6 +319,7 @@ export function registerCloudTools(server, config, api) {
     "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로, emphasisKeywords는 stitch_timeline의 emphasisKeywords로 이어집니다(하단자막 단어 강조).",
     {
       productionProfile: productionFields.productionProfile,
+      ...visualProductionFields,
       durationTargetSec: z.number().positive().max(180).optional().describe("사용자가 요청한 목표 길이(예:40). 음성 길이로 덮어쓰지 않습니다."),
       topic: z.string().optional().describe("영상 주제"),
       copy: z.string().optional().describe("핵심 카피/대사"),
@@ -328,12 +349,14 @@ export function registerCloudTools(server, config, api) {
         forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null, productionProfile, durationTargetSec }) => {
+    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null, productionProfile, durationTargetSec, imageSourceMode, visualMotionMode }) => {
       if (!String(topic).trim() && !String(copy).trim()) {
         return textResult("topic 또는 copy 중 하나는 입력해야 합니다.", { isError: true });
       }
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       const payload = await api.request("/api/tracker/shorts-video/plan", {
         body: {
+          ...visualSettings,
           categoryId,
           productionProfile,
           durationTargetSec,
@@ -352,15 +375,17 @@ export function registerCloudTools(server, config, api) {
         timeoutMs: 240_000,
       });
       const productionPath = saveProductionContext(config.stateDir, {
-        topic, productionProfile: payload?.productionProfile, narrationScript: payload?.narrationScript,
+        topic, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: payload?.productionProfile, narrationScript: payload?.narrationScript,
         narrationSource: payload?.narrationSource, tagline: payload?.tagline, emphasisKeywords: payload?.emphasisKeywords || [],
         channelFingerprint, scenes: trimPlanScenes(payload?.scenes),
       });
       return jsonResult({
         productionPath,
+        ...visualSettings,
         productionProfile: payload?.productionProfile,
         narrationSource: payload?.narrationSource,
-        next: "productionPath를 recommend_voice → tts_narration_with_captions → stitch_timeline에 전달하세요. 대본을 뉴스체로 바꾸지 말고, list_composer_presets/search_composer_assets로 편집 소재도 선택하세요.",
+        next: `productionPath를 이미지 준비·보이스 추천·TTS·스티치에 계속 전달하세요. ${visualSettings.visualMotionMode === "image-motion" ? "I2V 프롬프트/영상 생성은 생략하고 이미지 URL을 stitch_timeline.sceneVisuals(kind=image)에 넣으세요." : "이미지 확인 후 I2V 영상 생성으로 진행하세요."} 대본을 뉴스체로 바꾸지 말고 컷컴포저 소재도 활용하세요.`,
         charactersUsed: Array.isArray(payload?.charactersUsed) ? payload.charactersUsed : undefined,
         ctaText: payload?.ctaText,
         emphasisKeywords: Array.isArray(payload?.emphasisKeywords) ? payload.emphasisKeywords : [],
@@ -455,6 +480,8 @@ export function registerCloudTools(server, config, api) {
     "plan_commerce_video",
     "제품 홍보 영상 기획을 생성합니다. 제품 사진 파일 경로가 최소 1장 필요합니다 (이 PC의 로컬 경로).",
     {
+      ...visualProductionFields,
+      productionProfile: productionFields.productionProfile,
       productName: z.string().describe("제품명 (필수)"),
       productImagePaths: z.array(z.string()).min(1).describe("제품/자산 사진의 로컬 파일 경로 (1장 이상)"),
       modelImagePath: z.string().optional().describe("모델 사진 로컬 경로 (선택)"),
@@ -472,7 +499,8 @@ export function registerCloudTools(server, config, api) {
         forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" , characters = [] }) => {
+    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" , characters = [], productionProfile, imageSourceMode, visualMotionMode }) => {
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       // 확장자 검증(임의 파일 업로드 차단) + 합산 크기 예산(서버 413 사전 차단).
       for (const filePath of productImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "이미지" });
       if (modelImagePath) assertAllowedInputFile(modelImagePath, ALLOWED_IMAGE_EXTS, { kind: "모델 이미지" });
@@ -480,6 +508,7 @@ export function registerCloudTools(server, config, api) {
 
       const payload = await api.request("/api/tracker/commerce-video/plan", {
         body: {
+          ...visualSettings, productionProfile,
           categoryId,
           description,
           modelImage: modelImagePath ? fileToImagePayload(modelImagePath) : null,
@@ -497,7 +526,14 @@ export function registerCloudTools(server, config, api) {
         method: "POST",
         timeoutMs: 300_000,
       });
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic: productName, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: payload?.productionProfile || productionProfile,
+        tagline: payload?.tagline, narrationScript: payload?.narrationScript,
+        scenes: trimPlanScenes(payload?.scenes), featureKey: "commerceVideo",
+      });
       return jsonResult({
+        productionPath, ...visualSettings, productionProfile: payload?.productionProfile || productionProfile,
         analysis: trimAnalysis(payload?.analysis),
         ctaText: payload?.ctaText,
         ok: payload?.ok,
@@ -510,8 +546,13 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_image",
-    "씬 이미지 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed 결과의 imageUrl을 받은 뒤 씬 영상 입력에 쓰세요. 첫 씬/캐릭터/제품 이미지를 referenceImageUrls·referenceImagePaths로 전달하면 일관성 유지에 도움이 됩니다. 완료 이미지는 직접 확인하거나 verify_scene_image로 검증하세요.",
+    "선택한 방식으로 장면 이미지를 준비합니다. productionPath의 web은 사용자 키로 Pexels/Pixabay 검색만, ai는 AI 생성만, mixed는 웹 검색 후 없을 때 AI 생성합니다. 웹 결과는 즉시 imageUrl·출처를 반환하며 AI만 generationJobId를 get_generation_job으로 조회합니다. image-motion이면 I2V를 생략하고 sceneVisual을 스티치에 사용하세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
+      sceneIdx: z.number().int().min(0).optional().describe("기획 장면 idx. 저장된 장면 검색어와 출처를 연결합니다."),
+      webSearchQuery: z.string().max(160).optional().describe("장면에 맞는 짧은 웹 검색 키워드. plan.scenes[].webSearchQuery를 사용하세요."),
+      excludeImageUrls: z.array(z.string()).max(100).optional().describe("이미 사용한 웹 이미지 URL. 반복 장면을 피합니다."),
       requestId: z.string().optional().describe("접수 응답 유실 후 같은 작업을 재확인할 때 기존 generationJobId를 지정합니다. 동일 ID·입력은 중복 생성하지 않습니다."),
       prompt: z.string().describe("이미지 프롬프트 (plan 결과의 imagePrompt)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -522,7 +563,46 @@ export function registerCloudTools(server, config, api) {
       referenceImageUrls: z.array(z.string()).max(6).optional().describe("참조 이미지 URL (씬1 앵커 등)"),
       referenceImagePaths: z.array(z.string()).max(4).optional().describe("참조 이미지 로컬 경로 (제품 사진 등)"),
     },
-    wrapCloudHandler(config, async ({ requestId, prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "" }) => {
+    wrapCloudHandler(config, async ({ requestId, prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "", productionPath, productionProfile, imageSourceMode, visualMotionMode, sceneIdx = 0, webSearchQuery, excludeImageUrls = [] }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      productionProfile = context?.productionProfile || productionProfile;
+      const plannedScene = context?.scenes?.find((entry) => entry.idx === sceneIdx) || {};
+      const saveSource = (source) => saveProductionContext(config.stateDir, {
+        ...context, productionProfile, visualSettings,
+        sceneSources: [...(context?.sceneSources || []).filter((entry) => entry.idx !== sceneIdx), { ...source, idx: sceneIdx }],
+      });
+      let fallbackReason;
+      if (visualSettings.imageSourceMode !== "ai") {
+        // A retry of a possibly accepted paid job must recover it before another
+        // stock selection can hide it. Unknown IDs continue the original flow.
+        if (requestId) {
+          try {
+            const job = await fetchGenerationJob(api, requestId);
+            if (job.kind !== "image") throw new Error("requestId는 이미지 생성 작업 ID여야 합니다. 영상 작업은 get_generation_job으로 조회하세요.");
+            return job.status === "completed" ? completedGenerationResult(job, returnImage)
+              : jsonResult({ generationJobId: job.id, status: job.status, kind: job.kind, existing: true, nextTool: "get_generation_job" });
+          } catch (error) { if (Number(error?.status) !== 404) throw error; }
+        }
+        const query = webSearchQuery || sceneWebSearchQuery(plannedScene) || sceneWebSearchQuery({ imagePrompt: prompt });
+        const selected = await findSceneWebImage(api, {
+          query,
+          excludeImageUrls: [...excludeImageUrls, ...(context?.sceneSources || []).filter((entry) => entry.idx !== sceneIdx).map((entry) => entry.url).filter(Boolean)],
+        });
+        if (selected) {
+          const visual = { ...selected, idx: sceneIdx, label: plannedScene.label || selected.label, durationSec: Number(plannedScene.durationSec) || 6 };
+          return jsonResult({ ok: true, status: "completed", ...visualSettings, source: "web", imageUrl: selected.url,
+            sceneVisual: visual, sourcePage: selected.sourcePage, attribution: selected.attribution, license: selected.license,
+            productionPath: saveSource(visual),
+            guidance: visualSettings.visualMotionMode === "image-motion" ? "sceneVisual을 stitch_timeline.sceneVisuals에 넣으세요. I2V 호출은 하지 않습니다." : "웹 이미지의 내용·출처를 확인한 뒤 I2V 입력으로 사용하세요. 생성 영상에도 이 출처 정보를 보존하세요.",
+          });
+        }
+        if (visualSettings.imageSourceMode === "web") {
+          return { ...jsonResult({ ok: false, code: "WEB_IMAGE_NOT_FOUND", ...visualSettings,
+            message: "사용 가능한 새 웹 이미지를 찾지 못했습니다. 스톡 검색 키·검색어를 확인하거나 직접 이미지를 선택하세요. 웹만 선택했으므로 AI 생성은 실행하지 않았습니다." }), isError: true };
+        }
+        fallbackReason = "혼합 모드: 사용 가능한 새 웹 이미지가 없어 선택한 AI 생성으로 진행합니다.";
+      }
       // identity_lock 리터럴 부착 — 이미 포함돼 있으면 재부착하지 않는다(멱등: 프롬프트 캐시 보존).
       const lock = String(identityLock || "").trim();
       if (lock && !prompt.includes(lock)) prompt = `${prompt.trim()}, ${lock}`;
@@ -536,18 +616,22 @@ export function registerCloudTools(server, config, api) {
         ...referenceImageUrls.map((url, index) => ({ name: `ref-${index + 1}`, previewUrl: url })),
       ].slice(0, 6);
 
-      return jsonResult(await submitGenerationJob(api, {
+      const job = await submitGenerationJob(api, {
         kind: "image", includePreview: returnImage, requestId,
         input: {
+          productionProfile, ...visualSettings,
           aspectRatio,
           model,
           prompt,
           referenceImages,
-          referenceSearchEnabled: true,
+          referenceSearchEnabled: false,
           resolution,
-          webSearchEnabled: true,
+          webSearchEnabled: false,
         },
-      }));
+      });
+      return jsonResult({ ...job, ...visualSettings, source: "ai", fallbackReason,
+        productionPath: saveSource({ source: "ai", generationJobId: job.generationJobId }),
+      });
     }),
   );
 
@@ -555,6 +639,8 @@ export function registerCloudTools(server, config, api) {
     "generate_scene_video_prompt",
     "씬 이미지 기반 영상 프롬프트를 생성합니다. 결과 videoPrompt를 generate_scene_video의 prompt로 넘기세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
       imagePrompt: z.string().describe("씬의 이미지 프롬프트"),
       sceneImageUrl: z.string().optional().describe("generate_scene_image가 반환한 imageUrl"),
       sceneScript: z.string().optional().describe("씬 대사/설명 (plan 결과의 label)"),
@@ -565,9 +651,13 @@ export function registerCloudTools(server, config, api) {
       kind: z.enum(["shorts_scene", "commerce_video_scene", "music_video_scene"]).optional(),
       modelId: z.string().optional().describe("대상 영상 모델 (기본 kie-grok-imagine — generate_scene_video와 동일하게 맞추세요)"),
     },
-    wrapCloudHandler(config, async ({ imagePrompt, sceneImageUrl = "", sceneScript = "", sceneTitle = "", aspectRatio = "9:16", durationSec = 8, videoStylePreset = "", kind = "shorts_scene", modelId = "kie-grok-imagine" }) => {
+    wrapCloudHandler(config, async ({ imagePrompt, sceneImageUrl = "", sceneScript = "", sceneTitle = "", aspectRatio = "9:16", durationSec = 8, videoStylePreset = "", kind = "shorts_scene", modelId = "kie-grok-imagine", productionPath, productionProfile, imageSourceMode, visualMotionMode }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      assertI2vAllowed(visualSettings);
       const payload = await api.request("/api/tracker/gemini/storyboard-video-prompt", {
         body: {
+          productionProfile: context?.productionProfile || productionProfile, ...visualSettings,
           aspectRatio,
           durationLabel: `${Math.max(1, Math.round(durationSec))}s`,
           generationPlan: {
@@ -596,6 +686,8 @@ export function registerCloudTools(server, config, api) {
     "generate_scene_video",
     "씬 영상 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed가 될 때까지 조회한 뒤 videoUrl을 stitch_timeline에 넣으세요. 접수만 된 상태에서 새로 생성하지 마세요.",
     {
+      ...productionFields,
+      ...visualProductionFields,
       requestId: z.string().optional().describe("접수 응답 유실 후 동일 입력을 재접수할 때 기존 generationJobId를 지정합니다."),
       prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
       sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
@@ -605,10 +697,14 @@ export function registerCloudTools(server, config, api) {
       quality: z.string().optional().describe("기본 720p"),
       returnFrames: z.boolean().optional().describe("기본 true — 결과 영상의 대표 프레임 3장을 직접 보고 QC 할 수 있게 이미지 블록으로 반환"),
     },
-    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
+    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true, productionPath, productionProfile, imageSourceMode, visualMotionMode }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      assertI2vAllowed(visualSettings);
       return jsonResult(await submitGenerationJob(api, {
         kind: "video", includePreview: returnFrames, requestId,
         input: {
+          productionProfile: context?.productionProfile || productionProfile, ...visualSettings,
           aspectRatio,
           durationLabel: `${Math.max(1, Math.ceil(durationSec))}s`,
           generationPlan: {
@@ -630,71 +726,50 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "tts_narration",
-    "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요. 사용자가 보이스를 직접 지정하지 않았다면 먼저 recommend_voice로 주제·샘플 영상에 맞는 보이스를 자동 선정해 voice에 넣으세요.",
+    "내레이션 TTS를 합성해 이 PC에 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge → Supertonic2. 확정된 일시 거절에만 폴백하며, 명시 보이스는 fallbackVoices가 있어야 교체합니다. 접수 후 결과 불명·정책·인증 오류는 재합성하지 않습니다. 먼저 recommend_voice로 톤에 맞는 보이스를 고르세요.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 productionPath의 기획 대본"),
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      ...ttsFallbackFields,
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 선택/저장된 보이스는 유지"),
       voice: z.string().optional().describe("보이스 이름(라벨)"),
       speed: z.number().optional().describe("기본 1"),
       stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional(),
       modelId: z.string().optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
-      provider ||= context?.voice?.provider || (productionProfile ? "elevenlabs" : "typecast");
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
       if (!voice && context?.voice?.provider && context.voice.provider !== provider) return textResult("보이스 공급자가 다릅니다. 선택한 provider용 voice를 다시 선정하세요.", { isError: true });
       voice ||= context?.voice?.voiceId || "";
       if (!text?.trim()) return textResult("대본(text/productionPath)이 필요합니다.", { isError: true });
       if (productionProfile?.deliveryStyle === "casual-social" && !voice) return textResult("먼저 recommend_voice에 productionPath를 전달해 커뮤니티형 보이스를 선정하세요.", { isError: true });
-      const body = provider === "typecast"
-        ? {
-            productionProfile,
-            breath: 0.3,
-            costEventId: createUsageEventId("mcp-tts-typecast"),
-            emotion: "neutral",
-            fileName: "mcp-narration",
-            language: "kor",
-            modelId: "",
-            pitch: 0,
-            smartEmotion: true,
-            speed,
-            text,
-            voice,
-            volume: 100,
-          }
-        : {
-            productionProfile,
-            costEventId: createUsageEventId("mcp-tts-elevenlabs"),
-            fileName: "mcp-narration",
-            languageCode: "ko",
-            modelId,
-            similarityBoost,
-            speakerBoost,
-            speed,
-            stability,
-            style,
-            text,
-            voice,
-          };
-      const result = await api.requestBinary(`/api/tracker/tts/${provider}`, {
-        body,
-        method: "POST",
-        timeoutMs: 120_000,
-      });
-      const saved = saveMediaBuffer(config.stateDir, "narration.mp3", result.buffer, { contentType: result.contentType });
+      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice, fallbackVoices, allowProviderFallback });
+      const result = await requestTtsBinary(api, config, selection, body);
+      provider = result.provider || provider;
+      voice = result.voiceId || voice;
+      const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration.wav" : "narration.mp3", result.buffer, { contentType: result.contentType });
       const durationSec = audioDurationSecFromFile(saved.filePath);
       return jsonResult({
-        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text, tts: { filePath: saved.filePath, durationSec, voiceId: voice } }),
+        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
+          tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
+        provider,
+        primaryProvider: result.primaryProvider || provider,
+        providerFallback: result.providerFallback === true,
+        accountCostEvents: result.accountCostEvents || [],
+        hasAccountCostEvents: true,
+        executionTarget: selection.executionTarget,
         durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
         bytes: saved.bytes,
         // 실측 mp3 길이 — stitch_timeline 의 audioDurationSec 로 그대로 쓰면 타임라인이 정확하다.
         durationSec,
         filePath: saved.filePath,
         voiceName: decodeHeaderValue(
-          result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || "",
+          result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || result.headers.get("x-supertone-voice-name") || result.headers.get("x-edge-tts-voice-name") || result.headers.get("x-supertonic2-voice-name") || "",
         ),
       });
     }),
@@ -768,9 +843,12 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "stitch_timeline",
-    "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다. 하단자막 강조: emphasisKeywords 를 주면 자막 라인 안의 해당 단어만 다른 색/크기로 강조되고, subtitleLines[].style 로 라인별 디자인도 바꿀 수 있습니다.",
+    "씬 이미지/영상과 오디오를 타임라인 매니페스트로 합칩니다. image-motion은 sceneVisuals(kind=image)에 인스펙터 imageMotionPreset/Intensity를 적용해 I2V 없이 렌더합니다. autoCompose 기본 true는 문맥별 모션·자막 디자인·적합한 라이브러리 소재를 배치하며 명시 편집을 우선합니다. 결과 payloadPath를 로컬 render_start에 넘기세요.",
     {
       ...productionFields,
+      ...visualProductionFields,
+      autoCompose: z.boolean().optional().describe("기본 true. 실제 인스펙터 모션·자막 계층·문맥별 라이브러리 자동 편집. false는 수동 편집을 유지합니다."),
+      sceneVisuals: z.array(sceneVisual).min(1).max(200).optional().describe("장면 이미지/영상과 출처 메타데이터. sceneVideos와 동시에 전달하지 마세요."),
       titleStylePresetId: z.string().optional(), subtitleStylePresetId: z.string().optional(),
       titleStyle: composerTextStyle.optional(), subtitleStyle: composerTextStyle.optional(),
       titleSegments: z.array(z.object({ text: z.string(), color: z.string().optional() })).max(20).optional(),
@@ -781,7 +859,7 @@ export function registerCloudTools(server, config, api) {
         idx: z.number().int(),
         label: z.string().optional(),
         url: z.string(),
-      })).min(1).describe("씬 순서대로 idx=0부터. url은 generate_scene_video의 videoUrl"),
+      })).min(1).optional().describe("구버전 영상 전용 입력. 새 제작은 sceneVisuals를 권장합니다. image-motion에서는 사용할 수 없습니다."),
       featureKey: z.enum(["shortsVideo", "commerceVideo", "musicVideo"]).optional().describe("기본 commerceVideo"),
       projectTitle: z.string().optional(),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -808,14 +886,22 @@ export function registerCloudTools(server, config, api) {
       }).passthrough().optional().describe("measure_channel_spec 이 반환한 fingerprint — 자막 세로 위치·BGM 유무를 참고 채널에 맞춥니다"),
       transitionMode: z.enum(["fade", "none"]).optional().describe("기본 none(하드컷). fade 는 씬이 맞대기로 붙는 배치에서 컷마다 검은 딥을 만든다 — 명시 요청 시에만 쓸 것"),
     },
-    wrapCloudHandler(config, async ({ sceneVideos, featureKey, projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines, emphasisKeywords, emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null, productionPath, productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays, decorationRationale }) => {
+    wrapCloudHandler(config, async ({ sceneVideos, sceneVisuals, autoCompose, imageSourceMode, visualMotionMode, featureKey, projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines, emphasisKeywords, emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null, productionPath, productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays, decorationRationale }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
+      const visualSettings = resolveVisualSettings(context, { productionProfile, imageSourceMode, visualMotionMode });
+      if ((!sceneVisuals?.length && !sceneVideos?.length) || (sceneVisuals?.length && sceneVideos?.length)) {
+        return textResult("sceneVisuals 또는 구버전 sceneVideos 중 하나만 전달하세요.", { isError: true });
+      }
+      if (visualSettings.visualMotionMode === "image-motion" && (sceneVideos?.length || sceneVisuals.some((scene) => scene.kind !== "image"))) {
+        return textResult("IMAGE_MOTION_ONLY: 이미지 모션 제작에는 sceneVisuals(kind=image)만 사용할 수 있습니다.", { isError: true });
+      }
+      autoCompose ??= context?.autoCompose ?? productionProfile?.autoComposeEnabled ?? true;
       ttsAudioPath ||= context?.tts?.filePath || "";
       titleText ||= context?.tagline || "";
       subtitleLines ??= context?.tts?.subtitleLines || [];
       emphasisKeywords ??= context?.emphasisKeywords || [];
-      featureKey ||= productionProfile?.categoryId?.endsWith("shorts") ? "shortsVideo" : "commerceVideo";
+      featureKey ||= context?.featureKey || (productionProfile?.categoryId?.endsWith("shorts") ? "shortsVideo" : "commerceVideo");
       channelFingerprint ||= context?.channelFingerprint;
       // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
       if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
@@ -826,6 +912,7 @@ export function registerCloudTools(server, config, api) {
         ? audioDurationSec
         : (ttsAudioPath ? audioDurationSecFromFile(ttsAudioPath) : 0);
       const body = {
+        ...visualSettings, autoCompose,
         productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays,
         aspectRatio,
         audioDurationSec: resolvedAudioDurationSec,
@@ -834,12 +921,14 @@ export function registerCloudTools(server, config, api) {
         featureKey,
         muteVideoAudio,
         projectTitle,
-        sceneVideos: sceneVideos.map((scene, index) => ({
+        ...(sceneVisuals ? { sceneVisuals: sceneVisuals.map((scene, index) => ({
+          ...scene, idx: index, label: scene.label || `scene-${index + 1}`,
+        })) } : { sceneVideos: sceneVideos.map((scene, index) => ({
           durationSec: scene.durationSec,
           idx: index,
           label: scene.label || `scene-${index + 1}`,
           url: scene.url,
-        })),
+        })) }),
         emphasisColor,
         emphasisKeywords,
         channelFingerprint,
@@ -857,7 +946,11 @@ export function registerCloudTools(server, config, api) {
       if (!response?.ok || !response?.payload) {
         return textResult(`스티치 실패: ${response?.error || "매니페스트가 비어 있습니다."}`, { isError: true });
       }
-      if (context || productionProfile) response.payload.productionContext = { ...context, productionProfile, decorationRationale };
+      const autoComposition = response.payload.compositionReport?.autoComposition;
+      if (!decorationRationale && autoComposition?.enabled && autoComposition?.omissions?.length) {
+        decorationRationale = autoComposition.omissions.map((item) => typeof item === "string" ? item : item?.reason || item?.message || "").filter(Boolean).join(" ").slice(0, 500);
+      }
+      if (context || productionProfile) response.payload.productionContext = { ...context, productionProfile, visualSettings, decorationRationale };
       const qualityReview = reviewProductionPayload(response.payload);
       const handle = savePayloadHandle(config.stateDir, response.payload, "stitch");
       return jsonResult({
@@ -1157,6 +1250,8 @@ export function registerCloudTools(server, config, api) {
     "plan_music_video",
     "뮤직비디오 씬 플랜을 생성합니다. suno_music_download로 받은 곡의 가사·길이(durationSec)를 입력하세요. 결과 scenes의 imagePrompt는 generate_scene_image로 이어집니다.",
     {
+      ...visualProductionFields,
+      productionProfile: productionFields.productionProfile,
       durationSec: z.number().min(10).describe("곡 길이(초) — suno_music_download 결과의 durationSec"),
       lyrics: z.string().optional().describe("가사 전체 (instrumental이면 생략 가능)"),
       conceptBrief: z.string().optional().describe("영상 컨셉 브리프"),
@@ -1173,12 +1268,14 @@ export function registerCloudTools(server, config, api) {
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
     },
-    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" , characters = [] }) => {
+    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" , characters = [], productionProfile, imageSourceMode, visualMotionMode }) => {
       if (!instrumental && !String(lyrics).trim()) {
         return textResult("lyrics를 입력하거나 instrumental=true로 지정하세요.", { isError: true });
       }
+      const visualSettings = resolveVisualSettings(null, { productionProfile, imageSourceMode, visualMotionMode });
       const payload = await api.request("/api/tracker/music-video/plan", {
         body: {
+          ...visualSettings, productionProfile,
           alignedLines: [],
           aspectRatio,
           conceptBrief,
@@ -1197,7 +1294,13 @@ export function registerCloudTools(server, config, api) {
       });
       // usage/원장 이벤트 등 컨텍스트 낭비 필드는 제거하고 기획 본문만 돌려준다.
       const { accountCostEvents, providerUsage, usage, ...plan } = payload && typeof payload === "object" ? payload : {};
-      return jsonResult(plan);
+      const scenes = trimPlanScenes(plan.scenes);
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic: conceptBrief, visualSettings, autoCompose: productionProfile?.autoComposeEnabled ?? true,
+        productionProfile: plan.productionProfile || productionProfile,
+        scenes, featureKey: "musicVideo",
+      });
+      return jsonResult({ ...plan, scenes, ...visualSettings, productionPath });
     }),
   );
 
@@ -1314,17 +1417,31 @@ export function registerCloudTools(server, config, api) {
           endMs: z.number().describe("원본에서 자를 끝(ms)"),
         })).min(1).max(6).describe("이 행에 이어 붙일 원본 구간들"),
       })).min(1).max(40).describe("타임라인 행 — 순서대로 이어 붙습니다"),
-      provider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("TTS 공급자, 기본 typecast (recommend_voice 로 보이스를 먼저 고르세요)"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. recommend_voice로 보이스를 먼저 고르세요."),
       voiceId: z.string().optional().describe("보이스 ID (생략 시 공급자 기본)"),
       aspectRatio: z.enum(["9:16", "16:9", "1:1"]).optional().describe("기본 9:16"),
       subtitleCropMode: z.enum(["off", "always", "auto"]).optional().describe("원본 박힌 자막 하단 크롭 — auto 는 burnedSubtitle.present 소스만"),
     },
-    wrapCloudHandler(config, async ({ title = "", sourceVideos, rows, provider = "typecast", voiceId = "", aspectRatio = "9:16", subtitleCropMode = "off" }) => {
+    wrapCloudHandler(config, async ({ title = "", sourceVideos, rows, provider, voiceId = "", aspectRatio = "9:16", subtitleCropMode = "off" }) => {
       const sourceIds = new Set(sourceVideos.map((source) => source.id));
       const badRef = rows.flatMap((row) => row.clipRefs).find((ref) => !sourceIds.has(ref.videoId));
       if (badRef) {
         return textResult(`clipRefs 의 videoId "${badRef.videoId}" 가 sourceVideos 에 없습니다.`, { isError: true });
       }
+      const hasNarration = rows.some((row) => ["N", "SN"].includes(row.mode) && row.audioContent?.trim());
+      const selection = hasNarration ? await resolveTtsSelection(api, config, { provider }) : { provider: "typecast", executionTarget: "server" };
+      provider = selection.provider;
+      let preSynthesizedNarrations;
+      if (selection.executionTarget === "companion") {
+        const narrations = {};
+        for (const [rowIndex, row] of rows.entries()) {
+          if (!["N", "SN"].includes(row.mode) || !row.audioContent?.trim()) continue;
+          const text = row.audioContent.trim();
+          const result = await requestTtsBinary(api, config, selection, buildTtsRequestBody(provider, { text, voice: voiceId }));
+          narrations[rowIndex] = { dataUrl: `data:${result.contentType};base64,${result.buffer.toString("base64")}`, charCount: Array.from(text).length, voiceId };
+        }
+        preSynthesizedNarrations = { narrations, attempted: Object.keys(narrations).length, succeeded: Object.keys(narrations).length, lastError: "" };
+      }
       const version = {
         id: "mcp-remake",
         title,
@@ -1342,6 +1459,7 @@ export function registerCloudTools(server, config, api) {
           aspectRatio,
           costEventId: createUsageEventId("mcp-remake-tts"),
           provider,
+          ...(preSynthesizedNarrations ? { preSynthesizedNarrations } : {}),
           subtitleCropMode,
           version,
           voiceId,
@@ -1370,27 +1488,53 @@ export function registerCloudTools(server, config, api) {
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
-    "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식). 사용자가 보이스를 지정하지 않았다면 먼저 recommend_voice(provider=elevenlabs)로 자동 선정하세요.",
+    "TTS 오디오와 자막을 만듭니다. 순서 Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 목소리는 fallbackVoices 없이 변경하지 않습니다. ElevenLabs 선택 시 실제 char-level 타이밍을 유지하며 해당 정밀 기능은 대체하지 않습니다. 나머지는 실측 오디오 길이 기반 추정 자막이며 추가 STT 과금은 없습니다.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 제작 핸들의 기획 대본 그대로 합성. 사실·인용을 바꾸거나 뉴스체로 재작성하지 마세요."),
+      ...ttsFallbackFields,
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동 선택 또는 제작 핸들에 선정된 공급자"),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
       speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
       modelId: z.string().optional(), stability: z.number().min(0).max(1).optional(),
       style: z.number().min(0).max(1).optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
-      if (!voice && context?.voice?.provider && context.voice.provider !== "elevenlabs") {
-        return textResult("이 제작 핸들의 보이스는 ElevenLabs용이 아닙니다. recommend_voice(provider=elevenlabs)로 다시 선정하거나 ElevenLabs voice를 명시하세요.", { isError: true });
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
+      if (!voice && context?.voice?.provider && context.voice.provider !== provider) {
+        return textResult("보이스 공급자가 다릅니다. 선택한 provider용 voice를 다시 선정하세요.", { isError: true });
       }
       voice ||= context?.voice?.voiceId || "";
       if (!text?.trim()) return textResult("text 또는 기획 대본이 있는 productionPath가 필요합니다.", { isError: true });
       if (productionProfile?.deliveryStyle === "casual-social" && !voice) {
         return textResult("커뮤니티형 음성을 위해 먼저 recommend_voice에 productionPath를 전달하고, 반환된 productionPath 또는 보이스 ID를 사용하세요.", { isError: true });
       }
+      if (provider !== "elevenlabs") {
+        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, fallbackVoices, allowProviderFallback, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
+        const result = await requestTtsBinary(api, config, selection, body);
+        provider = result.provider || provider;
+        voice = result.voiceId || voice;
+        const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration-captions.wav" : "narration-captions.mp3", result.buffer, { contentType: result.contentType });
+        const durationSec = audioDurationSecFromFile(saved.filePath);
+        const subtitleLines = estimateTtsSubtitleLines(text, durationSec);
+        const timingSource = "estimated-from-audio-duration";
+        const updatedProductionPath = saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
+          tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: voice, timingSource },
+        });
+        return jsonResult({ productionPath: updatedProductionPath, productionProfile, provider, executionTarget: selection.executionTarget,
+          primaryProvider: result.primaryProvider || provider, providerFallback: result.providerFallback === true,
+          accountCostEvents: result.accountCostEvents || [], hasAccountCostEvents: true,
+          durationSec, durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec), filePath: saved.filePath,
+          lineCount: subtitleLines.length, subtitleLines, timingSource,
+          warnings: [durationSec > 0 ? "자막은 실측 오디오 길이 기준 추정입니다. 최종 렌더 전 발화와 동기를 확인하세요." : "오디오 길이를 측정하지 못해 자막을 만들지 않았습니다. 저장된 오디오를 확인하세요. 자동 재합성하지 않습니다."],
+          next: "이 productionPath를 stitch_timeline에 전달하세요. 추정 자막의 발화 동기는 최종 미리보기에서 확인하세요.",
+        });
+      }
       const payload = await api.request("/api/tracker/tts/elevenlabs-with-timestamps", {
         body: {
           productionProfile, modelId, stability, style, similarityBoost, speakerBoost,
@@ -1421,10 +1565,12 @@ export function registerCloudTools(server, config, api) {
         : audioDurationSecFromFile(saved.filePath);
       const updatedProductionPath = saveProductionContext(config.stateDir, {
         ...context, productionProfile, narrationScript: text,
-        tts: { durationSec, filePath: saved.filePath, subtitleLines, voiceId: payload?.voiceId || voice, deliverySettings: payload?.deliverySettings },
+        tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: payload?.voiceId || voice, deliverySettings: payload?.deliverySettings, timingSource: "provider-character-alignment" },
       });
       return jsonResult({
         productionPath: updatedProductionPath,
+        provider,
+        timingSource: "provider-character-alignment",
         productionProfile,
         deliverySettings: payload?.deliverySettings,
         durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
@@ -1442,10 +1588,12 @@ export function registerCloudTools(server, config, api) {
     "tts_list_voices",
     "TTS 보이스 목록을 조회합니다. 사용자가 목록에서 직접 고르고 싶어할 때 쓰세요 — 주제·샘플 영상 기반 자동 선정은 recommend_voice가 담당합니다. (voice를 생략하면 서버가 기본 보이스로 합성합니다)",
     {
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2"),
     },
-    wrapCloudHandler(config, async ({ provider = "typecast" }) => {
-      const payload = await api.request(`/api/tracker/tts/${provider}/voices`, { method: "GET", timeoutMs: 30_000 });
+    wrapCloudHandler(config, async ({ provider }) => {
+      const selection = await resolveTtsSelection(api, config, { provider });
+      provider = selection.provider;
+      const payload = selection.localVoices ? { voices: selection.localVoices } : await api.request(`/api/tracker/tts/${provider}/voices`, { method: "GET", timeoutMs: 30_000 });
       // ElevenLabs 는 gender/age 가 labels 객체 안에 있다 — 두 공급자 형태 모두 지원.
       const voices = (Array.isArray(payload?.voices) ? payload.voices : []).slice(0, 80).map((voice) => ({
         age: voice?.age || voice?.labels?.age,
@@ -1455,7 +1603,7 @@ export function registerCloudTools(server, config, api) {
         nameKo: voice?.voiceNameKo,
         voiceId: voice?.voiceId,
       }));
-      return jsonResult({ count: voices.length, provider, voices });
+      return jsonResult({ count: voices.length, provider, executionTarget: selection.executionTarget, voices });
     }),
   );
 
@@ -1467,13 +1615,14 @@ export function registerCloudTools(server, config, api) {
       topic: z.string().optional().describe("영상 주제·타깃 시청층 (예: 시니어 건강 정보, 커머스 쇼츠)"),
       scriptExcerpt: z.string().optional().describe("대본 앞부분 발췌 (선택)"),
       sampleVideoUrl: z.string().optional().describe("사용자가 샘플로 지정한 유튜브 URL 또는 11자 영상 ID"),
-      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 키가 없으면 다음 후보, 합성 실패 후 자동 재과금 없음"),
       sampleVoiceHints: z.string().optional().describe("사용자가 말한 보이스 요구 (예: 차분한 중년 남성)"),
     },
     wrapCloudHandler(config, async ({ topic = "", scriptExcerpt = "", sampleVideoUrl = "", provider, sampleVoiceHints = "", productionPath, productionProfile }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
-      provider ||= productionProfile ? "elevenlabs" : "typecast";
+      const selection = await resolveTtsSelection(api, config, { provider, context });
+      provider = selection.provider;
       topic ||= context?.topic || "";
       scriptExcerpt ||= context?.narrationScript?.slice(0, 2000) || "";
       const notes = [];
@@ -1504,7 +1653,7 @@ export function registerCloudTools(server, config, api) {
         return textResult("topic, scriptExcerpt, sampleVoiceHints, sampleVideoUrl 중 하나는 필요합니다.", { isError: true });
       }
       const payload = await api.request("/api/tracker/tts/recommend-voice", {
-        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic, productionProfile },
+        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic, productionProfile, ...(selection.localVoices ? { localVoiceCatalog: selection.localVoices } : {}) },
         method: "POST",
         timeoutMs: 180_000,
       });