hyper-animator-codex 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Install the Hyper Animator Codex skill for Codex.",
   "type": "module",
   "bin": {

package/skills/hyper-animator-codex/SKILL.md

@@ -20,7 +20,7 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
    - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
    - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
 7. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
-8. If background music is requested or undecided, read `references/minimax-music-workflow.md` and prefer MiniMax generation when configured. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
+8. If background music is requested or undecided, read `references/minimax-music-workflow.md` and use `scripts/generate_minimax_music.mjs` for every MiniMax request. Do not construct MiniMax HTTP calls directly. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
 9. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
 10. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
 11. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.

package/skills/hyper-animator-codex/references/minimax-music-workflow.md

@@ -2,6 +2,10 @@
 
 Use this when the user wants generated background music or asks whether Hyper Animator Codex can create music for an animation.
 
+## Script-Only Rule
+
+Do not hand-assemble MiniMax HTTP requests in agent reasoning or shell commands. Always call `scripts/generate_minimax_music.mjs`. The script owns request validation, retry policy, error normalization, audio writing, metadata writing, and secret redaction.
+
 ## MiniMax Preference
 
 Prefer MiniMax before other background-music sources when `config/minimax.json` exists in the installed skill or `MINIMAX_API_KEY` and `MINIMAX_GROUP_ID` are present in the environment.
@@ -60,6 +64,13 @@ node scripts/generate_minimax_music.mjs \
 
 Use `--dry-run` before a real call when checking config, request shape, or model choice.
 
+To generate a request JSON file for a scripted call:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --request-json hyper-animator-output/music/minimax-request.json
+```
+
 ## Beat Sync
 
 After music generation succeeds, analyze the generated audio:

package/skills/hyper-animator-codex/scripts/generate_minimax_music.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,7 +10,7 @@ import {
   validateMinimaxConfig,
 } from "./minimax_runtime_config.mjs";
 
-const ENDPOINT = "https://api.minimaxi.com/v1/music_generation";
+const DEFAULT_ENDPOINT = "https://api.minimaxi.com/v1/music_generation";
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const skillRoot = dirname(scriptDir);
 
@@ -28,15 +28,16 @@ function parseArgs(args) {
   const parsed = {
     prompt: undefined,
     lyrics: undefined,
-    lyrics_optimizer: false,
-    is_instrumental: true,
-    output_dir: join(process.cwd(), "hyper-animator-output", "music"),
-    output_format: "hex",
-    audio_format: "mp3",
-    sample_rate: 44100,
-    bitrate: 256000,
+    lyrics_optimizer: undefined,
+    is_instrumental: undefined,
+    output_dir: undefined,
+    output_format: undefined,
+    audio_format: undefined,
+    sample_rate: undefined,
+    bitrate: undefined,
     model: undefined,
     config_path: undefined,
+    request_json: undefined,
     dry_run: false,
   };
 
@@ -76,6 +77,9 @@ function parseArgs(args) {
     } else if (arg === "--config") {
       parsed.config_path = requireValue(args, index, arg);
       index += 1;
+    } else if (arg === "--request-json") {
+      parsed.request_json = requireValue(args, index, arg);
+      index += 1;
     } else if (arg === "--dry-run") {
       parsed.dry_run = true;
     } else if (arg === "--help" || arg === "-h") {
@@ -105,41 +109,108 @@ Options:
   --bitrate <bits>             32000, 64000, 128000, or 256000; default 256000
   --model <model>              music-2.6 or music-2.6-free
   --config <file>              Explicit MiniMax config JSON
+  --request-json <file>        Read request options from a JSON file
   --dry-run                    Print redacted request without contacting MiniMax
 `);
 }
 
