aimakeall-mcp 0.9.0 → 0.10.0

package/README.md

@@ -16,7 +16,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.9.0"],
+      "args": ["-y", "aimakeall-mcp@0.10.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }
@@ -35,13 +35,14 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
 ## 기본 플로우 (쇼츠)
 
 ```
-plan_shorts_video → (씬마다) generate_scene_image → [QC: 동봉 이미지 직접 확인 또는 verify_scene_image] → generate_scene_video_prompt → generate_scene_video → [QC: 동봉 프레임 확인 또는 verify_scene_video]
+plan_shorts_video → (씬마다) generate_scene_image → get_generation_job(completed까지 조회) → [QC: 동봉 이미지 직접 확인 또는 verify_scene_image] → generate_scene_video_prompt → generate_scene_video → get_generation_job(completed까지 조회) → [QC: 동봉 프레임 확인 또는 verify_scene_video]
 → (보이스 미지정 시) recommend_voice → tts_narration_with_captions(하단자막·강조용) 또는 tts_narration → stitch_timeline → render_start → render_status(폴링) → render_result
 → ai_publish_metadata → publish_youtube
 ```
 
-- 씬 영상 생성은 동기 호출로 최대 15분 걸립니다 — MCP 클라이언트의 툴 타임아웃(`MCP_TIMEOUT`)을 충분히 잡아주세요.
-- 렌더 잡은 `~/.aimakeall/render-jobs.json`에 기록되어 프록시 재시작 후 `list_render_jobs`로 복구할 수 있습니다.
+- 이미지·영상 생성은 즉시 `generationJobId`를 반환합니다. `get_generation_job`으로 상태를 조회하고 `completed`의 `imageUrl`/`videoUrl`을 다음 단계에 사용하세요. 연결이 끊겼을 때는 재생성 전에 `list_generation_jobs`로 기존 작업을 확인하세요. 완료 결과는 서버 DB에 48시간 보관되며 계정 소유자만 조회할 수 있습니다.
+- 서버 자체가 생성 중 재시작되면 작업은 `interrupted`로 표시됩니다. 이미 접수된 `providerTasks`와 비용 원장을 확인해야 하며, 자동으로 유료 생성을 재실행하지 않습니다. 이 기능에는 0.10.0 대응 서버가 필요합니다.
+- 렌더 잡은 `~/.aimakeall/render-jobs/` 아래 작업별 파일에 기록되어 프록시 재시작 후 `list_render_jobs`로 복구할 수 있습니다. 기존 `render-jobs.json`도 계속 읽을 수 있습니다.
 - 대용량 산출물(TTS mp3, 스티치 매니페스트)은 파일 경로로 주고받아 모델 컨텍스트를 오염시키지 않습니다.
 - `recommend_voice`는 주제·샘플 영상(유튜브)에 맞는 보이스를 자동 선정합니다 — 샘플 화자 분석은 컴패니언 앱이 실행 중일 때만 동작합니다.
 - 자체검증(QC): 씬 이미지/영상 결과에 이미지·프레임 블록이 동봉되어 에이전트가 직접 보고 판정합니다. 비전 미지원 클라이언트는 `verify_scene_image`/`verify_scene_video`(서버 Gemini 판정)를 쓰세요 — 불합격 시 `regenerationHint`를 반영해 재생성.

package/lib/audio-duration.mjs

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { mp3DurationSec } from "./mp3-duration.mjs";
+
+// WAV duration comes from sample frames, never an assumed MP3 bitrate. Walk RIFF
+// chunks because encoders may include JUNK/LIST metadata before the audio data.
+export function wavDurationSec(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 44
+    || buffer.toString("ascii", 0, 4) !== "RIFF"
+    || buffer.toString("ascii", 8, 12) !== "WAVE") return 0;
+  let format = null;
+  let dataBytes = 0;
+  for (let offset = 12; offset + 8 <= buffer.length;) {
+    const id = buffer.toString("ascii", offset, offset + 4);
+    const size = buffer.readUInt32LE(offset + 4);
+    const body = offset + 8;
+    if (id === "fmt " && size >= 16 && body + size <= buffer.length) {
+      let encoding = buffer.readUInt16LE(body);
+      if (encoding === 0xfffe && size >= 40) {
+        // WAVE_FORMAT_EXTENSIBLE PCM / IEEE_FLOAT subformat GUID.
+        const guidTail = buffer.subarray(body + 28, body + 40).toString("hex");
+        encoding = guidTail === "00001000800000aa00389b71" ? buffer.readUInt32LE(body + 24) : 0;
+      }
+      format = {
+        encoding,
+        channels: buffer.readUInt16LE(body + 2),
+        sampleRate: buffer.readUInt32LE(body + 4),
+        blockAlign: buffer.readUInt16LE(body + 12),
+        bits: buffer.readUInt16LE(body + 14),
+      };
+    } else if (id === "data") {
+      dataBytes += Math.min(size, buffer.length - body);
+    }
+    offset = body + size + (size % 2);
+  }
+  if (!format || !format.channels || !format.sampleRate) return 0;
+  const allowedBits = format.encoding === 1 ? [8, 16, 24, 32] : format.encoding === 3 ? [32, 64] : [];
+  if (!allowedBits.includes(format.bits)) return 0;
+  const blockAlign = format.channels * (format.bits / 8);
+  if (format.blockAlign !== blockAlign) return 0;
+  return Math.round((Math.floor(dataBytes / blockAlign) / format.sampleRate) * 100) / 100;
+}
+
+export function audioDurationSecFromFile(filePath) {
+  const buffer = readFileSync(filePath);
+  if (path.extname(filePath).toLowerCase() === ".wav"
+    || (buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WAVE")) {
+    const seconds = wavDurationSec(buffer);
+    if (seconds > 0) return seconds;
+    throw new Error("WAV 길이를 읽지 못했습니다. PCM WAV로 변환하거나 audioDurationSec에 실제 길이를 지정하세요.");
+  }
+  const seconds = mp3DurationSec(buffer);
+  if (seconds > 0) return seconds;
+  // Preserve the existing approximation only for unparseable MP3 inputs.
+  return Math.round((buffer.length * 8) / (128 * 1000) * 10) / 10;
+}

package/lib/audio-duration.test.mjs

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { audioDurationSecFromFile, wavDurationSec } from "./audio-duration.mjs";
+import { fileToDataUrl } from "./media-store.mjs";
+
+function makeWav({ seconds = 10, rate = 16000, channels = 1, bits = 16, encoding = 1, metadata = false, extensible = false } = {}) {
+  const formatBytes = extensible ? 40 : 16;
+  const header = Buffer.alloc(20 + formatBytes);
+  header.write("RIFF");
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(formatBytes, 16);
+  header.writeUInt16LE(extensible ? 0xfffe : encoding, 20);
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(rate, 24);
+  const blockAlign = channels * bits / 8;
+  header.writeUInt32LE(rate * blockAlign, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(bits, 34);
+  if (extensible) {
+    header.writeUInt16LE(22, 36);
+    header.writeUInt16LE(bits, 38);
+    header.writeUInt32LE(encoding, 44);
+    Buffer.from("00001000800000aa00389b71", "hex").copy(header, 48);
+  }
+  const junk = metadata ? Buffer.from([0x4a, 0x55, 0x4e, 0x4b, 3, 0, 0, 0, 1, 2, 3, 0]) : Buffer.alloc(0);
+  const data = Buffer.alloc(8 + Math.round(seconds * rate) * blockAlign);
+  data.write("data");
+  data.writeUInt32LE(data.length - 8, 4);
+  const buffer = Buffer.concat([header, junk, data]);
+  buffer.writeUInt32LE(buffer.length - 8, 4);
+  return buffer;
+}
+
+test("WAV 길이는 128kbps 추정이 아닌 실제 샘플 수다", () => {
+  for (const options of [
+    {},
+    { rate: 48000, channels: 2, bits: 24, metadata: true },
+    { rate: 44100, channels: 2, bits: 32, encoding: 3 },
+    { rate: 48000, channels: 2, bits: 24, extensible: true },
+    { rate: 8000, bits: 8 },
+  ]) {
+    assert.equal(wavDurationSec(makeWav(options)), 10, JSON.stringify(options));
+  }
+});
+
+test("WAV byteRate 자기신고 값으로 길이가 왜곡되지 않는다", () => {
+  const wav = makeWav();
+  wav.writeUInt32LE(16000, 28);
+  assert.equal(wavDurationSec(wav), 10);
+});
+
+test("실제 WAV 파일 자동 길이와 data URL MIME을 유지", (t) => {
+  const dir = mkdtempSync(path.join(tmpdir(), "aio-wav-duration-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const file = path.join(dir, "ten-seconds.wav");
+  writeFileSync(file, makeWav());
+  assert.equal(audioDurationSecFromFile(file), 10);
+  assert.match(fileToDataUrl(file), /^data:audio\/wav;base64,/u);
+  const source = readFileSync(new URL("./cloud-tools.mjs", import.meta.url), "utf8");
+  assert.match(source, /import \{ audioDurationSecFromFile \} from "\.\/audio-duration\.mjs"/u);
+  assert.match(source, /ttsAudioPath \? audioDurationSecFromFile\(ttsAudioPath\)/u);
+  assert.match(source, /ttsAudioUrl: ttsAudioPath \? fileToDataUrl\(ttsAudioPath\) : ""/u);
+  assert.match(source, /bgmAudioUrl: bgmAudioPath \? fileToDataUrl\(bgmAudioPath\) : ""/u);
+});
+
+test("손상·미지원 WAV는 MP3 비트레이트로 잘못 추정하지 않는다", (t) => {
+  const dir = mkdtempSync(path.join(tmpdir(), "aio-invalid-wav-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const file = path.join(dir, "unsupported.wav");
+  writeFileSync(file, makeWav({ encoding: 6 }));
+  assert.throws(() => audioDurationSecFromFile(file), /audioDurationSec/u);
+  assert.equal(wavDurationSec(Buffer.alloc(44)), 0);
+  assert.equal(wavDurationSec(makeWav().subarray(0, 30)), 0);
+});
+
+test("MP3 길이 프레임 파싱은 유지된다", (t) => {
+  const dir = mkdtempSync(path.join(tmpdir(), "aio-mp3-duration-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const frame = Buffer.alloc(417);
+  Buffer.from([0xff, 0xfb, 0x90, 0]).copy(frame);
+  const file = path.join(dir, "audio.mp3");
+  writeFileSync(file, Buffer.concat(Array.from({ length: 100 }, () => frame)));
+  assert.equal(audioDurationSecFromFile(file), 2.61);
+});

package/lib/cloud-tools.mjs

@@ -9,8 +9,8 @@ import { AimakeallApiError } from "./api-client.mjs";
 import { extractCompanionAudio } from "./companion-client.mjs";
 import {
   ALLOWED_IMAGE_EXTS,
-  ALLOWED_VIDEO_EXTS,
   assertAllowedInputFile,
+  assertAllowedVideoUpload,
   encodedDataUrlBytes,
   fileToDataUrl,
   fileToImagePayload,
@@ -20,9 +20,10 @@ import {
   savePayloadHandle,
   SERVER_JSON_BODY_LIMIT_BYTES,
 } from "./media-store.mjs";
-import { mp3DurationSec } from "./mp3-duration.mjs";
+import { audioDurationSecFromFile } from "./audio-duration.mjs";
 import { canonicalYoutubeWatchUrl } from "./payload-guard.mjs";
 import { createUsageEventId } from "./usage-event.mjs";
+import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./generation-jobs.mjs";
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
 
@@ -74,18 +75,6 @@ function isSafePublicImageUrl(rawUrl) {
   }
 }
 
-// 실측 mp3 길이(초) — 파싱 실패 시에만 CBR-128 근사로 폴백.
-function audioDurationSecFromFile(filePath) {
-  try {
-    const real = mp3DurationSec(readFileSync(filePath));
-    if (real > 0) return real;
-  } catch {
-    // fall through
-  }
-  const size = statSync(filePath).size;
-  return Math.round((size * 8) / (128 * 1000) * 10) / 10;
-}
-
 // aimakeall.com 클라우드 툴 — PAT 필요. 기획·씬 생성·TTS·SUNO·스티치·퍼블리시.
 // 렌더는 여기 없다: 스티치가 만든 타임라인 페이로드를 render_start(로컬 컴패니언)로 넘긴다.
 // 대용량 산출물(오디오·매니페스트·base64 이미지)은 모델 컨텍스트로 돌려주지 않고
@@ -191,6 +180,64 @@ function trimAnalysis(analysis) {
 }
 
 export function registerCloudTools(server, config, api) {
+  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.imageUrl = payload.imageUrl || undefined;
+      let inlineImage = null;
+      if (!payload.imageUrl && payload.imageDataUrl) {
+        const match = String(payload.imageDataUrl).match(/^data:([^;]+);base64,(.+)$/s);
+        if (match) {
+          const ext = match[1].includes("png") ? "png" : "jpg";
+          resultBody.savedPath = saveMediaBuffer(config.stateDir, `scene-image.${ext}`, Buffer.from(match[2], "base64")).filePath;
+          if (includePreview && ALLOWED_INLINE_IMAGE_MIME.has(match[1].toLowerCase()) && match[2].length <= MAX_INLINE_IMAGE_BYTES * 4 / 3) {
+            inlineImage = { base64: match[2], mimeType: match[1].toLowerCase() };
+          }
+        }
+      } else if (includePreview && payload.imageUrl) {
+        inlineImage = await downloadImageAsBase64(payload.imageUrl);
+      }
+      resultBody.qc = inlineImage ? "동봉 이미지를 확인한 뒤 다음 단계로 진행하세요."
+        : "verify_scene_image로 검증하세요. imageUrl이 없으면 savedPath를 imagePath로 넘기세요.";
+      return inlineImage ? jsonWithImagesResult(resultBody, [inlineImage]) : jsonResult(resultBody);
+    }
+    Object.assign(resultBody, { videoUrl: payload.videoUrl, durationLabel: payload.durationLabel, resolvedRouteLabel: payload.resolvedRouteLabel });
+    let frames = [];
+    if (includePreview && payload.videoUrl) {
+      try {
+        const response = await api.request("/api/tracker/video/frames", {
+          method: "POST", body: { count: 3, maxWidth: 480, videoUrl: payload.videoUrl }, timeoutMs: 20_000,
+        });
+        if (response?.ok && Array.isArray(response.frames)) frames = response.frames;
+      } catch { /* A preview failure must not hide the generated video. */ }
+    }
+    resultBody.qc = frames.length ? "동봉 프레임을 확인한 뒤 stitch_timeline으로 진행하세요." : "verify_scene_video로 영상 품질을 확인하세요.";
+    return frames.length ? jsonWithImagesResult(resultBody, frames) : jsonResult(resultBody);
+  }
+
+  server.tool(
+    "get_generation_job",
+    "generate_scene_image/video가 반환한 generationJobId의 상태·결과를 조회합니다. running이면 잠시 뒤 다시 조회하고, completed의 imageUrl/videoUrl로 다음 단계를 진행하세요. MCP를 재시작해도 같은 ID로 회수할 수 있습니다.",
+    { generationJobId: z.string(), includePreview: z.boolean().optional().describe("이미지/대표 프레임 미리보기 포함. 미지정 시 생성 요청의 returnImage/returnFrames 설정 유지") },
+    wrapCloudHandler(config, async ({ generationJobId, includePreview }) => {
+      const job = await fetchGenerationJob(api, generationJobId);
+      if (job.status === "completed") return completedGenerationResult(job, includePreview ?? job.includePreview ?? true);
+      return textResult(JSON.stringify({ generationJobId: job.id, kind: job.kind, status: job.status,
+        providerTasks: job.providerTasks, error: job.error,
+        guidance: job.status === "running" ? "생성 중입니다. 5~10초 후 이 ID를 다시 조회하세요. 새로 생성하지 마세요." : "비용 원장과 providerTasks를 먼저 확인하세요. 실패·중단 작업을 자동 재생성하지 마세요." }, null, 2),
+      { isError: job.status === "failed" || job.status === "interrupted" });
+    }),
+  );
+
+  server.tool(
+    "list_generation_jobs",
+    "내 계정의 최근 이미지·영상 생성 작업 ID와 상태를 조회합니다. 연결이 끊기거나 MCP를 재시작했을 때 결과를 복구하고 중복 생성을 피하는 데 사용하세요.",
+    {},
+    wrapCloudHandler(config, async () => jsonResult(await api.request(GENERATION_JOB_PATH, { timeoutMs: 30_000 }))),
+  );
+
   server.tool(
     "get_usage",
     "내 플랜과 기능별 렌더 쿼터 현황을 조회합니다. 생성 작업 전에 확인하세요.",
@@ -254,7 +301,7 @@ export function registerCloudTools(server, config, api) {
       tone: z.string().optional().describe("기본 '자동 추천'"),
       sceneCount: z.number().int().min(1).max(10).optional().describe("씬 수. 생략하면 channelFingerprint 의 목표 길이로 자동 산출(지문도 없으면 3)"),
       channelFingerprint: z.object({
-        sampleSize: z.number().optional(),
+        sampleSize: z.number().describe("표본 수 — 서버는 이 값이 0보다 커야 지문을 규격으로 인정한다(없으면 조용히 무시됨)"),
         durationTargetSec: z.number().nullable().optional(),
         cutIntervalSec: z.number().nullable().optional(),
         cutsPerMin: z.number().nullable().optional(),
@@ -446,8 +493,9 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_image",
-    "씬 이미지를 생성합니다 (기획 결과의 imagePrompt 사용). 반환된 imageUrl을 씬 영상 생성의 입력으로 쓰세요. 인물·제품 일관성은 이 참조 방식이 권장 경로입니다: 첫 씬(또는 캐릭터 시트/제품 사진)의 이미지를 referenceImageUrls·referenceImagePaths로 모든 씬에 앵커로 전달하세요. 결과에 이미지 블록이 동봉됩니다 — 반드시 직접 보고 QC(캐릭터 앵커·왜곡·지시 이행) 후 불합격 시 재생성하세요. 이미지를 볼 수 없으면 verify_scene_image 사용.",
+    "씬 이미지 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed 결과의 imageUrl을 받은 뒤 씬 영상 입력에 쓰세요. 첫 씬/캐릭터/제품 이미지를 referenceImageUrls·referenceImagePaths로 전달하면 일관성 유지에 도움이 됩니다. 완료 이미지는 직접 확인하거나 verify_scene_image로 검증하세요.",
     {
+      requestId: z.string().optional().describe("접수 응답 유실 후 같은 작업을 재확인할 때 기존 generationJobId를 지정합니다. 동일 ID·입력은 중복 생성하지 않습니다."),
       prompt: z.string().describe("이미지 프롬프트 (plan 결과의 imagePrompt)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
       model: z.enum(["gpt-image-2-beta", "gemini-3.1-flash-image-preview", "doubao-seedream-5.0-lite", "google-flow-nano-banana-pro", "kie-grok-imagine-image"]).optional().describe("이미지 모델, 기본 gpt-image-2-beta"),
@@ -457,7 +505,7 @@ 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 ({ 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 = "" }) => {
       // identity_lock 리터럴 부착 — 이미 포함돼 있으면 재부착하지 않는다(멱등: 프롬프트 캐시 보존).
       const lock = String(identityLock || "").trim();
       if (lock && !prompt.includes(lock)) prompt = `${prompt.trim()}, ${lock}`;
@@ -471,8 +519,9 @@ export function registerCloudTools(server, config, api) {
         ...referenceImageUrls.map((url, index) => ({ name: `ref-${index + 1}`, previewUrl: url })),
       ].slice(0, 6);
 
-      const payload = await api.request("/api/tracker/gemini/storyboard-scene-image", {
-        body: {
+      return jsonResult(await submitGenerationJob(api, {
+        kind: "image", includePreview: returnImage, requestId,
+        input: {
           aspectRatio,
           model,
           prompt,
@@ -481,38 +530,7 @@ export function registerCloudTools(server, config, api) {
           resolution,
           webSearchEnabled: true,
         },
-        method: "POST",
-        timeoutMs: 240_000,
-      });
-
-      let imageUrl = String(payload?.imageUrl || "");
-      let savedPath = "";
-      let inlineImage = null;
-      if (!imageUrl && payload?.imageDataUrl) {
-        // URL 없이 base64만 온 경우 — 컨텍스트로 돌려주지 않고 파일로 저장.
-        const match = String(payload.imageDataUrl).match(/^data:([^;]+);base64,(.+)$/s);
-        if (match) {
-          const ext = match[1].includes("png") ? "png" : "jpg";
-          const saved = saveMediaBuffer(config.stateDir, `scene-image.${ext}`, Buffer.from(match[2], "base64"));
-          savedPath = saved.filePath;
-          const inlineMime = String(match[1]).toLowerCase();
-          if (returnImage && ALLOWED_INLINE_IMAGE_MIME.has(inlineMime) && match[2].length <= MAX_INLINE_IMAGE_BYTES * 4 / 3) {
-            inlineImage = { base64: match[2], mimeType: inlineMime };
-          }
-        }
-      } else if (imageUrl && returnImage) {
-        inlineImage = await downloadImageAsBase64(imageUrl);
-      }
-      const resultBody = {
-        imageUrl: imageUrl || undefined,
-        model: payload?.model,
-        qc: inlineImage
-          ? "동봉된 이미지를 직접 확인하세요: 캐릭터 앵커 일치·손가락/글자 왜곡·프롬프트 이행. 불합격이면 사유를 프롬프트에 반영해 재생성하세요. 이미지를 볼 수 없는 클라이언트라면 verify_scene_image 를 호출하세요."
-          : "이미지를 동봉하지 못했습니다 — verify_scene_image 로 서버측 검증을 수행하세요 (imageUrl 이 없으면 savedPath 를 imagePath 로 넘기세요).",
-        savedPath: savedPath || undefined,
-        taskId: payload?.taskId,
-      };
-      return inlineImage ? jsonWithImagesResult(resultBody, [inlineImage]) : jsonResult(resultBody);
+      }));
     }),
   );
 
@@ -559,8 +577,9 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_video",
-    "씬 영상을 생성합니다 (동기 호출, 최대 ~30분 — MCP 클라이언트의 툴 타임아웃(MCP_TIMEOUT)을 그 이상으로 늘려두세요. 타임아웃되면 이미 과금된 결과를 회수할 수 없으니 주의). 반환된 videoUrl을 stitch_timeline의 sceneVideos에 넣으세요. 결과에 대표 프레임 3장이 동봉됩니다 — 반드시 직접 보고 QC 후 불합격 시 재생성하세요. 볼 수 없으면 verify_scene_video 사용.",
+    "씬 영상 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed가 될 때까지 조회한 뒤 videoUrl을 stitch_timeline에 넣으세요. 접수만 된 상태에서 새로 생성하지 마세요.",
     {
+      requestId: z.string().optional().describe("접수 응답 유실 후 동일 입력을 재접수할 때 기존 generationJobId를 지정합니다."),
       prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
       sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -569,9 +588,10 @@ export function registerCloudTools(server, config, api) {
       quality: z.string().optional().describe("기본 720p"),
       returnFrames: z.boolean().optional().describe("기본 true — 결과 영상의 대표 프레임 3장을 직접 보고 QC 할 수 있게 이미지 블록으로 반환"),
     },
-    wrapCloudHandler(config, async ({ prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
-      const payload = await api.request("/api/tracker/gemini/storyboard-scene-video", {
-        body: {
+    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
+      return jsonResult(await submitGenerationJob(api, {
+        kind: "video", includePreview: returnFrames, requestId,
+        input: {
           aspectRatio,
           durationLabel: `${Math.max(1, Math.ceil(durationSec))}s`,
           generationPlan: {
@@ -587,35 +607,7 @@ export function registerCloudTools(server, config, api) {
           selectedVideoModel: { id: modelId },
           videoGenerationSettings: { inputMode: sceneImageUrl ? "image" : "text", quality },
         },
-        method: "POST",
-        // 서버 최악 경로(KIE 900s + Evolink 폴백 3회×900s)를 넘겨 잡아 조기 abort 로 과금-미회수를 방지.
-        timeoutMs: 1_800_000,
-      });
-      // 대표 프레임 동봉(1층 QC) — 실패는 조용히 넘기고 verify_scene_video 안내로 대체.
-      let frames = [];
-      if (returnFrames && payload?.videoUrl) {
-        try {
-          const frameResp = await api.request("/api/tracker/video/frames", {
-            body: { count: 3, maxWidth: 480, videoUrl: payload.videoUrl },
-            method: "POST",
-            timeoutMs: 60_000, // 과금 완료된 결과를 오래 붙들지 않기 — 실패해도 verify 폴백 안내
-          });
-          if (frameResp?.ok && Array.isArray(frameResp?.frames)) frames = frameResp.frames;
-        } catch {
-          frames = [];
-        }
-      }
-      const resultBody = {
-        durationLabel: payload?.durationLabel,
-        model: payload?.model,
-        qc: frames.length
-          ? "동봉된 대표 프레임 3장을 직접 확인하세요: 캐릭터 붕괴·모션 파탄·왜곡. 불합격이면 프롬프트를 교정해 재생성하세요. 프레임을 볼 수 없는 클라이언트라면 verify_scene_video 를 호출하세요."
-          : "프레임을 동봉하지 못했습니다 — verify_scene_video 로 서버측 검증을 수행하세요.",
-        resolvedRouteLabel: payload?.resolvedRouteLabel,
-        taskId: payload?.taskId,
-        videoUrl: payload?.videoUrl,
-      };
-      return frames.length ? jsonWithImagesResult(resultBody, frames) : jsonResult(resultBody);
+      }));
     }),
   );
 
@@ -784,9 +776,9 @@ export function registerCloudTools(server, config, api) {
         subtitleLines: z.number().nullable().optional(),
         hasBgm: z.boolean().nullable().optional(),
       }).passthrough().optional().describe("measure_channel_spec 이 반환한 fingerprint — 자막 세로 위치·BGM 유무를 참고 채널에 맞춥니다"),
-      transitionMode: z.enum(["fade", "none"]).optional().describe("기본 fade"),
+      transitionMode: z.enum(["fade", "none"]).optional().describe("기본 none(하드컷). fade 는 씬이 맞대기로 붙는 배치에서 컷마다 검은 딥을 만든다 — 명시 요청 시에만 쓸 것"),
     },
-    wrapCloudHandler(config, async ({ sceneVideos, featureKey = "commerceVideo", projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines = [], emphasisKeywords = [], emphasisColor = "", emphasisSizeScale = 0, transitionMode = "fade", channelFingerprint = null }) => {
+    wrapCloudHandler(config, async ({ sceneVideos, featureKey = "commerceVideo", projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines = [], emphasisKeywords = [], emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null }) => {
       // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
       if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
       if (bgmAudioPath) assertAllowedInputFile(bgmAudioPath, new Set([".mp3", ".wav"]), { kind: "BGM 오디오" });
@@ -798,7 +790,7 @@ export function registerCloudTools(server, config, api) {
       const body = {
         aspectRatio,
         audioDurationSec: resolvedAudioDurationSec,
-        bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath, { mimeType: "audio/mpeg" }) : "",
+        bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath) : "",
         bgmVolume,
         featureKey,
         muteVideoAudio,
@@ -816,7 +808,7 @@ export function registerCloudTools(server, config, api) {
         subtitleLines,
         titleText,
         transitionMode,
-        ttsAudioUrl: ttsAudioPath ? fileToDataUrl(ttsAudioPath, { mimeType: "audio/mpeg" }) : "",
+        ttsAudioUrl: ttsAudioPath ? fileToDataUrl(ttsAudioPath) : "",
       };
       const response = await api.request("/api/tracker/commerce-video/stitch", {
         body,
@@ -895,8 +887,7 @@ export function registerCloudTools(server, config, api) {
       notifySubscribers: z.boolean().optional().describe("기본 true"),
     },
     wrapCloudHandler(config, async ({ videoPath, title, description = "", tags = [], categoryId = "", visibility = "private", madeForKids = false, notifySubscribers = true }) => {
-      assertAllowedInputFile(videoPath, ALLOWED_VIDEO_EXTS, { kind: "영상 파일" });
-      const stats = statSync(videoPath);
+      const stats = assertAllowedVideoUpload(videoPath);
       // 메타데이터가 쿼리스트링을 타므로 한국어 설명의 퍼센트 인코딩 팽창으로 헤더 상한(16KB)을
       // 넘지 않도록 보수적으로 제한한다.
       const safeTitle = title.slice(0, 100);
@@ -942,7 +933,7 @@ export function registerCloudTools(server, config, api) {
       storyText: z.string().optional().describe("핵심 줄거리·내용 브리프"),
       styleId: z.enum(["standard", "senior", "insight", "webnovel", "christian", "community-shorts", "viral-shorts"]).optional().describe("기본 standard. senior=시니어(쉽고 친절), insight=명언(통찰)"),
       model: z.enum(["gemini", "opus", "sonnet"]).optional().describe("기본 gemini(가성비). opus/sonnet=Claude"),
-      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLength: z.number().int().min(500).max(12000).optional().describe("목표 글자수, 기본 5000. 서버 출력 상한(8192토큰 ≈ 한국어 12,300자)을 넘으면 대본이 중간에 잘리므로 12000 이 상한이다"),
       targetLanguageLabel: z.string().optional().describe("출력 언어 라벨, 기본 '한국 (한국어)'"),
       contentFormat: z.enum(["longform", "shortform"]).optional().describe("기본 longform (standard/senior/insight는 항상 longform)"),
       webnovelSubtypeId: z.enum(["modern-webnovel", "regression-fantasy", "romance-fantasy", "martial-arts", "light-novel", "hunter-fantasy", "revenge-soda", "healing-daily", "relationship-drama", "literary-serial"]).optional().describe("styleId=webnovel일 때 장르"),
@@ -958,7 +949,7 @@ export function registerCloudTools(server, config, api) {
         endingStyle: z.string().nullable().optional(),
         emphasisCount: z.number().nullable().optional(),
         hasBgm: z.boolean().nullable().optional(),
-        sampleSize: z.number().optional(),
+        sampleSize: z.number().describe("표본 수 — 서버는 이 값이 0보다 커야 지문을 규격으로 인정한다(없으면 조용히 무시됨)"),
       }).passthrough().optional().describe("measure_channel_spec 의 fingerprint — 실측 규격(길이·컷·말끝)을 대본에 강제합니다"),
     },
     wrapCloudHandler(config, async ({
@@ -1002,7 +993,9 @@ export function registerCloudTools(server, config, api) {
           webnovelSubtypeId,
         },
         method: "POST",
-        timeoutMs: 240_000,
+        // 서버 최악 예산(리서치 40s + 생성 150s×2 = 340s)보다 크게 — 역전되면
+        // 클라는 실패로 끝나는데 서버는 계속 돌며 과금한다.
+        timeoutMs: 420_000,
       });
       const text = String(payload?.text || "").trim();
       if (!text) return textResult("대본 생성 결과가 비어 있습니다. 제목/브리프를 보강해 다시 시도하세요.", { isError: true });
@@ -1023,7 +1016,7 @@ export function registerCloudTools(server, config, api) {
       purpose: z.enum(["investment", "owner-occupancy", "move-up", "verification"]).optional().describe("기본 investment"),
       budget: z.string().optional().describe("예산/가격대"),
       notes: z.string().optional(),
-      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLength: z.number().int().min(500).max(12000).optional().describe("목표 글자수, 기본 5000. 서버 출력 상한(8192토큰 ≈ 한국어 12,300자)을 넘으면 대본이 중간에 잘리므로 12000 이 상한이다"),
       targetLanguageLabel: z.string().optional().describe("기본 '한국 (한국어)'"),
     },
     wrapCloudHandler(config, async ({ analysisType = "apartment-report", primaryTarget = "", secondaryTarget = "", region = "", title = "", storyText = "", purpose = "investment", budget = "", notes = "", targetLength = 5000, targetLanguageLabel = "한국 (한국어)" }) => {
@@ -1053,7 +1046,9 @@ export function registerCloudTools(server, config, api) {
           title,
         },
         method: "POST",
-        timeoutMs: 240_000,
+        // 서버 최악 예산(리서치 40s + 생성 150s×2 = 340s)보다 크게 — 역전되면
+        // 클라는 실패로 끝나는데 서버는 계속 돌며 과금한다.
+        timeoutMs: 420_000,
       });
       const text = String(payload?.text || "").trim();
       if (!text) return textResult("부동산 분석 대본 결과가 비어 있습니다.", { isError: true });
@@ -1074,7 +1069,7 @@ export function registerCloudTools(server, config, api) {
       purpose: z.enum(["startup", "investment", "site-selection", "verification"]).optional().describe("기본 startup"),
       budget: z.string().optional().describe("예산/운영 여력"),
       notes: z.string().optional(),
-      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLength: z.number().int().min(500).max(12000).optional().describe("목표 글자수, 기본 5000. 서버 출력 상한(8192토큰 ≈ 한국어 12,300자)을 넘으면 대본이 중간에 잘리므로 12000 이 상한이다"),
       targetLanguageLabel: z.string().optional().describe("기본 '한국 (한국어)'"),
     },
     wrapCloudHandler(config, async ({ analysisType = "commercial-district-report", primaryTarget = "", secondaryTarget = "", businessType = "", title = "", storyText = "", purpose = "startup", budget = "", notes = "", targetLength = 5000, targetLanguageLabel = "한국 (한국어)" }) => {
@@ -1104,7 +1099,9 @@ export function registerCloudTools(server, config, api) {
           title,
         },
         method: "POST",
-        timeoutMs: 240_000,
+        // 서버 최악 예산(리서치 40s + 생성 150s×2 = 340s)보다 크게 — 역전되면
+        // 클라는 실패로 끝나는데 서버는 계속 돌며 과금한다.
+        timeoutMs: 420_000,
       });
       const text = String(payload?.text || "").trim();
       if (!text) return textResult("상권 분석 대본 결과가 비어 있습니다.", { isError: true });
@@ -1457,7 +1454,7 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "measure_channel_spec",
-    "벤치마크 채널의 영상 표본(유튜브 URL ≤5)을 실측해 채널 규격 지문(길이·컷간격·컷/분·라우드니스·무음비율·자막 위치·말끝 스타일)을 만듭니다. 컴패니언 앱이 다운로드·샷감지·오디오 추출을 수행하고 서버가 집계합니다. 반환된 fingerprint 를 plan_shorts_video 의 channelFingerprint 로 넘기면 대본이 그 규격을 강제합니다.",
+    "벤치마크 채널의 영상 표본(유튜브 URL ≤5)을 실측해 채널 규격 지문(길이·컷간격·컷/분·라우드니스·무음비율·자막 위치·말끝 스타일)을 만듭니다. 말속도는 측정하지 않습니다. 컴패니언 앱이 다운로드·샷감지·오디오 추출을 수행하고 서버가 집계합니다. 반환된 fingerprint 를 plan_shorts_video 의 channelFingerprint 로 넘기면 대본이 그 규격을 강제합니다.",
     {
       videoUrls: z.array(z.string()).min(1).max(5).describe("표본 유튜브 URL 또는 11자 ID (조회수 상위 영상 권장)"),
     },
@@ -1526,6 +1523,9 @@ export function registerCloudTools(server, config, api) {
           notes.push(`표본 ${index + 1}: ${String(error?.message || error).slice(0, 100)}`);
         }
       }
+      // 말속도(cpsTarget)는 타임코드 전사가 있어야 산출된다. 이 도구는 전사를 하지 않으므로
+      // 그 축은 비워 둔다 — 재지 않은 것을 잰 척하지 않는다.
+      notes.push("말속도(cpsTarget)는 측정하지 않습니다 — 타임코드 전사가 필요합니다.");
       if (!specs.length) {
         return textResult(`표본 실측에 모두 실패했습니다. 컴패니언 앱 실행 여부를 확인하세요.\n${notes.join("\n")}`, { isError: true });
       }
@@ -1539,7 +1539,7 @@ export function registerCloudTools(server, config, api) {
       }
       return jsonResult({
         fingerprint: payload.fingerprint,
-        next: "이 fingerprint 객체를 plan_shorts_video 의 channelFingerprint 로 그대로 넘기세요 — 대본이 실측 규격(길이·컷·말속도·말끝)을 따르게 됩니다.",
+        next: "이 fingerprint 객체를 plan_shorts_video·stitch_timeline·write_script 의 channelFingerprint 로 그대로 넘기세요 — 길이·컷 리듬·말끝·자막 위치·BGM 이 이 규격을 따릅니다.",
         notes: notes.length ? notes : undefined,
         sampleCount: specs.length,
       });

package/lib/companion-client.mjs

@@ -1,4 +1,5 @@
-import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { closeSync, createWriteStream, mkdirSync, openSync, renameSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -157,20 +158,31 @@ export function parseContentDispositionFilename(headerValue) {
  * 성공 시 컴패니언이 파일을 삭제(1회성)하므로 저장 성공 후에만 소비된 것으로 본다.
  * 반환: { filePath, bytes } 또는 { error, status }
  */
-// 사용된 파일명이 이미 있으면 -2, -3 … 을 붙여 기존 출력을 덮어쓰지 않는다.
-function uniqueOutputPath(dir, fileName) {
+// wx 로 최종 경로를 먼저 예약한다. 존재 검사만 하면 여러 프로세스가 같은
+// 이름과 .part 파일을 골라 서로의 다운로드를 덮어쓴다.
+function reserveOutputPath(dir, fileName) {
   const ext = path.extname(fileName);
   const base = fileName.slice(0, fileName.length - ext.length);
   let candidate = path.join(dir, fileName);
   let counter = 2;
-  while (existsSync(candidate)) {
-    candidate = path.join(dir, `${base}-${counter}${ext}`);
-    counter += 1;
+  while (true) {
+    try {
+      closeSync(openSync(candidate, "wx", 0o600));
+      return candidate;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      candidate = path.join(dir, `${base}-${counter}${ext}`);
+      counter += 1;
+    }
   }
-  return candidate;
 }
 
 export async function downloadRenderOutput(companionUrl, jobId, outputDir, { suggestedName = "" } = {}) {
+  try {
+    mkdirSync(outputDir, { recursive: true });
+  } catch (error) {
+    return { error: `출력 폴더를 준비하지 못했습니다: ${String(error?.message || error)}`, status: 0 };
+  }
   let response;
   try {
     response = await fetch(
@@ -193,17 +205,20 @@ export async function downloadRenderOutput(companionUrl, jobId, outputDir, { sug
   const headerName = parseContentDispositionFilename(response.headers.get("content-disposition"));
   let fileName = sanitizeOutputFilename(suggestedName || headerName, `render-${jobId}.mp4`);
   if (!/\.[A-Za-z0-9]{1,5}$/u.test(fileName)) fileName += ".mp4"; // 확장자 없으면 mp4 보정
-  mkdirSync(outputDir, { recursive: true });
-  const finalPath = uniqueOutputPath(outputDir, fileName);
-  const partPath = `${finalPath}.part`;
-
+  let finalPath = "";
+  let partPath = "";
   try {
-    await pipeline(Readable.fromWeb(response.body), createWriteStream(partPath, { mode: 0o600 }));
+    finalPath = reserveOutputPath(outputDir, fileName);
+    partPath = `${finalPath}.${randomUUID()}.part`;
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(partPath, { flags: "wx", mode: 0o600 }));
+    const bytes = statSync(partPath).size;
     renameSync(partPath, finalPath);
+    return { bytes, filePath: finalPath };
   } catch (error) {
     // 중단 시 부분 파일 정리 — 잡은 다운로드 실패로 남아 재시도 가능(네트워크 abort 시 서버가 복구).
-    try { rmSync(partPath, { force: true }); } catch { /* ignore */ }
+    await response.body?.cancel().catch(() => {});
+    if (partPath) { try { rmSync(partPath, { force: true }); } catch { /* ignore */ } }
+    if (finalPath) { try { rmSync(finalPath, { force: true }); } catch { /* ignore */ } }
     return { error: `출력 저장 중 오류: ${String(error?.message || error)} — render_status로 상태 확인 후 다시 시도하세요.`, status: 0 };
   }
-  return { bytes: statSync(finalPath).size, filePath: finalPath };
 }