@vibeframe/mcp-server 0.102.0 → 0.103.0

package/dist/index.js

@@ -7643,9 +7643,14 @@ End on the product name, offer, or command. Avoid adding a new idea in the
 final beat.
 `;
 }
-function buildProjectClaudeMd(name) {
+function buildProjectAgentsMd(name) {
   return `# ${name} \u2014 Scene Authoring Project
 
+This is the canonical cross-agent guidance file for this scene project.
+Claude Code imports it through \`CLAUDE.md\`; Codex, Cursor, Aider,
+Gemini CLI, OpenCode, and other bash-capable agents should read it
+directly.
+
 This project is **bilingual**: it works with both VibeFrame (\`vibe\`) and
 HeyGen Hyperframes (\`hyperframes\`). You can run either CLI inside this
 directory.
@@ -7685,6 +7690,8 @@ Browse named styles: \`vibe scene list-styles\`. Re-seed from one with
 
 ## Skills \u2014 USE THESE FIRST
 
+@SKILL.md
+
 **Always invoke the relevant skill before authoring scenes.** Skills encode
 framework-specific patterns (GSAP timeline registration, data-attribute
 semantics, VibeFrame pipeline conventions) that are NOT in generic web docs.
@@ -7753,6 +7760,17 @@ vibe scene lint --json    # structured output for agent loops
 \`\`\`
 `;
 }
