ima2-gen 3.8.1 → 3.8.2

package/config.js

@@ -15,11 +15,13 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync } from "node:fs";
 import { deriveSupportedImageModels, deriveUnsupportedImageModels } from "./lib/providers/derive.js";
-export const DEFAULT_GROK_PLANNER_MODEL = "grok-4.6";
+// 4.6 rewrites prompts in ways that read worse than 4.3 for this planner's job, which
+// is judged by the result rather than a benchmark. 4.6 stays selectable below.
+export const DEFAULT_GROK_PLANNER_MODEL = "grok-4.3";
 export const GROK_PLANNER_MODELS = [
     DEFAULT_GROK_PLANNER_MODEL,
+    "grok-4.6",
     "grok-4.5",
-    "grok-4.3",
     "gpt-5.6-luna",
     "gpt-5.6-terra",
     "gpt-5.6-sol",

package/docs/API.md

@@ -14,7 +14,7 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
-- `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.5` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. `grok-4.3` remains available as an explicit compatibility override. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
+- `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.3` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. `grok-4.6` and `grok-4.5` remain selectable overrides. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool. Model is `nano-banana-2`. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (`AGY_VIDEO_UNSUPPORTED`).
 - `provider: "grok-api"` uses a direct xAI API key instead of the bundled progrok OAuth proxy. Same pipeline as `grok` (Web Search → planner → `/v1/images/generations`), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or `XAI_API_KEY` env var. Also supports video generation.
 - `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K) on both auth paths — the direct API path sends `generation_config.response_format.image` (snake_case) while the Vertex AI endpoint (`aiplatform.googleapis.com`) sends `generationConfig.imageConfig` (camelCase). With `size: "auto"` the image config is omitted entirely and the model decides ratio/size. Auth: `GEMINI_API_KEY` env var, web UI key management (`/api/keys/gemini`), or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON` or `/api/keys/vertex`). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (`apikey` or `vertex`) persists to `~/.ima2/config.json` as `geminiAuthMode` and is restored on server startup. Per-model cost: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
@@ -406,7 +406,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events on the
 | `referenceFilenames` | string[] | — | Existing generated files for reference-to-video |
 | `continueFromVideo` | string | — | Generated `.mp4` parent; server extracts its last frame and rebuilds lineage from sidecar |
 | `continuityLineage` | object | — | Optional client hint; used only when `continueFromVideo` is absent |
-| `plannerModel` | string | `grok-4.5` | Grok video planner model override; `grok-4.3` remains compatible (also via settings UI or `IMA2_GROK_PLANNER_MODEL`) |
+| `plannerModel` | string | `grok-4.3` | Grok video planner model override; `grok-4.6` and `grok-4.5` are selectable (also via settings UI or `IMA2_GROK_PLANNER_MODEL`) |
 | `storyboard` | boolean | `false` | Enable storyboard mode — maintains character/scene continuity across sequential clips |
 
 Blank prompts return `PROMPT_REQUIRED` with a `guidance` string. The active

package/docs/PROMPT_STUDIO.md

@@ -17,7 +17,7 @@ you want a reproducible way to report a workspace issue.
 | 1:1 Direct | Sends the prompt through with less rewriting by the app. | Use it for exact wording, strict prompt experiments, or provider-side prompt syntax. |
 | Model quick menu | Changes the image model and reasoning effort from the sidebar header. | The full Settings workspace remains the detailed configuration page. |
 | Recent generations | Shows the visible Prompt Studio history domain. | Arrow keys move inside the same visible recent domain instead of hidden older rows. Video items render as video thumbnails. Drag any thumbnail to the composer to add it as a reference image. Video results expose First, Mid, and Last frame buttons to copy keyframes. |
-| Video settings | Controls Grok video duration, resolution, aspect ratio, and planner model. | Default planner model is `grok-4.5`; `grok-4.3` remains a compatibility override. |
+| Video settings | Controls Grok video duration, resolution, aspect ratio, and planner model. | Default planner model is `grok-4.3`; `grok-4.6` and `grok-4.5` are selectable. |
 | Gallery | Browses saved local images, All/Favorites tabs, and folders. | Favorite toggles should preserve the gallery viewport you were browsing. |
 | Prompt library | Imports saved prompt text into the composer intentionally. | Library insert/continue actions are explicit prompt imports; passive image selection is not. |
 