+async function readRequestJson(path) {
+  if (!path) {
+    return {};
+  }
+
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw Object.assign(new Error(`--request-json must contain a JSON object: ${path}`), {
+      kind: "validation",
+    });
+  }
+
+  return parsed;
+}
+
+function mergeOptions(jsonOptions, cliOptions) {
+  return {
+    ...cliOptions,
+    prompt: cliOptions.prompt ?? jsonOptions.prompt,
+    lyrics: cliOptions.lyrics ?? jsonOptions.lyrics,
+    lyrics_optimizer: cliOptions.lyrics_optimizer ?? Boolean(jsonOptions.lyrics_optimizer),
+    is_instrumental: cliOptions.is_instrumental ?? jsonOptions.is_instrumental ?? true,
+    output_dir: cliOptions.output_dir ?? jsonOptions.output_dir ?? join(process.cwd(), "hyper-animator-output", "music"),
+    output_format: cliOptions.output_format ?? jsonOptions.output_format ?? "hex",
+    audio_format: cliOptions.audio_format ?? jsonOptions.audio_format ?? "mp3",
+    sample_rate: cliOptions.sample_rate ?? jsonOptions.sample_rate ?? 44100,
+    bitrate: cliOptions.bitrate ?? jsonOptions.bitrate ?? 256000,
+    model: cliOptions.model ?? jsonOptions.model,
+  };
+}
+
+function endpointFromEnv(env = process.env) {
+  return env.MINIMAX_MUSIC_ENDPOINT || DEFAULT_ENDPOINT;
+}
+
+function timeoutFromEnv(env = process.env) {
+  const value = Number.parseInt(env.MINIMAX_REQUEST_TIMEOUT_MS || "60000", 10);
+  return Number.isFinite(value) && value > 0 ? value : 60000;
+}
+
+function makeErrorEnvelope(error, attempts = 0) {
+  return {
+    ok: false,
+    provider: "minimax",
+    error: {
+      kind: error.kind || "validation",
+      message: error.message,
+      retryable: Boolean(error.retryable),
+      http_status: error.http_status ?? null,
+      status_code: error.status_code ?? null,
+    },
+    attempts,
+  };
+}
+
+function minimaxError(message, fields = {}) {
+  const error = new Error(message);
+  Object.assign(error, fields);
+  return error;
+}
+
+function printJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
 function validateOptions(options) {
   if (!options.prompt || options.prompt.trim().length === 0) {
-    throw new Error("--prompt is required");
+    throw Object.assign(new Error("--prompt is required"), { kind: "validation" });
   }
 
   if (options.prompt.length > 2000) {
-    throw new Error("--prompt must be 2000 characters or fewer");
+    throw Object.assign(new Error("--prompt must be 2000 characters or fewer"), { kind: "validation" });
   }
 
   if (!["hex", "url"].includes(options.output_format)) {
-    throw new Error("--output-format must be hex or url");
+    throw Object.assign(new Error("--output-format must be hex or url"), { kind: "validation" });
   }
 
   if (!["mp3", "wav", "pcm"].includes(options.audio_format)) {
-    throw new Error("--format must be mp3, wav, or pcm");
+    throw Object.assign(new Error("--format must be mp3, wav, or pcm"), { kind: "validation" });
   }
 
   if (![16000, 24000, 32000, 44100].includes(options.sample_rate)) {
-    throw new Error("--sample-rate must be 16000, 24000, 32000, or 44100");
+    throw Object.assign(new Error("--sample-rate must be 16000, 24000, 32000, or 44100"), { kind: "validation" });
   }
 
   if (![32000, 64000, 128000, 256000].includes(options.bitrate)) {
-    throw new Error("--bitrate must be 32000, 64000, 128000, or 256000");
+    throw Object.assign(new Error("--bitrate must be 32000, 64000, 128000, or 256000"), { kind: "validation" });
   }
 
   if (!options.is_instrumental && !options.lyrics && !options.lyrics_optimizer) {
-    throw new Error("Vocal MiniMax generation requires --lyrics or --lyrics-optimizer");
+    throw Object.assign(new Error("Vocal MiniMax generation requires --lyrics or --lyrics-optimizer"), { kind: "validation" });
   }
 
   if (options.lyrics && options.lyrics.length > 3500) {
-    throw new Error("--lyrics must be 3500 characters or fewer");
+    throw Object.assign(new Error("--lyrics must be 3500 characters or fewer"), { kind: "validation" });
   }
 }
 
