feat(text chat): expose image input via repeatable --image (multimodal M3, multi-image)

[shoemoney]

Closes #224.

What

mmx text chat now takes a repeatable --image <path-or-url>:

# single image
mmx text chat --image ./photo.jpg --message "What breed is this dog?"

# multiple images in one call
mmx text chat --image ./before.png --image ./after.png \
  --message "List every visual difference between these two."

Why

M3 is multimodal and already accepts multiple images through --messages-file, but there was no CLI path to it, you had to hand-write a base64 messages JSON. Worse, the documented OpenAI shape ({"type":"image_url", ...}) is rejected, because text chat posts to the Anthropic-compatible /anthropic/v1/messages endpoint and needs {"type":"image","source":{"type":"base64",...}}. --image emits the right shape for you.

How

• toImageBlock() in src/utils/image.ts wraps toDataUri() and enforces the M3 image contract: each image is capped at 10 MB, formats are restricted to JPEG/PNG/GIF/WEBP, and oversized files are rejected before encoding (via statSync for local paths, content-length checks for remote URLs, and size computation for data URIs).
• src/commands/text/chat.ts appends image blocks to the last user message, promoting content from a string to a block array. Text goes first so the model reads the instruction before the pixels. With no --message, images become the user message.
• The aggregate request body is tracked and capped at 64 MB, so runs bail as soon as an image would exceed the limit rather than after fetching and encoding everything.
• When --image is present and --model is not, the model resolves to MiniMax-M3, otherwise a text-only defaultTextModel in config would silently break every image request. An explicit --model still wins.
• Docs updated: README.md, README_CN.md, and skill/SKILL.md (which also now calls out the OpenAI-vs-Anthropic block-shape gotcha).
• ContentBlock type gains the image variant.

Verification

Dry run of the built binary:

$ mmx text chat --image a.png --image b.png --message "diff these" --dry-run --output json
{
  "request": {
    "model": "MiniMax-M3",
    "messages": [ { "role": "user", "content": [
      { "type": "text",  "text": "diff these" },
      { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "..." } },
      { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "..." } }
    ] } ],
    "max_tokens": 4096,
    "stream": false
  }
}

That is byte-for-byte the payload shape confirmed working against M3 in #224.

Six focused test categories in test/commands/text/chat.test.ts cover block shape, multi-image, image-without-message, model override, explicit --model winning, missing file, oversized local file, unsupported format (HEIC), supported format (GIF), remote image over the per-image cap, data URI over cap, and seven small images that cumulatively exceed the 64 MB cap. bun test 461 pass / 0 fail; bun run typecheck and bun run lint clean.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[NianJiuZst]

I reviewed the current head and the feature direction is useful, but I do not recommend merging this revision yet.

[P2] Enforce the M3 image contract before encoding. The current MiniMax Anthropic API docs cap each image at 10 MB and the whole request body at 64 MB, and support JPEG/PNG/GIF/WEBP. The new path delegates to toDataUri(), which leaves local/data-URI inputs unbounded, permits remote images up to 50 MB, rejects local GIF, and accepts HEIC/HEIF. A local 11 MiB .png was encoded to 15,379,116 base64 characters without error; repeated --image inputs can therefore exceed the request cap and fail only after substantial memory/network work. Please add chat-specific per-image/format validation and an aggregate request-size check.

Official contract: https://platform.minimax.io/docs/api-reference/text-anthropic-api

Local verification: typecheck, lint (one pre-existing warning), build, 17 focused tests, and the full suite (455/455) passed. Those mocks do not exercise the oversized/unsupported real-provider cases.

[shoemoney]

Thanks — the 11 MiB repro was the useful part, that path was genuinely unbounded. Pushed a fix in 91889a1.

toDataUri/toImageBlock now take optional per-caller constraints. Omitted, every existing caller (vision/describe, video/generate, image/generate, the SDK) runs byte-identically to before — same 50 MB remote cap, same HEIC/HEIF allowlist. IMAGE_MIME_TYPES is untouched. Chat passes the M3 limits explicitly:

• Local files are statSync'd before readFileSync, so an 11 MiB PNG is rejected without ever being read, let alone base64-encoded.
• Remote URLs have their content-type checked against the allowlist and their content-length checked before res.arrayBuffer(), then the real byteLength re-checked after — content-length can be absent or lie.
• data: URIs have their declared media type validated and their decoded size computed arithmetically from the base64 length, without decoding.
• Formats for chat are exactly image/jpeg, image/png, image/gif, image/webp. GIF is now accepted; HEIC/HEIF are now rejected.
• The 64 MB aggregate is accumulated as each --image is processed, starting from the serialized message and system text, so a run bails as soon as the cap is unreachable rather than after fetching and encoding everything. The running total counts base64 length, since that is what actually goes on the wire.

Six focused tests cover each of those: oversized local, HEIC rejected, GIF accepted and labeled image/gif, remote over-cap, data: URI over-cap, and seven images each under 10 MB that trip the 64 MB aggregate. Full suite is 461/461, typecheck clean, lint unchanged at the one pre-existing warning.

One thing I could not black-box in a test: that the content-length check strictly fires before buffering. Bun's Response recomputes Content-Length to match the real body, so a spoofed header collapses to the true size and both checks agree. The code does the header check first as you asked; the test only asserts the rejection.

[SaladDay]

Thanks for putting this together — the direction is great, and the normal single-/multi-image paths look good. I found three issues that should be addressed before merging:

1. The 64 MB check does not measure the final serialized request body. It runs before the image wrapper, model fields, and tools are added, and it counts raw system text instead of JSON-escaped bytes. I reproduced a request that was accepted by the CLI but exceeded 64 MiB on the wire. Please validate Buffer.byteLength(JSON.stringify(body)) after the complete body is built.
2. attachImages() walks backward to any previous user message. If the history ends with an assistant message, a new --image is silently attached to an old user turn while the assistant remains last. Please append a new user turn unless the final message is already a user message.
3. Remote images without a trustworthy Content-Length are fully buffered by res.arrayBuffer() before the 10 MB check, so a large/chunked response can cause unbounded memory use. Please enforce the limit while streaming and cancel once it is exceeded.

Two smaller consistency issues: image-only input works at runtime, but the exported schema still requires message; and the docs/types only describe base64 image sources even though the MiniMax Anthropic API also supports source.type: "url".

I reproduced the three main cases locally. Once these are covered, this should be in good shape. Thanks!

[shoemoney]

Thanks for reproducing all three — each one was real. Pushed 13a538e (rebased onto main):

1. The 64 MB check now runs on Buffer.byteLength(JSON.stringify(body)) after the full body is built, so escaping, the image wrapper, model fields and tools are all counted. The per-image accumulation stays as an early fail on a lower bound.
2. attachImages now only merges into the final message if it is a user turn; if the assistant spoke last (or the history is empty) the images become a new user turn instead of being spliced into an earlier one.
3. Remote images are read from res.body chunk by chunk and the download is cancelled the moment the received bytes exceed 10 MB, so an untrustworthy or missing Content-Length can't force a full buffer.

On the two smaller points: --message is no longer schema-required (the existing prompt/failIfMissing path still covers the no-input case), and ImageSource in the types now includes { type: 'url', url } with a note in the skill doc; --image still emits base64.

Added a regression for each of the three, verified red first (the chunked test asserts the server never got to serve the whole body, since the old code rejected only after buffering it). Full suite 518/518, lint and typecheck clean.