package/docs/PROMPT_STUDIO.zh-CN.md

@@ -17,7 +17,7 @@ Prompt Studio 是用于重复图像迭代的经典工作区配置文件。它
 |1:1直接|通过应用程序更少的重写来发送提示。|将其用于精确的措辞、严格的提示实验或提供者端提示语法。|
 |模型快捷菜单|从侧边栏标题更改图像模型和推理工作。|完整的设置工作区仍然是详细的配置页面。|
 |最近几代|显示可见的 Prompt Studio 历史域。|箭头键在同一可见的最近域内移动，而不是隐藏的旧行。视频项目呈现为视频缩略图。将任何缩略图拖到编辑器中以将其添加为参考图像。视频结果显示“第一帧”、“中间帧”和“最后一帧”按钮以复制关键帧。|
-|视频设置|控制Grok视频时长、分辨率、宽高比和规划器模型。|默认规划器模型是`grok-4.5`; `grok-4.3`仍然是兼容性覆盖。|
+|视频设置|控制Grok视频时长、分辨率、宽高比和规划器模型。|默认规划器模型是`grok-4.3`；`grok-4.6`和`grok-4.5`可选。|
 |画廊|浏览保存的本地图像、所有/收藏夹选项卡和文件夹。|最喜欢的切换应保留您正在浏览的图库视口。|
 |提示库|有意将保存的提示文本导入到编辑器中。|库插入/继续操作是显式提示导入；被动图像选择则不然。|
 

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 371 (runtime: 168, contract: 203)
+Total: 372 (runtime: 169, contract: 203)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -146,6 +146,7 @@ Total: 371 (runtime: 168, contract: 203)
 - `tests/serve-singleton-contract.test.ts`
 - `tests/serve-ui-build-contract.test.ts`
 - `tests/server-code-preservation.test.ts`
+- `tests/skill-video-claims-contract.test.ts`
 - `tests/sprite-anchor-policy.test.ts`
 - `tests/sprite-atlas-compose.test.ts`
 - `tests/sprite-atlas-import.test.ts`

package/lib/agentImageVideoGen.js

@@ -22,7 +22,9 @@ import { isVideoGenerationError, normalizeVideoGenerationRequest, } from "./vide
 import { appendAgentTurn, getAgentImages, getAgentSession, importAgentImage, } from "./agentStore.js";
 import { errInfo } from "./errInfo.js";
 import { forceImagePrompt, isTextOnlyResult, textOnlyError, notFound } from "./agentRuntime.js";
-const AGENT_GROK_PLANNER_MODELS = new Set([DEFAULT_GROK_PLANNER_MODEL, "grok-4.5", "grok-4.3"]);
+// Spelled out rather than derived from the default, so moving the default does not
+// silently drop a model agents are allowed to ask for.
+const AGENT_GROK_PLANNER_MODELS = new Set([DEFAULT_GROK_PLANNER_MODEL, "grok-4.6", "grok-4.5", "grok-4.3"]);
 export async function generateAgentImageWithRetry(ctx, sessionId, prompt, manifest, webSearchEnabled, options) {
     options.onProgressStage?.("requesting");
     let lastError = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.8.1",
+  "version": "3.8.2",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -119,5 +119,5 @@
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   },
-  "gitHead": "04154ba017a080045bc12fdc37b8945dbcfd75b6"
+  "gitHead": "19b682ffdeaedb38fda2ee4be45726abb5f47390"
 }

package/skills/ima2/SKILL.md

@@ -575,8 +575,8 @@ Persist the server-side model defaults shared by GPT OAuth and API provider path
 
 The built-in OAuth image default is `gpt-5.6-luna`; Grok image and video code
 defaults are `grok-imagine-image-quality` and `grok-imagine-video` respectively.
-Use `grok-imagine-video-1.5` explicitly when its quality or 1080p capabilities
-are needed.
+For video, set `grok-imagine-video-1.5` as your default and leave the base model
+for edit and extension, which are the only things 1.5 cannot do.
 
 ```bash
 ima2 defaults set model gpt-5.5
@@ -659,10 +659,11 @@ a SuperGrok subscription; MCP lanes require their own connected subscription.
 
 ```bash
 ima2 models --kind video