@@ -202,48 +273,148 @@ function decodeHexAudio(value) {
   return Buffer.from(value, "hex");
 }
 
-async function callMiniMax(config, request) {
-  const response = await fetch(ENDPOINT, {
+function classifyHttpStatus(status) {
+  if (status === 401 || status === 403) {
+    return { kind: "auth", retryable: false };
+  }
+
+  if (status === 429) {
+    return { kind: "rate_limit", retryable: true };
+  }
+
+  if (status >= 500) {
+    return { kind: "server", retryable: true };
+  }
+
+  return { kind: "response", retryable: false };
+}
+
+async function fetchWithTimeout(url, options, timeoutMs) {
+  if (!URL.canParse(url)) {
+    throw minimaxError(`MiniMax endpoint is not a valid URL: ${url}`, {
+      kind: "validation",
+      retryable: false,
+    });
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw minimaxError("MiniMax request timed out", { kind: "timeout", retryable: true });
+    }
+
+    if (typeof error?.cause?.code === "string") {
+      throw minimaxError(`MiniMax network error: ${error.message}`, { kind: "network", retryable: true });
+    }
+
+    throw minimaxError(`MiniMax request setup failed: ${error.message}`, {
+      kind: "response",
+      retryable: false,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function callMiniMax(config, request, { endpoint, timeoutMs }) {
+  const response = await fetchWithTimeout(endpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.api_key}`,
     },
     body: JSON.stringify(request),
-  });
+  }, timeoutMs);
 
   const text = await response.text();
-  let json;
+  let json = null;
+
+  if (!response.ok) {
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+
+    const message = json?.base_resp?.status_msg || `HTTP ${response.status}`;
+    throw minimaxError(`MiniMax request failed: ${message}`, {
+      ...classifyHttpStatus(response.status),
+      http_status: response.status,
+      status_code: json?.base_resp?.status_code ?? null,
+    });
+  }
 
   try {
     json = JSON.parse(text);
   } catch (error) {
-    throw new Error(`MiniMax returned non-JSON response with HTTP ${response.status}`);
-  }
-
-  if (!response.ok) {
-    const message = json.base_resp?.status_msg || `HTTP ${response.status}`;
-    throw new Error(`MiniMax request failed: ${message}`);
+    throw minimaxError(`MiniMax returned non-JSON response with HTTP ${response.status}`, {
+      kind: "response",
+      retryable: false,
+      http_status: response.status,
+    });
   }
 
   const statusCode = json.base_resp?.status_code;
   if (statusCode !== 0) {
     const message = json.base_resp?.status_msg || "unknown MiniMax error";
-    throw new Error(`MiniMax request failed with status_code ${statusCode}: ${message}`);
+    throw minimaxError(`MiniMax request failed with status_code ${statusCode}: ${message}`, {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   if (json.data?.status !== 2) {
-    throw new Error(`MiniMax generation is not complete; data.status is ${json.data?.status}`);
+    throw minimaxError(`MiniMax generation is not complete; data.status is ${json.data?.status}`, {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   if (!json.data?.audio) {
-    throw new Error("MiniMax response did not include data.audio");
+    throw minimaxError("MiniMax response did not include data.audio", {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   return json;
 }
 
-async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
+async function callMiniMaxWithRetries(config, request, { endpoint, timeoutMs, maxRetries = 2 }) {
+  let attempts = 0;
+
+  while (attempts <= maxRetries) {
+    attempts += 1;
+
+    try {
+      return {
+        responseJson: await callMiniMax(config, request, { endpoint, timeoutMs }),
+        attempts,
+      };
+    } catch (error) {
+      if (!error.retryable || attempts > maxRetries) {
+        error.attempts = attempts;
+        throw error;
+      }
+    }
+  }
+
+  throw minimaxError("MiniMax request failed", { kind: "network", retryable: true, attempts });
+}
+
+async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint }) {
   await mkdir(outputDir, { recursive: true });
 
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -261,7 +432,7 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
     metadataPath,
     `${JSON.stringify({
       provider: "minimax",
-      endpoint: ENDPOINT,
+      endpoint,
       request,
       response: {
         base_resp: responseJson.base_resp,
@@ -283,64 +454,90 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2));
+  try {
+    const cliOptions = parseArgs(process.argv.slice(2));
+    const endpoint = endpointFromEnv();
+    const timeoutMs = timeoutFromEnv();
 
-  if (options.help) {
-    printHelp();
-    return;
-  }
+    if (cliOptions.help) {
+      printHelp();
+      return;
+    }
 
-  validateOptions(options);
+    const requestJson = await readRequestJson(cliOptions.request_json);
+    const options = mergeOptions(requestJson, cliOptions);
 
-  const runtime = await readMinimaxRuntimeConfig({
-    skillRoot,
-    env: process.env,
-    configPath: options.config_path,
-  });
+    validateOptions(options);
 
-  if (!runtime) {
-    throw new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID.");
-  }
+    let runtime;
+    try {
+      runtime = await readMinimaxRuntimeConfig({
+        skillRoot,
+        env: process.env,
+        configPath: options.config_path,
+      });
+    } catch (error) {
+      throw Object.assign(error, { kind: "config", retryable: false });
+    }
+
+    if (!runtime) {
+      throw Object.assign(new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID."), {
+        kind: "config",
+        retryable: false,
+      });
+    }
+
+    let request;
+    try {
+      request = buildRequest(options, runtime.config);
+    } catch (error) {
+      throw Object.assign(error, { kind: "config", retryable: false });
+    }
+    const redactedConfig = redactMinimaxConfig(runtime.config);
+
+    if (options.dry_run) {
+      printJson({
+        ok: true,
+        dry_run: true,
+        provider: "minimax",
+        endpoint,
+        config: {
+          source: runtime.source,
+          path: runtime.configPath,
+          redacted: redactedConfig,
+        },
+        request_path: cliOptions.request_json,
+        request,
+        output_dir: options.output_dir,
+      });
+      return;
+    }
 
-  const request = buildRequest(options, runtime.config);
-  const redactedConfig = redactMinimaxConfig(runtime.config);
+    const { responseJson, attempts } = await callMiniMaxWithRetries(runtime.config, request, {
+      endpoint,
+      timeoutMs,
+    });
+    const output = await writeAudioOutput({
+      responseJson,
+      request,
+      outputDir: options.output_dir,
+      prompt: options.prompt,
+      endpoint,
+    });
 
-  if (options.dry_run) {
-    console.log(JSON.stringify({
+    printJson({
       ok: true,
-      dry_run: true,
       provider: "minimax",
-      endpoint: ENDPOINT,
-      config: {
-        source: runtime.source,
-        path: runtime.configPath,
-        redacted: redactedConfig,
-      },
-      request,
-      output_dir: options.output_dir,
-    }, null, 2));
-    return;
+      model: request.model,
+      attempts,
+      output_path: output.audioPath,
+      metadata_path: output.metadataPath,
+      beat_analysis_command: `python3 scripts/analyze_music_beats.py ${output.audioPath} -o ${join(options.output_dir, "beat-map.json")} --fps 60 --pretty`,
+    });
+  } catch (error) {
+    printJson(makeErrorEnvelope(error, error.attempts ?? 0));
+    process.exitCode = 1;
   }
-
-  const responseJson = await callMiniMax(runtime.config, request);
-  const output = await writeAudioOutput({
-    responseJson,
-    request,
-    outputDir: options.output_dir,
-    prompt: options.prompt,
-  });
-
-  console.log(JSON.stringify({
-    ok: true,
-    provider: "minimax",
-    model: request.model,
-    output_path: output.audioPath,
-    metadata_path: output.metadataPath,
-    beat_analysis_command: `python3 scripts/analyze_music_beats.py ${output.audioPath} -o ${join(options.output_dir, "beat-map.json")} --fps 60 --pretty`,
-  }, null, 2));
 }
 
-main().catch((error) => {
-  console.error(`Error: ${error.message}`);
-  process.exitCode = 1;
-});
+main();