@hmanlab/mmx 0.4.3

package/opencode/plugin/mmx-tools.ts

@@ -0,0 +1,362 @@
+// mmx-tools.ts
+//
+// OpenCode plugin that wraps the official MiniMax mmx-cli so the LLM can
+// generate images, video, music, speech, run web search, describe images,
+// and check Token Plan quota — all from inside an OpenCode session without
+// leaving the chat.
+//
+// Requires once on the machine:
+//   npm install -g mmx-cli
+//   mmx auth login --api-key sk-xxxxx
+// After that, no key is needed in opencode.
+//
+// All generated files default to ~/Desktop/mmx-output/. The user can override
+// the default directory permanently via the MMX_OUTPUT_DIR env var; the LLM
+// should never pass out_dir / out_path unless the user explicitly asked.
+
+import { tool } from "@opencode-ai/plugin"
+import { homedir } from "node:os"
+import { basename, dirname, join, resolve, isAbsolute } from "node:path"
+import { mkdirSync, existsSync } from "node:fs"
+
+const DEFAULT_OUT_DIR = join(homedir(), "Desktop", "mmx-output")
+
+function resolveOutDir(outDir: string | undefined, worktree: string): string {
+  const target = outDir ?? process.env.MMX_OUTPUT_DIR ?? DEFAULT_OUT_DIR
+  return isAbsolute(target) ? target : resolve(worktree, target)
+}
+
+function isSuspiciousOutDir(absPath: string): boolean {
+  const home = homedir()
+  const suspects = [home, join(home, "Desktop"), "/tmp", "/private/tmp", "."]
+  return absPath === "" || suspects.includes(absPath)
+}
+
+function warnSuspiciousOutDir(originalArg: string, usedInstead: string): string {
+  return `Note: out_dir/out_path "${originalArg}" looks like a mistake (home directory, Desktop root, /tmp, or cwd). Saving to "${usedInstead}" instead. Pass an explicit subdirectory to override.`
+}
+
+function resolveFilePath(
+  argsOutPath: string | undefined,
+  worktree: string,
+  defaultFileName: string,
+): { filePath: string; wasSuspicious: boolean; originalArg: string | undefined } {
+  const envDir = process.env.MMX_OUTPUT_DIR ?? DEFAULT_OUT_DIR
+  const requested = argsOutPath ?? join(envDir, defaultFileName)
+  const requestedDirAbs = isAbsolute(requested) ? dirname(requested) : resolve(worktree, dirname(requested))
+  if (isSuspiciousOutDir(requestedDirAbs)) {
+    return {
+      filePath: join(DEFAULT_OUT_DIR, basename(requested)),
+      wasSuspicious: true,
+      originalArg: argsOutPath,
+    }
+  }
+  return {
+    filePath: isAbsolute(requested) ? requested : join(requestedDirAbs, basename(requested)),
+    wasSuspicious: false,
+    originalArg: argsOutPath,
+  }
+}
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+async function runMmx(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(["mmx", ...args], { stdout: "pipe", stderr: "pipe" })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  return { stdout, stderr, exitCode }
+}
+
+export default async () => {
+  return {
+    tool: {
+      // ──────────────────────────────────────────────────────────────────
+      // IMAGE GENERATION (primary tool)
+      // ──────────────────────────────────────────────────────────────────
+      mmx_image: tool({
+        description:
+          "Generate one or more images from a text prompt using MiniMax's image-01 model via mmx-cli. Use this whenever the user asks for an image, illustration, logo, artwork, photo, or any visual asset. Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Pass seed for reproducible results. Returns the saved file path.",
+        args: {
+          prompt: tool.schema
+            .string()
+            .describe(
+              "Detailed text description of the image. Be specific about subject, style, lighting, composition, mood.",
+            ),
+          aspect_ratio: tool.schema
+            .string()
+            .optional()
+            .describe("Aspect ratio. One of: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. Default 1:1."),
+          n: tool.schema.number().optional().describe("Number of images to generate. Default 1, max 4."),
+          seed: tool.schema.number().optional().describe("Random seed for reproducible generation."),
+          out_dir: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Override save directory. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/ (or $MMX_OUTPUT_DIR if set). Suspicious paths fall back to the default with a warning.",
+            ),
+          optimize_prompt: tool.schema
+            .boolean()
+            .optional()
+            .describe("Auto-optimize the prompt for better quality."),
+          filename_prefix: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Filename prefix. Defaults to a unique per-call value (image-<timestamp>) so back-to-back calls don't overwrite each other. Pass an explicit value for predictable sequential naming.",
+            ),
+        },
+        async execute(args, ctx) {
+          const requestedDir = resolveOutDir(args.out_dir, ctx.worktree)
+          const outDir = isSuspiciousOutDir(requestedDir) ? DEFAULT_OUT_DIR : requestedDir
+          ensureDir(outDir)
+          const filenamePrefix = args.filename_prefix ?? `image-${Date.now()}`
+          const cliArgs = ["image", "generate", "--prompt", args.prompt]
+          if (args.aspect_ratio) cliArgs.push("--aspect-ratio", args.aspect_ratio)
+          if (args.n) cliArgs.push("--n", String(args.n))
+          if (args.seed != null) cliArgs.push("--seed", String(args.seed))
+          if (args.optimize_prompt) cliArgs.push("--prompt-optimizer")
+          cliArgs.push("--out-dir", outDir, "--out-prefix", filenamePrefix, "--non-interactive")
+          const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+          if (exitCode !== 0) {
+            return `mmx image generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          let msg = `Image generation complete.\n\n${stdout.trim()}\n\nSaved to: ${outDir}\nFilename prefix: ${filenamePrefix}`
+          if (outDir !== requestedDir && args.out_dir) {
+            msg += `\n\n${warnSuspiciousOutDir(args.out_dir, outDir)}`
+          }
+          return msg
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // SPEECH SYNTHESIS
+      // ──────────────────────────────────────────────────────────────────
+      mmx_speech: tool({
+        description:
+          "Synthesize speech from text using MiniMax's speech-2.8-hd model. Use when the user wants a voiceover, narration, audio file, TTS, or to read text aloud. Saves an MP3 and returns the path. 40+ languages. Default voice: English_expressive_narrator.",
+        args: {
+          text: tool.schema.string().describe("The text to speak. Up to 10,000 characters."),
+          voice: tool.schema.string().optional().describe("Voice ID. Default English_expressive_narrator."),
+          speed: tool.schema.number().optional().describe("Speech speed multiplier. Default 1.0."),
+          out_path: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Override output .mp3 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/speech-<timestamp>.mp3 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+            ),
+        },
+        async execute(args, ctx) {
+          const {
+            filePath: outPath,
+            wasSuspicious,
+            originalArg,
+          } = resolveFilePath(args.out_path, ctx.worktree, `speech-${Date.now()}.mp3`)
+          ensureDir(dirname(outPath))
+          const cliArgs = ["speech", "synthesize", "--text", args.text]
+          if (args.voice) cliArgs.push("--voice", args.voice)
+          if (args.speed != null) cliArgs.push("--speed", String(args.speed))
+          cliArgs.push("--out", outPath, "--non-interactive")
+          const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+          if (exitCode !== 0) {
+            return `mmx speech synthesize failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          let msg = `Speech synthesized.\n\nSaved to: ${outPath}`
+          if (wasSuspicious && originalArg) {
+            msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+          }
+          return msg
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // VIDEO GENERATION
+      // ──────────────────────────────────────────────────────────────────
+      mmx_video: tool({
+        description:
+          "Generate a short video from a text prompt using MiniMax's Hailuo-2.3 model. Use when the user wants a video clip, animation, or motion graphic. Generation can take 1-3 minutes. Returns the output MP4 file path.",
+        args: {
+          prompt: tool.schema
+            .string()
+            .describe("Detailed description of the video scene, including camera movement and action."),
+          model: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Model ID. Default MiniMax-Hailuo-2.3. Use MiniMax-Hailuo-2.3-Fast for quicker lower-quality results.",
+            ),
+          out_path: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Override output .mp4 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/video-<timestamp>.mp4 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+            ),
+        },
+        async execute(args, ctx) {
+          const {
+            filePath: outPath,
+            wasSuspicious,
+            originalArg,
+          } = resolveFilePath(args.out_path, ctx.worktree, `video-${Date.now()}.mp4`)
+          ensureDir(dirname(outPath))
+          const cliArgs = ["video", "generate", "--prompt", args.prompt]
+          if (args.model) cliArgs.push("--model", args.model)
+          cliArgs.push("--download", outPath, "--non-interactive")
+          const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+          if (exitCode !== 0) {
+            return `mmx video generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          let msg = `Video generation complete.\n\nSaved to: ${outPath}`
+          if (wasSuspicious && originalArg) {
+            msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+          }
+          return msg
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // MUSIC GENERATION
+      // ──────────────────────────────────────────────────────────────────
+      mmx_music: tool({
+        description:
+          "Generate a song or instrumental music from a style prompt using MiniMax's music-2.6 model. Use when the user wants background music, a theme song, a jingle, or instrumental music. Either supply lyrics or set instrumental=true.",
+        args: {
+          prompt: tool.schema
+            .string()
+            .describe(
+              "Style description: genre, mood, instruments, tempo. E.g. 'cinematic orchestral, building tension'.",
+            ),
+          lyrics: tool.schema
+            .string()
+            .optional()
+            .describe("Song lyrics with structure tags like [Verse], [Chorus]. Omit for instrumental."),
+          instrumental: tool.schema
+            .boolean()
+            .optional()
+            .describe("If true, generate instrumental music with no vocals."),
+          vocals: tool.schema.string().optional().describe("Vocal style hint, e.g. 'warm male baritone'."),
+          bpm: tool.schema.number().optional().describe("Exact tempo in BPM."),
+          out_path: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Override output .mp3 path. Leave unset unless the user explicitly asked for a different save location in this conversation. Default: ~/Desktop/mmx-output/music-<timestamp>.mp3 (or $MMX_OUTPUT_DIR if set). Suspicious parent directories fall back to the default with a warning.",
+            ),
+        },
+        async execute(args, ctx) {
+          const {
+            filePath: outPath,
+            wasSuspicious,
+            originalArg,
+          } = resolveFilePath(args.out_path, ctx.worktree, `music-${Date.now()}.mp3`)
+          ensureDir(dirname(outPath))
+          const cliArgs = ["music", "generate", "--prompt", args.prompt]
+          if (args.lyrics) cliArgs.push("--lyrics", args.lyrics)
+          if (args.instrumental) cliArgs.push("--instrumental")
+          if (args.vocals) cliArgs.push("--vocals", args.vocals)
+          if (args.bpm != null) cliArgs.push("--bpm", String(args.bpm))
+          cliArgs.push("--out", outPath, "--non-interactive")
+          const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+          if (exitCode !== 0) {
+            return `mmx music generate failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          let msg = `Music generation complete.\n\nSaved to: ${outPath}`
+          if (wasSuspicious && originalArg) {
+            msg += `\n\n${warnSuspiciousOutDir(originalArg, outPath)}`
+          }
+          return msg
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // WEB SEARCH
+      // ──────────────────────────────────────────────────────────────────
+      mmx_search: tool({
+        description:
+          "Search the web using MiniMax's search API. Use when the user wants current information, news, facts, or anything time-sensitive. Returns a textual summary of search results.",
+        args: {
+          query: tool.schema.string().describe("The search query."),
+        },
+        async execute(args, ctx) {
+          const { stdout, stderr, exitCode } = await runMmx([
+            "search",
+            "query",
+            "--q",
+            args.query,
+            "--output",
+            "json",
+            "--non-interactive",
+          ])
+          if (exitCode !== 0) {
+            return `mmx search failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          return stdout.trim() || "(no results)"
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // VISION (image understanding)
+      // ──────────────────────────────────────────────────────────────────
+      mmx_vision: tool({
+        description:
+          "Describe or analyze an image using MiniMax's vision model. Pass a local file path or URL. Returns a textual description. Useful when the user uploads an image and wants analysis, OCR, or a description.",
+        args: {
+          image: tool.schema.string().describe("Local file path or URL of the image."),
+          prompt: tool.schema
+            .string()
+            .optional()
+            .describe("Custom question about the image. Default 'Describe the image.'"),
+        },
+        async execute(args, ctx) {
+          const cliArgs = ["vision", "describe", "--image", args.image]
+          if (args.prompt) cliArgs.push("--prompt", args.prompt)
+          cliArgs.push("--non-interactive")
+          const { stdout, stderr, exitCode } = await runMmx(cliArgs)
+          if (exitCode !== 0) {
+            return `mmx vision describe failed (exit ${exitCode}):\n${stderr || stdout || "(no output)"}`
+          }
+          return stdout.trim() || "(no description)"
+        },
+      }),
+
+      // ──────────────────────────────────────────────────────────────────
+      // QUOTA CHECK
+      // ──────────────────────────────────────────────────────────────────
+      mmx_quota: tool({
+        description:
+          "Show current Token Plan usage and remaining quota (5-hour rolling and weekly windows). Use when the user asks about quota, usage, limits, or how many calls they have left.",
+        args: {},
+        async execute(_args, ctx) {
+          let { stdout, stderr, exitCode } = await runMmx(["quota"])
+          if (exitCode !== 0) {
+            const fallback = await runMmx(["quota", "show", "--non-interactive"])
+            if (fallback.exitCode === 0) {
+              stdout = fallback.stdout
+              stderr = fallback.stderr
+              exitCode = fallback.exitCode
+            } else {
+              return `mmx quota failed (exit ${exitCode}):\n${stderr || "(no stderr)"}`
+            }
+          }
+          const raw = stdout.trim()
+          let data: any
+          try {
+            data = JSON.parse(raw)
+          } catch {
+            return raw || "(no quota info)"
+          }
+          const rows = (data.model_remains ?? []).map((m: any) => {
+            const reset = new Date(m.end_time).toUTCString().replace(/^[^,]+,\s*/, "")
+            return `| ${m.model_name} | ${m.current_interval_remaining_percent}% left | ${m.current_weekly_remaining_percent}% left | resets ${reset} |`
+          })
+          const header = "| Model | 5h window | Weekly | Next reset |\n|---|---|---|---|"
+          return `Quota — Token Plan\n\n${header}\n${rows.join("\n")}\n`
+        },
+      }),
+    },
+  }
+}

package/opencode/skill/mmx/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mmx
+description: Use when the user wants to generate images, video, music, speech, run web search, analyze images, or check Token Plan quota. Wraps the official mmx-cli so multimodal MiniMax capabilities can be invoked directly from inside an OpenCode session without leaving the chat. Front-load keywords: image, picture, illustration, logo, artwork, generate, mmx, MiniMax, video, music, song, voiceover, TTS, speech, search, vision, quota, usage.
+---
+
+# mmx — MiniMax multimodal tools
+
+The `mmx-tools` plugin exposes seven tools that wrap the official MiniMax CLI:
+
+| Tool              | What it does                                         |
+| ----------------- | ---------------------------------------------------- |
+| `mmx_image`       | Text → image (image-01 model)                        |
+| `mmx_speech`      | Text → MP3 voiceover (speech-2.8-hd)                 |
+| `mmx_video`       | Text → MP4 short video (Hailuo-2.3)                  |
+| `mmx_music`       | Text → song / instrumental (music-2.6)               |
+| `mmx_search`      | Web search via MiniMax search API                    |
+| `mmx_vision`      | Image → text description / OCR / Q&A                |
+| `mmx_quota`       | Show Token Plan usage and remaining quota            |
+
+## Setup (one-time, on the machine)
+
+1. Install the CLI: `npm install -g mmx-cli`
+2. Authenticate with the user's API key: `mmx auth login --api-key sk-xxxxx`
+   The key is stored locally — never paste it into chat.
+3. If calls return 401, the region auto-detect failed. Set it manually:
+   - Overseas: `mmx config set --key region --value global`
+   - Mainland China: `mmx config set --key region --value cn`
+4. Confirm with: `mmx quota` and `mmx auth status`
+
+## Output location
+
+All generated files save to `~/Desktop/mmx-output/` by default — regardless of which repo or directory OpenCode was launched from. This is intentional; do not override it on your own.
+
+**Never pass `out_dir` / `out_path` unless the user explicitly asked for a different save location in this conversation.** Passing these args based on your own inference (e.g. "save to the current repo") is wrong and will be silently corrected to the default with a warning in the tool output.
+
+Two ways the user can legitimately override:
+
+1. **Per-call:** tell the agent explicitly in chat ("save this to my Pictures folder"), and the agent will pass the right `out_dir` / `out_path`.
+2. **Permanent:** set `MMX_OUTPUT_DIR=/some/path` in the user's shell rc (`~/.zshrc`, `~/.bashrc`) before launching OpenCode. This changes the default for all mmx tools.
+
+Suspicious paths (`$HOME`, `~/Desktop`, `/tmp`, `.`) passed via `out_dir` / `out_path` are always rejected and fall back to `~/Desktop/mmx-output/` — even when the user explicitly asks for them. (Users wanting those locations should use `MMX_OUTPUT_DIR` for the legitimate case.)
+
+`mmx_image` defaults to a unique filename prefix per call (`image-<timestamp>`) so back-to-back calls don't overwrite each other. Pass an explicit `filename_prefix` when you want predictable sequential naming (e.g. `logo_001.jpg`, `logo_002.jpg`).
+
+## Common patterns
+
+- **Cover image for a slide / social post** — call `mmx_image` with a detailed style prompt and `aspect_ratio: "16:9"` or `"1:1"`.
+- **Voiceover for a video** — `mmx_speech` with the script as `text`. Override voice ID if the default English narrator doesn't fit.
+- **Background music** — `mmx_music` with `instrumental: true` and a style prompt like "calm ambient pad, lo-fi beat, 70 bpm".
+- **Verify what's left in the quota** — `mmx_quota` before starting a long batch.
+- **Describe a screenshot the user dropped in** — `mmx_vision` with the local path.
+
+## Tips
+
+- Image prompts should be **specific and detailed**: subject, style, lighting, composition, mood. Vague prompts produce vague results.
+- For reproducible images, pass `seed`. Same prompt + same seed = same image.
+- Video and music calls block for 1–3 minutes — call them only when the user actually wants the output.
+- If `mmx_image` returns a failed exit code, surface the stderr verbatim — that's where mmx-cli writes quota errors, region errors, and validation issues.
+
+## When NOT to use these tools
+
+- For diagrams, charts, tables, or anything textual — render with HTML/JSX instead.
+- For tiny UI icons — too heavy; use SVG.
+- If the user is on the free tier or hasn't authenticated, point them at the setup section above before retrying.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hmanlab/mmx",
+  "version": "0.4.3",
+  "description": "Multimodal generation via MiniMax (image, video, music, speech, search, vision, quota).",
+  "type": "module",
+  "files": [
+    "opencode"
+  ],
+  "hl-plugins": {
+    "opencodePlugin": "./opencode/plugin/mmx-tools.ts",
+    "opencodeSkill": "./opencode/skill/mmx/SKILL.md",
+    "defaultInstall": true,
+    "permission": "mmx *",
+    "requires": [
+      {
+        "name": "mmx-cli",
+        "type": "binary",
+        "check": "mmx --version",
+        "install": "npm install -g mmx-cli",
+        "update": "npm update -g mmx-cli"
+      }
+    ],
+    "auth": {
+      "check": "mmx auth status",
+      "login": {
+        "cmd": "mmx auth login",
+        "args": [
+          "--api-key",
+          {
+            "var": "key"
+          }
+        ]
+      },
+      "verify": "mmx quota",
+      "keyLabel": "MiniMax API key",
+      "envVar": "MMX_API_KEY"
+    },
+    "postInstall": [
+      "mmx quota"
+    ]
+  }
+}