-ima2 defaults set video grok/grok-imagine-video
+ima2 defaults set video grok/grok-imagine-video-1.5
 ima2 video "a cat playing piano"                    # text-to-video, uses saved default
-ima2 video "animate this" --model grok/grok-imagine-video --ref photo.png
-ima2 video "cinematic" --model grok/grok-imagine-video --ref a.png --ref b.png
+ima2 video "animate this" --ref photo.png           # image-to-video: photo is frame 1
+ima2 video "same cat, on a beach" --ref cat.png --as-reference   # new scene, same subject
+ima2 video "cinematic" --ref a.png --ref b.png      # 2+ refs are always references
 ```
 
 Targets use `--model <lane>/<model>`; a bare ID is accepted only when it is
@@ -691,24 +692,62 @@ parameters. Multishot generation is `POST /api/mcp/multishot` (CLI surface
 planned). Video edit is the 2-step `edit-video-preview` → `edit-video-submit`
 media action; stage-1 returns a synchronous keyframe preview.
 
-### Modes (auto-detected from --ref count)
+### Model choice: reach for 1.5 first
+
+`grok-imagine-video-1.5` is the model to use unless you are editing or extending an
+existing video. It owns everything that makes a clip better; the base model owns two
+operations 1.5 refuses.
+
+| Capability | `grok-imagine-video-1.5` | `grok-imagine-video` (base) |
+|---|---|---|
+| Reference images (1-7) | yes | yes |
+| 1080p | yes (not in reference-to-video) | no |
+| Duration 1-15s | yes | yes |
+| Preset voices (`--voice`) | yes, up to 3 | **no** — returns 400 |
+| Video edit (V2V) | **no** — returns 400 | yes |
+| Video extension | **no** — returns 400 | yes |
+
+So: **1.5 for generating, base for editing and extending.** Nothing needs both at once.
+
+`grok-imagine-video-1.5-preview` is still accepted as a compatibility alias, but write
+`grok-imagine-video-1.5` in anything new.
+
+Prompt-only text-to-video on 1.5 is implemented as an internal white-canvas image-to-video anchor,
+because upstream 1.5 rejects raw T2V. That is an implementation detail — ask for
+text-to-video normally.
+
+When a request does fall back to another model, the result carries `requestedModel`,
+`effectiveModel`, and `modelFallback`. Read `effectiveModel` before naming or reporting
+which model produced a clip. A request carrying `--voice` never falls back, because the
+base model cannot honor the voice and silently dropping it would return a clip missing
+what was asked for.
+
+### Modes (from --ref count, plus your choice at one reference)
 
 | Refs | Mode | Max Duration |
 |------|------|-------------|
 | 0 | text-to-video | 15s |
-| 1 | image-to-video | 15s |
-| 2-7 | reference-to-video | 10s |
+| 1 | image-to-video (default) | 15s |
+| 1 + `--as-reference` | reference-to-video | 15s |
+| 2-7 | reference-to-video | 15s |
+
+One image is ambiguous and only the caller knows the intent, so it is a choice rather
+than a deduction. **image-to-video** locks that image as the opening frame and animates
+it. **reference-to-video** carries its subject, outfit, or location into a new scene
+without reproducing the shot. Two or more images can only be references.
 
-`grok-imagine-video-1.5` supports image-to-video and supports 1080p for prompt-only text-to-video and single image/frame image-to-video. Prompt-only 1.5 text-to-video is implemented as an internal white-canvas image-to-video anchor because upstream 1.5 rejects raw T2V. The old `grok-imagine-video-1.5-preview` string is accepted as a compatibility alias. 1.5 does not support `reference_images` Ref2V, V2V edit, or extension. For 2+ references, use `grok-imagine-video` and keep duration at 10s or less. ima2 may auto-retry a rejected 1.5 Ref2V request with the base model; read `effectiveModel` and `modelFallback` from the final result before naming or reporting the output.
+Reference-to-video tops out at 720p; ask for 1080p there and the request is refused.
 
 ### Parameters
 
 | Flag | Values | Default |
 |------|--------|---------|
 | `--duration` | 1–15 (seconds) | 5 |
-| `--resolution` | 480p, 720p, 1080p (1.5 T2V canvas shim or I2V) | 480p |
+| `--resolution` | 480p, 720p, 1080p (1.5 only; not in reference-to-video) | 480p |
 | `--aspect-ratio` | auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | auto |
-| `--model` | `<lane>/<model>`; Grok base or 1.5 (preview alias accepted) | `grok-imagine-video` after selecting the Grok lane |
+| `--model` | `<lane>/<model>`; prefer `grok-imagine-video-1.5` (preview alias accepted) | `grok-imagine-video` after selecting the Grok lane |
+| `--as-reference` | (flag) with exactly one `--ref`: guide a new scene instead of animating that image | off |
+| `--voice` | preset voice id, repeatable, max 3 (1.5 only) | (none) |
 | `--topic` | any string | (none) |
 | `--session` | session ID | (none) |
 | `-o, --out` | output file path | saved under configured generated dir |
@@ -804,7 +843,7 @@ ima2 serve          # server must be running
 ### Output
 
 SSE streaming events: `planning` → `submitted` → `progress` (0-100%) → `done`.
-The `submitted` and `done` payloads include `requestedModel`, `effectiveModel`, and `modelFallback` so agents can report when a requested 1.5-preview Ref2V job actually ran on `grok-imagine-video`. CLI `--json` prints `video.requestedModel`, `video.effectiveModel`, and `video.modelFallback`; use `path`/`filename` for local chaining.
+The `submitted` and `done` payloads include `requestedModel`, `effectiveModel`, and `modelFallback` so agents can report which model actually produced a clip when a request falls back. A request carrying `--voice` never falls back. CLI `--json` prints `video.requestedModel`, `video.effectiveModel`, and `video.modelFallback`; use `path`/`filename` for local chaining.
 
 ### Discover Valid Parameters
 
@@ -830,8 +869,9 @@ Generate a high-quality still image first, then animate it. This produces better
 
 | Scenario | Use | Why |
 |----------|-----|-----|
-| Need 2+ character identity lock from separate refs | ref2v (`grok-imagine-video`, max 7 refs, max 10s) | Refs lock character appearance |
-| Single composed scene with all elements | i2v (`1.5-preview` or base, 1 ref) | Better motion quality from composed start |
+| Need 2+ character identity lock from separate refs | ref2v (`grok-imagine-video-1.5`, max 7 refs, up to 15s, 720p) | Refs lock character appearance |
+| Single composed scene with all elements | i2v (`grok-imagine-video-1.5`, 1 ref) | Better motion quality from composed start |
+| One subject, but a brand new setting | ref2v with one ref (`--as-reference`) | Keeps the subject without reproducing the source shot |
 | Continue from previous video | `video continue` (last frame as i2v ref) | Lineage metadata preserved |
 
 ```bash
