ima2-gen 2.0.2 → 2.0.4-preview-260626

package/CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Node route validation order — `startJob`/202 response moved after request validation.
 - CI typecheck — unused imports in card-news tests and store split type mismatches.
 - Thumbnail backfill failure reporting (#94).
+- AGY provider detection now finds user-local `agy` installs such as `~/.local/bin/agy` and supports `IMA2_AGY_BIN` for explicit binary paths.
 - AGY Windows pipe handling, Gemini API aspect ratio string values, multimode same-prompt batching.
 - Moderation over-filtering — removed safety tags and added error enrichment.
 

package/bin/commands/gen.js

@@ -9,6 +9,8 @@ const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
 const VALID_PROVIDERS = new Set(["auto", "oauth", "api", "grok", "grok-api", "agy", "gemini-api"]);
 const KNOWN_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex-spark", "grok-imagine-image", "grok-imagine-image-quality", "nano-banana-2", "nano-banana-pro"]);
+const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
+const MAX_REFERENCE_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxRefCount) || 5));
 const SPEC = {
     flags: {
         quality: { short: "q", type: "string", default: "low" },
@@ -47,8 +49,8 @@ const HELP = `
   Options:
     -q, --quality <low|medium|high>         Default: low
     -s, --size <WxH | auto>                 Default: 1024x1024
-    -n, --count <1..8>                      Default: 1
-        --ref <file>                        Attach reference image (repeatable, max 5)
+    -n, --count <1..${MAX_GENERATION_COUNT}>                     Default: 1
+        --ref <file>                        Attach reference image (repeatable, max ${MAX_REFERENCE_COUNT})
     -o, --out <file>                        Single-image output path (implies -n 1)
     -d, --out-dir <dir>                     Output dir for multiple images
         --json                              Print JSON result to stdout
@@ -88,8 +90,8 @@ export default async function genCmd(argv) {
     if (!prompt)
         die(2, "prompt is required (positional or via --stdin)");
     const refs = (Array.isArray(args.ref) ? args.ref : []);
-    if (refs.length > 5)
-        die(2, "max 5 --ref attachments");
+    if (refs.length > MAX_REFERENCE_COUNT)
+        die(2, `max ${MAX_REFERENCE_COUNT} --ref attachments`);
     if (!VALID_MODES.has(String(args.mode)))
         die(2, "--mode must be one of: auto, direct");
     if (!VALID_MODERATION.has(String(args.moderation)))
@@ -107,7 +109,7 @@ export default async function genCmd(argv) {
     if (args["web-search"] && args["no-web-search"]) {
         die(2, "--web-search and --no-web-search are mutually exclusive");
     }
-    const n = Math.max(1, Math.min(8, parseInt(String(args.count)) || 1));
+    const n = Math.max(1, Math.min(MAX_GENERATION_COUNT, parseInt(String(args.count)) || 1));
     const timeoutMs = (parseInt(String(args.timeout)) || 180) * 1000;
     let server;
     try {

package/bin/commands/multimode.js

@@ -5,6 +5,8 @@ import { dataUriToFile, defaultOutName, fileToDataUri } from "../lib/files.js";
 import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { config } from "../../config.js";
 import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from "../lib/recover-output.js";
+const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
+const MAX_REFERENCE_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxRefCount) || 5));
 const SPEC = {
     flags: {
         quality: { short: "q", type: "string", default: "low" },
@@ -36,7 +38,7 @@ const HELP = `
   Options:
     -q, --quality <low|medium|high>     Default: low
     -s, --size <WxH>                    Default: 1024x1024
-        --max-images <1..8>             Default: 4
+        --max-images <1..${MAX_GENERATION_COUNT}>            Default: 4
     -o, --out <file>                    First image (implies --max-images 1)
     -d, --out-dir <dir>                 Output dir for multiple images
         --json
@@ -44,7 +46,7 @@ const HELP = `
         --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>
                                       Provider (oauth = GPT OAuth; grok = xAI Grok; agy/gemini-api = Gemini)
         --mode <auto|direct>            Prompt handling mode. Default: auto
-        --ref <file>                    Attach reference image (repeatable, max 5)
+        --ref <file>                    Attach reference image (repeatable, max ${MAX_REFERENCE_COUNT})
         --reasoning-effort <none|low|medium|high|xhigh>
         --web-search / --no-web-search
         --moderation <auto|low>
@@ -83,10 +85,10 @@ export default async function multimodeCmd(argv) {
         die(exitCodeForError(e), e.message);
         throw e;
     }
-    const maxImages = Math.max(1, Math.min(8, parseInt(String(args["max-images"])) || 4));
+    const maxImages = Math.max(1, Math.min(MAX_GENERATION_COUNT, parseInt(String(args["max-images"])) || 4));
     const refs = (Array.isArray(args.ref) ? args.ref : []);
-    if (refs.length > 5)
-        die(2, "max 5 --ref attachments");
+    if (refs.length > MAX_REFERENCE_COUNT)
+        die(2, `max ${MAX_REFERENCE_COUNT} --ref attachments`);
     const references = await Promise.all(refs.map((p) => fileToDataUri(p)));
     const outDir = args["out-dir"] ? String(args["out-dir"]) : null;
     const explicitOut = args.out ? String(args.out) : null;

package/bin/commands/node.js

@@ -4,6 +4,7 @@ import { streamSse } from "../lib/sse.js";
 import { fileToDataUri, dataUriToFile, defaultOutName } from "../lib/files.js";
 import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { config } from "../../config.js";
+const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
 const HELP = `
   ima2 node <subcommand> [options]
 
@@ -75,7 +76,7 @@ async function generateSub(argv) {
         prompt,
         quality: args.quality,
         size: args.size,
-        n: Math.max(1, Math.min(8, parseInt(String(args.count)) || 1)),
+        n: Math.max(1, Math.min(MAX_GENERATION_COUNT, parseInt(String(args.count)) || 1)),
         references,
         moderation: args.moderation,
         sessionId: args.session,

package/config.js

@@ -79,7 +79,8 @@ export const config = {
         maxRefB64Bytes: pickInt(env.IMA2_MAX_REF_B64_BYTES, fileCfg.limits?.maxRefB64Bytes, 7 * 1024 * 1024),
         maxMetadataReadB64Bytes: pickInt(env.IMA2_MAX_METADATA_READ_B64_BYTES, fileCfg.limits?.maxMetadataReadB64Bytes, 12 * 1024 * 1024),
         maxRefCount: pickInt(env.IMA2_MAX_REF_COUNT, fileCfg.limits?.maxRefCount, 5),
-        maxParallel: pickInt(env.IMA2_MAX_PARALLEL, fileCfg.limits?.maxParallel, 8),
+        maxGeneratedImages: pickInt(env.IMA2_MAX_GENERATED_IMAGES, fileCfg.limits?.maxGeneratedImages, 24),
+        maxParallel: pickInt(env.IMA2_MAX_PARALLEL, fileCfg.limits?.maxParallel, 24),
         graphMaxNodes: pickInt(env.IMA2_GRAPH_MAX_NODES, fileCfg.limits?.graphMaxNodes, 500),
         graphMaxEdges: pickInt(env.IMA2_GRAPH_MAX_EDGES, fileCfg.limits?.graphMaxEdges, 1000),
         promptImportMaxFileBytes: pickInt(env.IMA2_PROMPT_IMPORT_MAX_FILE_BYTES, fileCfg.limits?.promptImportMaxFileBytes, 512 * 1024),
@@ -133,6 +134,7 @@ export const config = {
         promptImportDiscoveryRegistryFile: pickStr(env.IMA2_PROMPT_IMPORT_DISCOVERY_REGISTRY_FILE, fileCfg.storage?.promptImportDiscoveryRegistryFile, join(configDir, "prompt-import-discovery.json")),
         configFile: join(configDir, "config.json"),
         advertiseFile: pickStr(env.IMA2_ADVERTISE_FILE, fileCfg.storage?.advertiseFile, join(configDir, "server.json")),
+        generationRequestLogFile: pickStr(env.IMA2_GENERATION_REQUEST_LOG_FILE, fileCfg.storage?.generationRequestLogFile, join(configDir, "generation-request-log.json")),
         staticMaxAge: pickStr(env.IMA2_STATIC_MAX_AGE, fileCfg.storage?.staticMaxAge, "1y"),
     },
     ids: {
@@ -193,6 +195,10 @@ export const config = {
         timeoutMs: pickInt(env.IMA2_CARD_NEWS_PLANNER_TIMEOUT_MS, fileCfg.cardNewsPlanner?.timeoutMs, 60_000),
         deterministicFallback: pickBool(env.IMA2_CARD_NEWS_PLANNER_FALLBACK, fileCfg.cardNewsPlanner?.deterministicFallback, false),
     },
+    agentPlanner: {
+        enabled: pickBool(env.IMA2_AGENT_PLANNER_ENABLED, fileCfg.agentPlanner?.enabled, true),
+        timeoutMs: pickInt(env.IMA2_AGENT_PLANNER_TIMEOUT_MS, fileCfg.agentPlanner?.timeoutMs, 30_000),
+    },
     comfy: {
         defaultUrl: pickStr(env.IMA2_COMFY_URL, fileCfg.comfy?.defaultUrl, "http://127.0.0.1:8188"),
         uploadTimeoutMs: pickPositiveInt(env.IMA2_COMFY_UPLOAD_TIMEOUT_MS, fileCfg.comfy?.uploadTimeoutMs, 30_000),
@@ -216,6 +222,7 @@ export const GENERATED_DIR = config.storage.generatedDir;
 export const BODY_LIMIT = config.server.bodyLimit;
 export const MAX_REF_B64_BYTES = config.limits.maxRefB64Bytes;
 export const MAX_REFS = config.limits.maxRefCount;
+export const MAX_GENERATED_IMAGES = config.limits.maxGeneratedImages;
 export const MAX_N = config.limits.maxParallel;
 export const INFLIGHT_TTL_MS = config.inflight.ttlMs;
 export const INFLIGHT_REAP_MS = config.inflight.reapMs;

package/docs/API.md

@@ -17,7 +17,7 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 - `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`. 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); these are honored only on the direct API path — the Vertex AI endpoint (`aiplatform.googleapis.com`) rejects the `response_format` field and always returns a default 1K/1:1 image regardless of requested 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.
+- `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.
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
 - Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
@@ -163,7 +163,7 @@ data: {"requestId":"req_abc","jobId":"req_abc","phase":"streaming"}
 |---|---|---|
 | Accepted | `202` | `{ "requestId": "req_xxx" }` |
 | Duplicate active `requestId` | `409` | `REQUEST_ID_IN_USE` |
-| More than 12 concurrent active jobs | `429` | `TOO_MANY_JOBS` with `Retry-After: 5` |
+| More than the configured concurrent active job limit | `429` | `TOO_MANY_JOBS` with `Retry-After: 5`; default limit is `24` via `IMA2_MAX_PARALLEL` |
 
 Progress events are published on `GET /api/events`. The POST response returns immediately; clients must not expect SSE on the POST connection when `async: true`.
 
@@ -604,7 +604,7 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `VIDEO_PROVIDER_UNSUPPORTED` | Video generation requires provider `"grok"` or `"grok-api"` |
 | `SSE_CAPACITY` | More than 512 concurrent `GET /api/events` listeners |
 | `REQUEST_ID_IN_USE` | Async POST used a `requestId` that already has an active job |
-| `TOO_MANY_JOBS` | More than 12 concurrent active generation jobs (`Retry-After: 5`) |
+| `TOO_MANY_JOBS` | More than the configured concurrent active generation job limit (`Retry-After: 5`; default `24`) |
 
 ## Key Management
 
@@ -612,11 +612,12 @@ API key management endpoints for configuring provider credentials at runtime thr
 
 | Endpoint | Method | Description |
 |---|---|---|
-| `/api/keys/status` | GET | Returns configured/valid/maskedKey status for all providers (openai, xai, gemini, vertex) |
+| `/api/keys/status` | GET | Returns configured/valid/maskedKey status for all providers (openai, xai, gemini, vertex) plus `geminiAuthMode` (`"apikey"` or `"vertex"`) |
 | `/api/keys/:provider` | PUT | Save an API key. Body: `{ "apiKey": "..." }`. Validates key format and upstream before saving to config.json. Provider: `openai`, `xai`, or `gemini`. |
 | `/api/keys/:provider` | DELETE | Remove a config-sourced API key. Env-sourced keys cannot be removed (`ENV_KEY_IMMUTABLE`). |
 | `/api/keys/vertex` | PUT | Save a Vertex AI service account JSON. Body: `{ "serviceAccountJson": "..." }`. Validates JSON structure (`type: "service_account"`, `project_id` required). |
 | `/api/keys/vertex` | DELETE | Remove a config-sourced Vertex AI service account. |
+| `/api/keys/gemini-auth-mode` | PUT | Persist the Gemini auth mode chosen in the settings dropdown. Body: `{ "mode": "apikey" \| "vertex" }`. Saved to `config.json` and hot-updated. |
 
 Keys saved via PUT are stored in `config.json` and hot-updated in the runtime context (no server restart required). Keys loaded from environment variables (`OPENAI_API_KEY`, `XAI_API_KEY`, `GEMINI_API_KEY`, `VERTEX_SERVICE_ACCOUNT_JSON`) take precedence and are immutable through the API.
 

package/docs/CLI.md

@@ -41,7 +41,7 @@ Agents should start from the packaged skill and capability commands instead of g
 | `ima2 defaults --json` | Print the running server's effective model/reasoning defaults, falling back to local config when no server is reachable |
 | `ima2 defaults --local --json` | Print local effective defaults without contacting the server |
 
-`ima2 capabilities --json` separates supported and unsupported model ids. Agents should use only `valid.imageModels.supported` for generation/default choices. `limits.maxParallel` is advisory queue guidance; it is not a server-side concurrency semaphore.
+`ima2 capabilities --json` separates supported and unsupported model ids. Agents should use only `valid.imageModels.supported` for generation/default choices. `limits.maxGeneratedImages` reports the configured per-request image count limit, and `limits.maxParallel` reports the enforced server-side inflight capacity guard.
 
 ## Generation
 
@@ -61,7 +61,7 @@ Provider override semantics:
 - `api` forces the API-key Responses path and requires a configured API key.
 - `oauth` forces the local OAuth proxy path.
 - `grok` uses the bundled progrok xAI proxy (`127.0.0.1:18645`). Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.3` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
-- `agy` spawns the Antigravity CLI to generate via Google Gemini (`nano-banana-2`). Fixed 1024×1024 JPEG output, max 3 refs. No web search, quality, size, or mask controls.
+- `agy` spawns the Antigravity CLI to generate via Google Gemini (`nano-banana-2`). Fixed 1024×1024 JPEG output, max 3 refs. No web search, quality, size, or mask controls. If `agy` is not on the server process PATH, ima2 also checks common user-local installs such as `~/.local/bin/agy`; set `IMA2_AGY_BIN=/absolute/path/to/agy` to force a specific binary.
 - `gemini-api` calls the Google Generative Language API directly. Models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Use `--model nano-banana-2` or `--model nano-banana-pro` to select. Supports `--size` for aspect ratio and resolution (512px–4K) on the direct API path; Vertex AI ignores aspect/size. Requires `GEMINI_API_KEY` or a Vertex AI service account (`VERTEX_SERVICE_ACCOUNT_JSON`). Switching from `agy` or `gemini-api` provider auto-selects the corresponding Gemini model; switching away resets to the GPT default.
 - `auto` preserves route default behavior and currently resolves to GPT OAuth unless server routing changes.
 
@@ -108,7 +108,7 @@ mockup`.
 For dense or critical text, keep the text large and explicit. Exact placement,
 small text, and pixel-perfect typography can still need iteration or post-editing.
 
-Multimode-specific flags include `--max-images <1..8>`, `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api|grok|grok-api|agy|gemini-api>`, and `--show-partial`. `ima2 edit --mask` remains intentionally deferred to #31 because current mask plumbing is guided edit rather than guaranteed true masked/inpaint semantics.
+Multimode-specific flags include `--max-images <1..24>` by default (configurable through `IMA2_MAX_GENERATED_IMAGES`), `--ref <file>` (repeatable, max 5), `--mode <auto|direct>`, `--provider <auto|oauth|api|grok|grok-api|agy|gemini-api>`, and `--show-partial`. `ima2 edit --mask` remains intentionally deferred to #31 because current mask plumbing is guided edit rather than guaranteed true masked/inpaint semantics.
 
 ## Video
 
@@ -362,7 +362,7 @@ comfy.{defaultUrl,uploadTimeoutMs,maxUploadBytes}
 storage.{generatedDir,generatedDirName}
 server.{port,host,bodyLimit}
 oauth.{proxyPort,statusTimeoutMs,restartDelayMs}
-limits.{maxRefCount,maxParallel}
+limits.{maxRefCount,maxGeneratedImages,maxParallel}
 history.{defaultPageSize,maxPageCap}
 ```
 

package/docs/FAQ.ko.md

@@ -337,7 +337,7 @@ GPT OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수
 
 ### 동시 작업 상한은 얼마인가요?
 
-서버는 동시 생성 작업을 12건(`MAX_CONCURRENT_JOBS`)으로 제한합니다. 초과 요청은 `429`와 `Retry-After: 5`를 받습니다. SSE 엔드포인트 자체는 512개 동시 연결까지 지원합니다.
+서버는 동시 생성 작업을 설정값 `limits.maxParallel` 기준으로 제한합니다(기본 `24`, `IMA2_MAX_PARALLEL`로 변경 가능). 초과 요청은 `429`와 `Retry-After: 5`를 받습니다. SSE 엔드포인트 자체는 512개 동시 연결까지 지원합니다.
 
 ## CLI 점검 순서
 

package/docs/FAQ.md

@@ -362,7 +362,7 @@ The event channel client reconnects automatically with exponential backoff. On r
 
 ### What is the maximum number of concurrent jobs?
 
-The server caps concurrent generation jobs at 12 (`MAX_CONCURRENT_JOBS`). Additional requests receive `429` with `Retry-After: 5`. The SSE endpoint itself caps at 512 simultaneous connections.
+The server caps concurrent generation jobs at the configured `limits.maxParallel` value (default `24`, overridable with `IMA2_MAX_PARALLEL`). Additional requests receive `429` with `Retry-After: 5`. The SSE endpoint itself caps at 512 simultaneous connections.
 
 ## CLI troubleshooting checklist
 

package/docs/IMAGE_RESOLUTION.md

@@ -0,0 +1,29 @@
+# Image Resolution (OAuth path) — Temporary Limitation
+
+OAuth (ChatGPT subscription / Codex backend) image generation has a backend-imposed
+resolution behavior. This is documented here because it is a **temporary limitation
+and the future direction is undecided**.
+
+## Behavior
+
+- **Aspect ratio is honored** exactly per the requested `size`. The prompt carries a
+  directive (`You MUST generate this image at exactly WxH resolution as a TALL vertical
+  PORTRAIT / WIDE horizontal LANDSCAPE / SQUARE canvas`), so portrait/landscape/square
+  come out with the correct orientation.
+- **Total pixels are capped at ~1.57M** (≈ 1024×1536) by the OAuth backend. 1K presets
+  are exact; larger requests keep the aspect ratio but scale down.
+
+| requested `size` | actual PNG (OAuth) | note |
+|---|---|---|
+| 1024×1536 (portrait) | 1024×1536 | exact |
+| 1536×1024 (landscape) | 1536×1024 | exact |
+| 2048×1152 (16:9) | 1672×941 | aspect kept, scaled to ~1.57M |
+| 2048×2048 (square) | 1254×1254 | aspect kept, scaled |
+
+## If you need exact large pixels
+
+Use the **API-key path** (`/images/generations`, `gpt-image` — arbitrary resolutions up
+to 3840×2160). The OAuth path is free (ChatGPT subscription) but pixel-capped.
+
+> Verified by server `/api/generate` E2E on 2026-06-27.
+> **This is a temporary limitation; the future direction is undecided.**

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

@@ -4,16 +4,20 @@ 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: 191 (runtime: 66, contract: 125)
+Total: 201 (runtime: 71, contract: 130)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
+- `tests/agent-mode-llm-planner-contract.test.ts`
 - `tests/agent-mode-parallel-contract.test.ts`
 - `tests/agent-mode-queue-contract.test.ts`
 - `tests/agent-mode-queue-migration-contract.test.ts`
 - `tests/agent-mode-runtime-contract.test.ts`
 - `tests/agent-mode-slash-command-contract.test.ts`
+- `tests/agent-mode-ux-feedback-contract.test.ts`
 - `tests/agent-video-intent.test.ts`
+- `tests/agy-artifact-fallback.test.ts`
+- `tests/agy-cli.test.ts`
 - `tests/api-cache-policy.test.ts`
 - `tests/api-provider-parity.test.ts`
 - `tests/billing-source.test.ts`
@@ -29,6 +33,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/generate-route-validation-error.test.ts`
 - `tests/generated-static-privacy.test.ts`
 - `tests/generation-errors.test.ts`
+- `tests/generation-request-log.test.ts`
 - `tests/grok-command-login-contract.test.ts`
 - `tests/grok-planner-adapter.test.ts`
 - `tests/grok-proxy-launcher.test.ts`
@@ -78,6 +83,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/agent-mode-frontend-contract.test.js`
 - `tests/agent-mode-layout-contract.test.js`
 - `tests/agent-mode-right-sidebar-contract.test.js`
+- `tests/agent-mode-run-progress-contract.test.ts`
 - `tests/agent-mode-tool-folding-contract.test.js`
 - `tests/app-weight-splitting-contract.test.js`
 - `tests/async-capacity-retry-behavior.test.ts`
@@ -100,6 +106,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/canvas-hit-test-contract.test.js`
 - `tests/canvas-mask-contract.test.js`
 - `tests/canvas-memo-contract.test.js`
+- `tests/canvas-memo-prompt-contract.test.js`
 - `tests/canvas-mode-contract.test.js`
 - `tests/canvas-object-key-contract.test.js`
 - `tests/canvas-persistence-contract.test.js`
@@ -142,6 +149,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/gallery-shortcuts-visible-domain-contract.test.js`
 - `tests/gallery-viewer-navigation-contract.test.js`
 - `tests/generation-controls-ux-contract.test.js`
+- `tests/generation-limit-unlock-contract.test.js`
 - `tests/health.test.js`
 - `tests/history-index-contract.test.js`
 - `tests/history-permanent-delete.test.js`
@@ -165,6 +173,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/node-diagnostics-contract.test.js`
 - `tests/node-edge-disconnect-contract.test.js`
 - `tests/node-footer-compact-contract.test.js`
+- `tests/node-gallery-drop-contract.test.js`
 - `tests/node-generation-lock-contract.test.js`
 - `tests/node-layout-contract.test.js`
 - `tests/node-pending-recovery-contract.test.js`
@@ -184,6 +193,7 @@ Total: 191 (runtime: 66, contract: 125)
 - `tests/prompt-library-ui-contract.test.js`
 - `tests/prompt-studio-docs-contract.test.js`
 - `tests/prompt-studio-ui-contract.test.js`
+- `tests/provider-ui-polish-contract.test.js`
 - `tests/server-fallback-contract.test.js`
 - `tests/server.test.js`
 - `tests/session-conflict.test.js`

package/lib/agentCommandParser.js

@@ -1,3 +1,6 @@
+import { config } from "../config.js";
+const MAX_AGENT_VARIANT_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
+const MAX_AGENT_PARALLELISM = Math.max(1, Math.trunc(Number(config.limits.maxParallel) || 24));
 const COMMAND_ALIASES = {
     ask: "question",
     q: "question",
@@ -28,7 +31,7 @@ export function parseAgentSlashCommand(input) {
         return null;
     const rest = (match[2] ?? "").trim();
     const countCommands = ["variants", "generate", "parallelism"];
-    const parsed = countCommands.includes(name) ? parseLeadingCount(rest) : { prompt: rest };
+    const parsed = countCommands.includes(name) ? parseLeadingCount(rest, name) : { prompt: rest };
     return {
         name,
         rawName,
@@ -41,9 +44,9 @@ export function formatAgentSlashHelp() {
     return [
         "Available Agent commands:",
         "/question <topic> - ask a planning question without generating images.",
-        "/variants <1-8> <prompt> - force that many image variants.",
-        "/generate <1-8> <prompt> - generate a bounded fanout from one request.",
-        "/parallelism <1-8> <prompt> - cap concurrent tool calls for this turn.",
+        `/variants <1-${MAX_AGENT_VARIANT_COUNT}> <prompt> - force that many image variants.`,
+        `/generate <1-${MAX_AGENT_VARIANT_COUNT}> <prompt> - generate a bounded fanout from one request.`,
+        `/parallelism <1-${MAX_AGENT_PARALLELISM}> <prompt> - cap concurrent tool calls for this turn.`,
     ].join("\n");
 }
 export function formatAgentQuestionReply(prompt) {
@@ -53,12 +56,13 @@ export function formatAgentQuestionReply(prompt) {
     }
     return topic;
 }
-function parseLeadingCount(value) {
+function parseLeadingCount(value, name) {
     const match = /^(\d+)(?:\s+([\s\S]*))?$/.exec(value);
     if (!match)
         return { prompt: value };
+    const max = name === "parallelism" ? MAX_AGENT_PARALLELISM : MAX_AGENT_VARIANT_COUNT;
     return {
-        value: Math.max(1, Math.min(8, Number(match[1]))),
+        value: Math.max(1, Math.min(max, Number(match[1]))),
         prompt: (match[2] ?? "").trim(),
     };
 }

package/lib/agentGenerationPlanner.js

@@ -1,25 +1,35 @@
-const HARD_MAX_VARIANTS = 8;
+import { config } from "../config.js";
+const HARD_MAX_VARIANTS = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
 const AMBIGUOUS_MULTI_VARIANTS = 3;
 const KOREAN_COUNT_WORDS = [
-    [/(?:한|하나|1)\s*(?:장|개|가지|컷|시안|버전)/u, 1],
-    [/(?:두|둘|2)\s*(?:장|개|가지|컷|시안|버전)/u, 2],
-    [/(?:세|셋|3)\s*(?:장|개|가지|컷|시안|버전)/u, 3],
-    [/(?:네|넷|4)\s*(?:장|개|가지|컷|시안|버전)/u, 4],
-    [/(?:다섯|5)\s*(?:장|개|가지|컷|시안|버전)/u, 5],
-    [/(?:여섯|6)\s*(?:장|개|가지|컷|시안|버전)/u, 6],
-    [/(?:일곱|7)\s*(?:장|개|가지|컷|시안|버전)/u, 7],
-    [/(?:여덟|8)\s*(?:장|개|가지|컷|시안|버전)/u, 8],
+    [/(?:스물네|스물\s*네|이십사)\s*(?:장|개|가지|컷|시안|버전)/u, 24],
+    [/(?:열두|열\s*두|십이)\s*(?:장|개|가지|컷|시안|버전)/u, 12],
+    [/(?:열|열\s*개)\s*(?:장|개|가지|컷|시안|버전)?/u, 10],
+    [/(?:한|하나)\s*(?:장|개|가지|컷|시안|버전)/u, 1],
+    [/(?:두|둘)\s*(?:장|개|가지|컷|시안|버전)/u, 2],
+    [/(?:세|셋)\s*(?:장|개|가지|컷|시안|버전)/u, 3],
+    [/(?:네|넷)\s*(?:장|개|가지|컷|시안|버전)/u, 4],
+    [/(?:다섯)\s*(?:장|개|가지|컷|시안|버전)/u, 5],
+    [/(?:여섯)\s*(?:장|개|가지|컷|시안|버전)/u, 6],
+    [/(?:일곱)\s*(?:장|개|가지|컷|시안|버전)/u, 7],
+    [/(?:여덟)\s*(?:장|개|가지|컷|시안|버전)/u, 8],
+    [/(?:아홉)\s*(?:장|개|가지|컷|시안|버전)/u, 9],
 ];
 const ENGLISH_COUNT_WORDS = [
-    [/\b(?:one|1)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 1],
-    [/\b(?:two|2)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 2],
-    [/\b(?:three|3)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 3],
-    [/\b(?:four|4)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 4],
-    [/\b(?:five|5)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 5],
-    [/\b(?:six|6)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 6],
-    [/\b(?:seven|7)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 7],
-    [/\b(?:eight|8)\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 8],
+    [/\btwenty[-\s]?four\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 24],
+    [/\btwelve\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 12],
+    [/\bten\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 10],
+    [/\bone\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 1],
+    [/\btwo\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 2],
+    [/\bthree\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 3],
+    [/\bfour\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 4],
+    [/\bfive\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 5],
+    [/\bsix\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 6],
+    [/\bseven\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 7],
+    [/\beight\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 8],
+    [/\bnine\s*(?:image|variant|version|option|candidate|shot|render)?s?\b/iu, 9],
 ];
+const NUMERIC_COUNT_PATTERN = /(?:^|\b)(\d{1,3})\s*(?:장|개|가지|컷|시안|버전|image|images|variant|variants|version|versions|option|options|candidate|candidates|shot|shots|render|renders)(?:\b|$)/iu;
 export function deriveAgentGenerationPlan({ prompt, settings, command = null }) {
     if (command?.name === "question" || command?.name === "help") {
         return {
@@ -32,6 +42,7 @@ export function deriveAgentGenerationPlan({ prompt, settings, command = null })
             reason: command.name === "help" ? "Slash help answered without image generation." : "Question command answered without image generation.",
             command: command.name,
             assistantText: null,
+            sourceImagePolicy: null,
         };
     }
     if (isVideoIntent(prompt)) {
@@ -45,6 +56,7 @@ export function deriveAgentGenerationPlan({ prompt, settings, command = null })
             reason: "Video generation detected from prompt keywords.",
             command: command?.name ?? null,
             assistantText: null,
+            sourceImagePolicy: "auto",
         };
     }
     const variantDecision = decideVariantCount(prompt, settings, command);
@@ -60,18 +72,41 @@ export function deriveAgentGenerationPlan({ prompt, settings, command = null })
         reason: variantDecision.reason,
         command: command?.name ?? null,
         assistantText: null,
+        sourceImagePolicy: inferSourceImagePolicy(prompt, prompts.length > 1 ? "fanout" : "single"),
     };
 }
 export function normalizeAgentGenerationPlan(prompt, value, settings) {
     const input = value && typeof value === "object" ? value : {};
     const prompts = cleanPromptArray(input.prompts);
+    // errors/question modes legitimately carry no generation prompts — they
+    // must be resolved before the empty-prompts fallback re-derives a regex plan.
+    if (input.mode === "errors" || input.mode === "question") {
+        return {
+            mode: input.mode,
+            prompts: [],
+            requestedVariants: 0,
+            plannedVariants: 0,
+            plannedParallelism: 0,
+            source: cleanPlanSource(input.source),
+            reason: cleanReason(input.reason, input.mode === "errors" ? "User asked about recent generation failures." : "User asked a question answered without generation."),
+            command: cleanCommandName(input.command),
+            assistantText: typeof input.assistantText === "string" ? input.assistantText : null,
+            videoParams: null,
+            sourceImagePolicy: null,
+        };
+    }
     if (prompts.length === 0)
         return deriveAgentGenerationPlan({ prompt, settings, command: cleanCommand(input.command) });
     const plannedVariants = cleanCount(input.plannedVariants, prompts.length, 0, HARD_MAX_VARIANTS);
     const requestedParallelism = cleanCount(input.plannedParallelism, settings.parallelism, 1, HARD_MAX_VARIANTS);
     const plannedParallelism = resolvePlannedParallelism({ ...settings, parallelism: requestedParallelism }, plannedVariants, null);
+    const mode = input.mode === "question"
+        ? "question"
+        : input.mode === "video"
+            ? "video"
+            : prompts.length > 1 ? "fanout" : "single";
     return {
-        mode: input.mode === "question" ? "question" : input.mode === "video" ? "video" : prompts.length > 1 ? "fanout" : "single",
+        mode,
         prompts,
         requestedVariants: cleanCount(input.requestedVariants, plannedVariants, 0, HARD_MAX_VARIANTS),
         plannedVariants,
@@ -80,8 +115,24 @@ export function normalizeAgentGenerationPlan(prompt, value, settings) {
         reason: cleanReason(input.reason, prompts.length > 1 ? "Stored fanout plan." : "Stored single-image plan."),
         command: cleanCommandName(input.command),
         assistantText: typeof input.assistantText === "string" ? input.assistantText : null,
+        videoParams: mode === "video" ? cleanVideoParams(input.videoParams) : null,
+        sourceImagePolicy: cleanSourceImagePolicy(input.sourceImagePolicy) ?? inferSourceImagePolicy(prompt, mode),
     };
 }
+function inferSourceImagePolicy(prompt, mode) {
+    if (mode === "question" || mode === "errors")
+        return null;
+    if (mode === "video")
+        return "auto";
+    const text = prompt.trim();
+    if (/(?:i2i\s*말고|image-to-image\s*말고|새로운\s*방식|새로|별도|독립|from\s+scratch|new\s+image|fresh\s+image|without\s+(?:reference|refs?)|no\s+(?:reference|refs?))/iu.test(text)) {
+        return "none";
+    }
+    if (/(?:이\s*이미지|현재\s*이미지|방금\s*(?:그거|그\s*이미지|이미지)|참조|레퍼런스|reference|refs?|i2i|image-to-image|수정|편집|바꿔|변형|유지(?:해서)?|그걸|그거)/iu.test(text)) {
+        return "current";
+    }
+    return "none";
+}
 function decideVariantCount(prompt, settings, command) {
     if (command?.name === "variants" || command?.name === "generate") {
         const count = clampCount(command.value ?? AMBIGUOUS_MULTI_VARIANTS, HARD_MAX_VARIANTS);
@@ -114,6 +165,11 @@ function decideVariantCount(prompt, settings, command) {
 }
 function inferRequestedVariantCount(prompt) {
     const text = prompt.trim();
+    const numericMatch = NUMERIC_COUNT_PATTERN.exec(text);
+    if (numericMatch) {
+        const count = Math.max(1, Math.trunc(Number.parseInt(numericMatch[1] ?? "", 10) || 1));
+        return { count, reason: `User request explicitly implies ${count} variant${count === 1 ? "" : "s"}.` };
+    }
     for (const [pattern, count] of [...KOREAN_COUNT_WORDS, ...ENGLISH_COUNT_WORDS]) {
         if (pattern.test(text)) {
             return { count, reason: `User request explicitly implies ${count} variant${count === 1 ? "" : "s"}.` };
@@ -156,10 +212,31 @@ function cleanPlanSource(value) {
         value === "auto-request" ||
         value === "manual-settings" ||
         value === "slash-command" ||
-        value === "question-command")
+        value === "question-command" ||
+        value === "llm-planner")
         return value;
     return "auto-default";
 }
+function cleanSourceImagePolicy(value) {
+    if (value === "auto" || value === "none" || value === "current")
+        return value;
+    return null;
+}
+export function cleanVideoParams(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const input = value;
+    const params = {};
+    const duration = typeof input.duration === "number" ? input.duration : Number(input.duration);
+    if (Number.isFinite(duration))
+        params.duration = Math.max(1, Math.min(15, Math.round(duration)));
+    if (input.resolution === "480p" || input.resolution === "720p")
+        params.resolution = input.resolution;
+    if (typeof input.aspectRatio === "string" && /^(auto|16:9|9:16|4:3|3:4|3:2|2:3|1:1)$/.test(input.aspectRatio)) {
+        params.aspectRatio = input.aspectRatio;
+    }
+    return Object.keys(params).length > 0 ? params : null;
+}
 function cleanCommandName(value) {
     if (value === "question" ||
         value === "help" ||