+function buildProjectClaudeMd(name) {
+  return `@AGENTS.md
+
+# ${name} \u2014 Claude Code Overrides
+
+This file imports \`AGENTS.md\`; keep cross-agent VibeFrame and
+Hyperframes instructions there so Codex, Cursor, Aider, Gemini CLI, and
+OpenCode see the same project rules. Add Claude-Code-specific notes below
+only when this project needs them.
+`;
+}
 function buildSceneGitignore() {
   return `# VibeFrame \u2014 caches, checkpoints, and project-scope config.yaml (may contain API keys)
 .vibeframe/
@@ -7792,6 +7810,7 @@ function describeSceneScaffold(opts) {
   }
   if (profile === "agent" || profile === "full") {
     groups.agent = [
+      resolve2(dir, "AGENTS.md"),
       resolve2(dir, "SKILL.md"),
       resolve2(dir, "references"),
       resolve2(dir, "CLAUDE.md")
@@ -7871,9 +7890,24 @@ async function scaffoldSceneProject(opts) {
     created.push(vibePath);
   }
   if (profile === "agent" || profile === "full") {
+    const agentsPath = resolve2(dir, "AGENTS.md");
+    if (await pathExists(agentsPath)) {
+      skipped2.push(agentsPath);
+    } else {
+      await writeFile(agentsPath, buildProjectAgentsMd(name), "utf-8");
+      created.push(agentsPath);
+    }
     const claudePath = resolve2(dir, "CLAUDE.md");
     if (await pathExists(claudePath)) {
-      skipped2.push(claudePath);
+      const existing = await readFile2(claudePath, "utf-8");
+      if (existing.includes("@AGENTS.md")) {
+        skipped2.push(claudePath);
+      } else {
+        await writeFile(claudePath, `@AGENTS.md
+
+${existing}`, "utf-8");
+        merged.push(claudePath);
+      }
     } else {
       await writeFile(claudePath, buildProjectClaudeMd(name), "utf-8");
       created.push(claudePath);
@@ -25606,6 +25640,7 @@ __export(config_exports, {
   USER_CONFIG_DIR: () => USER_CONFIG_DIR,
   USER_CONFIG_PATH: () => USER_CONFIG_PATH,
   createDefaultConfig: () => createDefaultConfig,
+  findProjectConfigPath: () => findProjectConfigPath,
   getActiveScope: () => getActiveScope,
   getApiKeyFromConfig: () => getApiKeyFromConfig,
   getConfigDir: () => getConfigDir,
@@ -450988,9 +451023,22 @@ function backdropCacheDescriptor(opts) {
     provider: opts.provider,
     quality: opts.quality,
     size: opts.size,
+    ratio: opts.ratio,
     ext: "png"
   });
 }
+function imageRatioForSize(size) {
+  switch (size) {
+    case "1024x1024":
+      return "1:1";
+    case "1024x1536":
+      return "2:3";
+    case "1536x1024":
+      return "3:2";
+    default:
+      return "16:9";
+  }
+}
 function videoCacheDescriptor(opts) {
   return cacheAssetDescriptor("video", {
     beatId: opts.beatId,
@@ -451319,6 +451367,7 @@ async function createBuildPlan(opts) {
   }
   const storyboardMd = await readFile13(storyboardPath, "utf-8");
   const validation3 = validateStoryboardMarkdown(storyboardMd);
+  const validationIssues = [...validation3.issues];
   const parsed = parseStoryboard(storyboardMd);
   let sourceBeats = parsed.beats;
   if (opts.beat) {
@@ -451341,6 +451390,7 @@ async function createBuildPlan(opts) {
   const mode = opts.mode ?? config4.config.build.mode;
   const imageQuality = opts.imageQuality ?? config4.config.build.imageQuality ?? "hd";
   const imageSize2 = opts.imageSize ?? config4.config.build.imageSize ?? "1536x1024";
+  const imageRatio = imageRatioForSize(imageSize2);
   const needsComposer = includeCompose && mode !== "agent" && sourceBeats.some((beat) => !existsSync31(join30(projectDir, `compositions/scene-${beat.id}.html`)));
   const resolved = await resolvePlanProviders({
     projectDir,
@@ -451390,7 +451440,8 @@ async function createBuildPlan(opts) {
       cue: backdropPrompt,
       provider: resolved.image.resolved,
       quality: imageQuality,
-      size: imageSize2
+      size: imageSize2,
+      ratio: imageRatio
     }) : null;
     const videoCache = videoPrompt && !videoReference ? videoCacheDescriptor({
       beatId: beat.id,
@@ -451484,7 +451535,8 @@ async function createBuildPlan(opts) {
       }
     }
     if (narration?.willGenerate) noteProviderNeed(resolved.narration, "Narration");
-    if (backdrop?.willGenerate) noteProviderNeed(resolved.image, "Backdrop generation");
+    if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
+      noteProviderNeed(resolved.image, "Backdrop generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
@@ -451506,23 +451558,35 @@ async function createBuildPlan(opts) {
     };
   });
   providerResolution.push(...providerResolutionsForPlan(resolved, beats, opts, includeAssets));
+  if (includeAssets && !opts.skipBackdrop && !isSupportedBuildImageProvider(resolved.image.resolved)) {
+    const unsupportedBackdropBeats = beats.filter(
+      (beat) => isBuildGeneratedBackdropPlan(beat.assets.backdrop)
+    );
+    for (const beat of unsupportedBackdropBeats) {
+      validationIssues.push({
+        severity: "error",
+        code: "UNSUPPORTED_BUILD_IMAGE_PROVIDER",
+        beatId: beat.id,
+        message: `Build backdrop generation supports openai, gemini, and grok. Beat "${beat.id}" resolves image provider "${resolved.image.resolved}"; rerun with one of those or replace the backdrop cue with a project asset path.`
+      });
+    }
+    if (unsupportedBackdropBeats.length > 0) {
+      const beatFlag = opts.beat ? ` --beat ${opts.beat}` : "";
+      retryWith.push(
+        `vibe build ${projectDir}${beatFlag} --stage assets --image-provider openai --json`
+      );
+    }
+  }
+  const validationOk = !validationIssues.some((issue) => issue.severity === "error");
   if (!existsSync31(join30(projectDir, config4.config.composition.entry))) {
     missing.add("root-composition");
-    if (validation3.ok) retryWith.push(`vibe build ${projectDir} --stage sync --json`);
+    if (validationOk) retryWith.push(`vibe build ${projectDir} --stage sync --json`);
   }
   if (config4.legacy) {
     warnings.push(
       `Using legacy ${config4.source}; write ${projectDir}/vibe.config.json to use the TO-BE project contract.`
     );
   }
-  if (resolved.image.resolved !== "openai" && beats.some((beat) => {
-    const backdrop = beat.assets.backdrop;
-    return backdrop && !["referenced-asset", "invalid-reference", "stage-skipped"].includes(backdrop.reason);
-  }) && !opts.skipBackdrop) {
-    warnings.push(
-      `Image provider "${resolved.image.resolved}" is not supported by build assets yet; use --image-provider openai.`
-    );
-  }
   if (!validation3.ok) {
     retryWith.push(
       `vibe storyboard validate ${projectDir} --json`,
@@ -451533,7 +451597,7 @@ async function createBuildPlan(opts) {
     projectDir,
     config: config4,
     stage,
-    status: validation3.ok ? "ready" : "invalid",
+    status: validationOk ? "ready" : "invalid",
     currentStage: stage,
     mode,
     beat: opts.beat ?? null,
@@ -451545,8 +451609,8 @@ async function createBuildPlan(opts) {
     warnings,
     retryWith,
     validation: {
-      ok: validation3.ok,
-      issues: validation3.issues
+      ok: validationOk,
+      issues: validationIssues
     }
   });
 }
@@ -451573,6 +451637,15 @@ function finalizeBuildPlan(plan) {
     retryWith: unique2(plan.retryWith)
   };
 }
+function isBuildGeneratedBackdropPlan(asset) {
+  if (!asset || asset.kind !== "backdrop") return false;
+  return !["referenced-asset", "invalid-reference", "stage-skipped"].includes(asset.reason);
+}
+function isSupportedBuildImageProvider(provider) {
+  return SUPPORTED_BUILD_IMAGE_PROVIDERS.includes(
+    provider
+  );
+}
 function nextCommandsForPlan(plan) {
   if (plan.status === "invalid") return unique2(plan.retryWith);
   const commands = [];
@@ -451872,7 +451945,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname18(dir);
   }
 }
-var import_dotenv2, BACKDROP_COST_USD, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD;
+var import_dotenv2, BACKDROP_COST_USD, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
 var init_build_plan = __esm({
   "../cli/src/commands/_shared/build-plan.ts"() {
     "use strict";
@@ -451891,6 +451964,7 @@ var init_build_plan = __esm({
     MUSIC_COST_USD = 0.5;
     ELEVENLABS_NARRATION_COST_USD = 0.05;
     COMPOSE_COST_USD = 0.06;
+    SUPPORTED_BUILD_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
   }
 });
 
@@ -451916,22 +451990,35 @@ function applySuggestion(project, suggestion) {
   if (clipIds.length === 0) return false;
   const clipId = clipIds[0];
   switch (type) {
-    case "trim":
-      if (params.newDuration) {
-        return project.trimClipEnd(clipId, params.newDuration);
+    case "trim": {
+      const newDuration = params.newDuration;
+      if (typeof newDuration === "number") {
+        return project.trimClipEnd(clipId, newDuration);
       }
       break;
-    case "add-effect":
-      if (params.effectType) {
+    }
+    case "add-effect": {
+      const effectType = params.effectType;
+      if (typeof effectType === "string") {
+        const startTime = typeof params.startTime === "number" ? params.startTime : 0;
+        const duration = typeof params.duration === "number" ? params.duration : 1;
+        const rawEffectParams = params.effectParams && typeof params.effectParams === "object" ? params.effectParams : {};
+        const effectParams = {};
+        for (const [k, v] of Object.entries(rawEffectParams)) {
+          if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            effectParams[k] = v;
+          }
+        }
         const effect = project.addEffect(clipId, {
-          type: params.effectType,
-          startTime: params.startTime || 0,
-          duration: params.duration || 1,
-          params: params.effectParams || {}
+          type: effectType,
+          startTime,
+          duration,
+          params: effectParams
         });
         return effect !== null;
       }
       break;
+    }
     case "delete":
       return project.removeClip(clipId);
   }
@@ -453526,6 +453613,7 @@ function isActiveStatus(status) {
 }
 function providerStatusCommand(record) {
   if (record.jobType === "generate-video") {
+    if (record.provider !== "runway" && record.provider !== "kling") return void 0;
     const type = record.provider === "kling" && record.providerTaskType ? ` --type ${record.providerTaskType}` : "";
     return `vibe generate video-status ${record.providerTaskId} -p ${record.provider}${type} --json`;
   }
@@ -454625,19 +454713,18 @@ async function dispatchBackdrop(beat, ctx) {
   if (reference) return referencePrimitiveOutcome("backdrop", beat, ctx, reference);
   const prompt3 = stringOrUndefined4(beat.cues?.backdrop);
   if (!prompt3) return { status: "no-cue" };
-  if (ctx.imageProvider !== "openai") {
-    const error = `image provider "${ctx.imageProvider}" not yet supported (use openai)`;
-    ctx.onProgress({ type: "backdrop-failed", beatId: beat.id, error });
-    return { status: "failed", error };
-  }
   const rel = `assets/backdrop-${beat.id}.png`;
   const abs = join33(ctx.projectDir, rel);
+  const size = ctx.imageSize ?? "1536x1024";
+  const ratio = imageRatioForSize(size);
+  const metadataOptions = { quality: ctx.imageQuality, size, ratio };
   const cache = backdropCacheDescriptor({
     beatId: beat.id,
     cue: prompt3,
     provider: ctx.imageProvider,
     quality: ctx.imageQuality,
-    size: ctx.imageSize ?? "1536x1024"
+    size,
+    ratio
   });
   const metadataPath = assetMetadataPath("backdrop", beat.id);
   if (existsSync35(abs) && !ctx.force) {
@@ -454648,7 +454735,7 @@ async function dispatchBackdrop(beat, ctx) {
       beatId: beat.id,
       cue: prompt3,
       provider: ctx.imageProvider,
-      options: { quality: ctx.imageQuality, size: ctx.imageSize ?? "1536x1024" },
+      options: metadataOptions,
       cacheKey: cache.key
     })) {
       ctx.onProgress({ type: "backdrop-cached", beatId: beat.id, path: rel });
@@ -454673,7 +454760,7 @@ async function dispatchBackdrop(beat, ctx) {
       beatId: beat.id,
       cue: prompt3,
       provider: ctx.imageProvider,
-      options: { quality: ctx.imageQuality, size: ctx.imageSize ?? "1536x1024" },
+      options: metadataOptions,
       cacheKey: cache.key,
       canonicalPath: rel,
       cachePath: cache.path
@@ -454689,27 +454776,14 @@ async function dispatchBackdrop(beat, ctx) {
       freshness: "fresh"
     };
   }
-  loadSceneBuildEnv(ctx.projectDir);
-  const apiKey = await getApiKeyFromConfig("openai", { cwd: ctx.projectDir }) ?? process.env.OPENAI_API_KEY ?? "";
-  if (!apiKey) {
-    const error = "OPENAI_API_KEY not set \u2014 cannot dispatch backdrop";
-    ctx.onProgress({ type: "backdrop-failed", beatId: beat.id, error });
-    return { status: "failed", error };
-  }
-  const provider = new OpenAIImageProvider();
-  await provider.initialize({ apiKey });
-  const result = await provider.generateImage(prompt3, {
-    model: "gpt-image-2",
-    size: ctx.imageSize,
-    quality: ctx.imageQuality
-  });
-  if (!result.success || !result.images?.[0]?.base64) {
-    const error = result.error ?? "no image data returned";
+  const generated = await generateBackdropImage(prompt3, ctx, ratio);
+  if (!generated.success) {
+    const error = generated.error;
     ctx.onProgress({ type: "backdrop-failed", beatId: beat.id, error });
     return { status: "failed", error };
   }
   await mkdir12(dirname20(abs), { recursive: true });
-  const buffer = Buffer.from(result.images[0].base64, "base64");
+  const buffer = generated.buffer;
   await writeFile19(abs, buffer);
   await mkdir12(dirname20(cacheAbs), { recursive: true });
   await writeFile19(cacheAbs, buffer);
@@ -454718,8 +454792,8 @@ async function dispatchBackdrop(beat, ctx) {
     kind: "backdrop",
     beatId: beat.id,
     cue: prompt3,
-    provider: "openai",
-    options: { quality: ctx.imageQuality, size: ctx.imageSize ?? "1536x1024" },
+    provider: ctx.imageProvider,
+    options: metadataOptions,
     cacheKey: cache.key,
     canonicalPath: rel,
     cachePath: cache.path
@@ -454728,18 +454802,75 @@ async function dispatchBackdrop(beat, ctx) {
     type: "backdrop-generated",
     beatId: beat.id,
     path: rel,
-    provider: "openai"
+    provider: ctx.imageProvider
   });
   return {
     status: "generated",
     path: rel,
-    provider: "openai",
+    provider: ctx.imageProvider,
     cachePath: cache.path,
     cacheKey: cache.key,
     metadataPath,
     freshness: "fresh"
   };
 }
+async function generateBackdropImage(prompt3, ctx, ratio) {
+  loadSceneBuildEnv(ctx.projectDir);
+  const keyInfo = imageProviderKeyInfo(ctx.imageProvider);
+  const apiKey = await getApiKeyFromConfig(keyInfo.configKey, { cwd: ctx.projectDir }) ?? process.env[keyInfo.envVar] ?? "";
+  if (!apiKey) {
+    return {
+      success: false,
+      error: `${keyInfo.envVar} not set \u2014 cannot dispatch backdrop with ${ctx.imageProvider}`
+    };
+  }
+  if (ctx.imageProvider === "openai") {
+    const provider2 = new OpenAIImageProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.generateImage(prompt3, {
+      model: "gpt-image-2",
+      size: ctx.imageSize,
+      quality: ctx.imageQuality
+    });
+    return imageBufferFromResult(result2);
+  }
+  if (ctx.imageProvider === "gemini") {
+    const provider2 = new GeminiProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.generateImage(prompt3, {
+      model: "flash",
+      aspectRatio: ratio
+    });
+    return imageBufferFromResult(result2);
+  }
+  const provider = new GrokProvider();
+  await provider.initialize({ apiKey });
+  const result = await provider.generateImage(prompt3, {
+    aspectRatio: ratio,
+    n: 1
+  });
+  return imageBufferFromResult(result);
+}
+async function imageBufferFromResult(result) {
+  const image = result.images?.[0];
+  if (!result.success || !image) {
+    return { success: false, error: result.error ?? "no image data returned" };
+  }
+  if (image.base64) return { success: true, buffer: Buffer.from(image.base64, "base64") };
+  if (image.url) {
+    const response = await fetch(image.url);
+    if (!response.ok) {
+      return { success: false, error: `failed to download image: HTTP ${response.status}` };
+    }
+    return { success: true, buffer: Buffer.from(await response.arrayBuffer()) };
+  }
+  return { success: false, error: "no image data returned" };
+}
+function imageProviderKeyInfo(provider) {
+  if (provider === "gemini") return { configKey: "google", envVar: "GOOGLE_API_KEY" };
+  if (provider === "grok") return { configKey: "xai", envVar: "XAI_API_KEY" };
+  return { configKey: "openai", envVar: "OPENAI_API_KEY" };
+}
 async function dispatchVideo(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
@@ -470125,7 +470256,10 @@ async function executeSuggestEdit(options) {
     }
     return { success: true, suggestions };
   } catch (error) {
-    return { success: false, error: `Suggest failed: ${error instanceof Error ? error.message : String(error)}` };
+    return {
+      success: false,
+      error: `Suggest failed: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.102.0",
+  "version": "0.103.0",
   "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -57,8 +57,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/core": "0.102.0",
-    "@vibeframe/cli": "0.102.0"
+    "@vibeframe/cli": "0.103.0",
+    "@vibeframe/core": "0.103.0"
   },
   "engines": {
     "node": ">=20"