@@ -1021,12 +1061,43 @@ done
 ### Limitations
 
 - Max 15 seconds per clip (extend adds 2-10s more)
-- Reference-to-video (2+ refs): max 10 seconds, max 7 refs, `grok-imagine-video` effective model
+- Reference-to-video: 1-7 refs, up to 15 seconds, 720p ceiling. The 10-second clamp this
+  section used to describe was ours, not xAI's, and was removed in v3.8.0 (issue #155)
 - 1080p resolution is available for `grok-imagine-video-1.5` prompt-only text-to-video via the white-canvas I2V shim, and for image-to-video with a single image/frame source
 - Video edit/extend: grok-imagine-video only (1.5 is not supported)
 - Video edit input: max 8.7 seconds
 - Video extend input: 2-15 seconds; extension duration: 2-10 seconds
 
+#### Provenance of the limits above
+
+Do not re-litigate these from doc snippets alone. Two different kinds of fact are
+mixed in this section, and they age differently.
+
+**Owner-measured, not in any public doc — trust it, do not "correct" it away:**
+
+| Limit | Source |
+|---|---|
+| Video edit input max **8.7 seconds** | Owner's own empirical measurement, recorded in `docs/grok-video-i2v-research.md` (2026-05-30). No xAI doc states this number. It is not a hallucination and it is not stale-by-default — leave it in place unless a fresh measurement contradicts it. |
+
+**Live-probed against `api.x.ai` on 2026-08-20 (real requests, real responses):**
+
+| Behavior | Observed |
+|---|---|
+| `grok-imagine-video-1.5` + `/v1/videos/edits` | `400 "Video editing is not supported for this model."` |
+| `grok-imagine-video-1.5` + `/v1/videos/extensions` | `400 "Video extension is not supported for this model."` |
+| `grok-imagine-video` (base) + edit / extend | `200` → `done` (both work) |
+| Edit `duration` / `resolution` overrides | Accepted with `200` but **silently ignored** — output inherits the source video's properties, capped at 720p |
+| Extension `duration` outside 2-10 | Returns `200` with a `request_id`, then **fails asynchronously** on poll: `"Duration must be between 2 and 10 seconds"`. Validate before sending; a 200 here does not mean accepted. |
+| R2V reference count | 7 max; 8 → `400 "Too many reference images: 8. Maximum allowed is 7."` |
+| R2V + 1080p | `400 "1080p video resolution is not supported for reference-to-video requests."` |
+| R2V duration 15 | `200` → `done`, `video.duration=15` (this is why the old 10s clamp was removed) |
+| R2V with a single reference image | Accepted (`200`) — 2+ is an ima2 convention, not an API requirement |
+| `reference_audios: [{"voice_id": "eve"}]` on 1.5 | `200` → `done` (preset voices work; up to 3) |
+| Rate limit | 2 requests/second per team; exceeding it returns `429` |
+
+The 1.5-vs-base split is not symmetric: **1.5** owns reference images, 1080p, and 15s;
+**base** owns video editing and extension. Neither model does both.
+
 ### Video Editing (V2V)
 
 Edit an existing video with a text prompt. This uses xAI's real video edit endpoint and saves the result as a generated video artifact.
@@ -1045,13 +1116,22 @@ ima2 video edit "Add a sailboat in the distance" --video "$VIDEO_FILE"
 ima2 video edit "Make it stormy with dark clouds" --video "$VIDEO_FILE"
 ```
 
-Constraints: grok-imagine-video only, input mp4 <=8.7s. Use `-o/--out` if you also need a local copy outside the generated directory.
+Constraints: grok-imagine-video only, input mp4 <=8.7s (owner-measured 2026-05-30; not
+in any xAI doc — see Provenance above). `grok-imagine-video-1.5` returns
+`400 "Video editing is not supported for this model."` (verified 2026-08-20).
+`duration` and `resolution` are accepted but ignored: the output inherits the source
+video's properties, capped at 720p. Use `-o/--out` if you also need a local copy
+outside the generated directory.
 
 ### Video Extension (Continue from Last Frame)
 
 Extend a video from its last frame using xAI's video extension endpoint. The output combines the source video and extension, but continuity quality is provider-dependent.
 
-Constraints: grok-imagine-video only, extension duration 2-10s. 1.5-preview is not supported for extension.
+Constraints: grok-imagine-video only, extension duration 2-10s. `grok-imagine-video-1.5`
+returns `400 "Video extension is not supported for this model."` (verified 2026-08-20).
+`duration` is the length of the **appended segment**, not the total: a 10s source with
+`duration: 5` returns a 15s video. Out-of-range durations return `200` and then fail
+asynchronously on poll, so validate before sending.
 
 ```bash
 # Generate initial clip
@@ -1335,3 +1415,23 @@ Agents: run `ima2 tools list --json` for the live view; this section is the bund
 | `mcp.runway.whoami` | — | Returns the authenticated Runway user profile, the workspace this MCP connection is pinned to (chosen at sign-in), and the list of image/vid |
 
 <!-- mcp-tools:generated:end -->
+### Preset Voices (1.5 only)
+
+`grok-imagine-video-1.5` can give the subject a speaking voice. Pass up to three preset
+voices; the base model rejects the field outright.
+
+```bash
+ima2 video "the person from <IMAGE_1> greets the camera with <AUDIO_0>" \
+  --ref portrait.png --as-reference --voice eve --duration 6 --resolution 720p
+```
+
+Address voices in the prompt as `<AUDIO_0>`, `<AUDIO_1>`, `<AUDIO_2>`, the same way
+reference images are `<IMAGE_1>`..`<IMAGE_N>`. A voice nobody is assigned to in the
+prompt does not get used.
+
+Known presets include `ara`, `eve`, `leo`, `rex`, `sal`, `carina`, `luna`, `orion`,
+`iris`, `atlas`. **This list is a hint, not an allowlist.** xAI owns the roster and also
+accepts custom voice ids, so an unknown id comes back as a 400 that names every voice it
+will take — read that error rather than guessing from this page.
+
+### Video Editing (V2V)