ima2-gen 2.0.1 → 2.0.3

package/docs/API.md

@@ -10,14 +10,14 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation supports OAuth, API-key, Grok, and Gemini (agy) providers.
+Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-api`) providers.
 
 - `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.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 and resolutions (512px–4K). Requires a `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON. 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`.
@@ -35,6 +35,16 @@ Generation section below for the full endpoint specification.
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
 | `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
+| `GET` | `/api/quota` | Provider quota: returns `{ codex, grok }`. Grok result includes `billing: { usedUsd, limitUsd }` and a `monthly` percent window drawn from the xAI billing API. |
+
+## Account Switching
+
+| Method | Path | Notes |
+|---|---|---|
+| `POST` | `/api/auth/switch` | Start a device-code OAuth flow. Body: `{ "provider": "grok" \| "codex" }`. Returns `{ sessionId, userCode, verificationUrl }`. |
+| `GET` | `/api/auth/switch/:sessionId` | Poll switch-account session status. Returns `{ status }` where status is `pending`, `complete`, `error`, or `expired`. |
+
+The Switch Account flow opens a browser verification URL. Once the user completes the device-code step, the server saves the new credentials (Grok: `~/.progrok/auth.json`; Codex: via `codex login --device-auth`) and the session transitions to `complete`. This endpoint is surfaced as a **Switch Account** button in the Settings QuotaCard for Grok and Codex providers.
 
 ## Storage
 
@@ -84,9 +94,81 @@ Storage `state` values:
 | `GET` | `/api/inflight` | Active jobs only by default |
 | `GET` | `/api/inflight?includeTerminal=1` | Includes recent terminal jobs for debugging |
 | `DELETE` | `/api/inflight/:requestId` | Cancel or forget an active job |
+| `GET` | `/api/events` | Persistent SSE multiplex channel for all async generation progress (see below) |
 
 In-flight logs and responses use `requestId` for correlation. Logs should not include raw prompts, reference data URLs, generated base64, tokens, cookies, auth headers, or raw upstream bodies.
 
+## Events (SSE Multiplexing)
+
+### `GET /api/events` (SSE Multiplexing)
+
+Single persistent Server-Sent Events channel that carries progress for all async generation jobs. The browser UI opens one `EventSource` here instead of holding a per-request SSE connection for each job, avoiding browser per-origin connection limits.
+
+| Query | Notes |
+|---|---|
+| `lastEventId` | Optional. Reconnect cursor; also accepted via the `Last-Event-ID` request header |
+
+**Response**: `text/event-stream` (persistent). Each frame uses standard SSE fields `id`, `event`, and `data` (JSON).
+
+**Connection limits**: When active listeners reach 512, the server returns `503` with `SSE_CAPACITY` before opening the stream.
+
+**Heartbeat**: Every 15 seconds the server writes a comment frame:
+
+```text
+: ping
+```
+
+**Replay**: On reconnect, the server replays events from an in-memory ring buffer (size 2000) for IDs newer than `lastEventId`. Large image payloads (>1000 characters) are omitted from replay with `_imageOmitted: true` in the `data` payload. If the requested ID is older than the oldest buffered event, the server emits a `replay-gap` event before live fan-out:
+
+| Event | Data | Description |
+|---|---|---|
+| `replay-gap` | `{ lastEventId, oldestAvailableId }` | Client should reconcile inflight state (for example via `GET /api/inflight`) |
+
+**Job routing**: Every `data` payload includes `jobId` (same value as the job's `requestId`). Event bodies also carry `requestId` where applicable. Clients filter events by matching `data.jobId` or `data.requestId` to the job they started.
+
+**Event types** (fan-out to all connected clients):
+
+| Event | Emitted by | Description |
+|---|---|---|
+| `phase` | node, multimode, video | Lifecycle phase change |
+| `partial` | node, multimode | Progressive preview image (base64 data URL) |
+| `image` | multimode | Final saved `GenerateItem` for one sequence image |
+| `done` | node, multimode, video | Terminal success payload (route-specific shape) |
+| `error` | all generation routes | Terminal failure |
+| `submitted` | video | Job submitted to xAI |
+| `progress` | video | Progress fraction 0.0–1.0 |
+| `planning` | video | Video planner running |
+
+Example SSE frame:
+
+```text
+id: 42
+event: phase
+data: {"requestId":"req_abc","jobId":"req_abc","phase":"streaming"}
+```
+
+### Async generation mode
+
+`POST /api/node/generate`, `POST /api/generate/multimode`, and `POST /api/video/generate` support an async POST mode for clients that already hold `GET /api/events`:
+
+```json
+{
+  "async": true,
+  "requestId": "req_xxx",
+  "...": "other route fields"
+}
+```
+
+| Outcome | HTTP | Body |
+|---|---|---|
+| Accepted | `202` | `{ "requestId": "req_xxx" }` |
+| Duplicate active `requestId` | `409` | `REQUEST_ID_IN_USE` |
+| 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`.
+
+CLI and legacy clients omit `async` and keep the original behavior: per-request SSE on the same POST response (`Accept: text/event-stream` where applicable). The server dual-emits in that mode — it writes SSE to the POST response and also publishes the same events on `GET /api/events`.
+
 ## Generation
 
 ### `POST /api/generate`
@@ -195,14 +277,46 @@ Body fields:
 }
 ```
 
-When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Extra node references are currently supported only for root nodes.
+When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Node-local references are allowed on both root and child/edit nodes; for child/edit nodes the parent image is sent first, then references, then the text prompt.
 
 With `provider: "grok"`, Node Mode uses the same xAI search + `grok-4.3` planner + Images API pipeline as classic generation. A parent node image, `externalSrc`, or extra references are passed to the planner and then to xAI `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return `GROK_REF_TOO_MANY` before upstream when that limit is exceeded. `quality: "high"` promotes the final image model to `grok-imagine-image-quality`.
 
-The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`.
+The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`. Alternatively, send `{ "async": true, "requestId": "req_xxx" }` in the body to receive `202 { requestId }` immediately and follow progress on `GET /api/events` (see Events section).
 
 Grok Node SSE responses do not include Responses API `partial` image events because the xAI Images API call is synchronous JSON. They still emit `phase` and `done`/`error` events so the Node UI can use the same in-flight lifecycle.
 
+### `POST /api/generate/multimode` (SSE)
+
+Multi-image sequence generation. SSE-only on the POST response unless async mode is used.
+
+```json
+{
+  "prompt": "a story in four panels",
+  "maxImages": 4,
+  "quality": "medium",
+  "size": "1024x1024",
+  "format": "png",
+  "moderation": "low",
+  "model": "gpt-5.4",
+  "provider": "oauth",
+  "references": [],
+  "requestId": "optional-client-id",
+  "async": false
+}
+```
+
+Send `Accept: text/event-stream` for per-request SSE on the POST connection. Or set `"async": true` with a client `requestId` to get `202 { requestId }` and receive events on `GET /api/events`.
+
+**SSE events**:
+
+| Event | Data | Description |
+|---|---|---|
+| `phase` | `{ requestId, phase, sequenceId?, maxImages? }` | Lifecycle phase |
+| `partial` | `{ requestId, image, index }` | Progressive preview |
+| `image` | full `GenerateItem` | One saved sequence image |
+| `done` | route-specific summary; may include `status: "partial"` after timeout if at least one image was saved | Sequence complete |
+| `error` | `{ requestId, error, code?, status? }` | Generation failed |
+
 ### `GET /api/node/:nodeId`
 
 Fetch stored node metadata and asset URL.
@@ -228,7 +342,7 @@ Server-side validation may return these reference codes:
 
 ### `POST /api/video/generate` (SSE)
 
-Generate a video via the Grok video provider. Returns Server-Sent Events.
+Generate a video via the Grok video provider. Returns Server-Sent Events on the POST connection, or accepts async mode (`{ "async": true, "requestId": "req_xxx" }`) for `202 { requestId }` with progress on `GET /api/events` (see Events section).
 
 ```json
 {
@@ -263,7 +377,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | Field | Type | Default | Notes |
 |---|---|---|---|
 | `prompt` | string | — | Required |
-| `provider` | string | `"grok"` | Must be `"grok"` |
+| `provider` | string | `"grok"` | `"grok"` or `"grok-api"` |
 | `model` | string | `grok-imagine-video` | Video model |
 | `duration` | integer | `5` | 1–15 seconds (clamped to 10 for reference-to-video) |
 | `resolution` | string | `"480p"` | `480p` or `720p` |
@@ -488,6 +602,9 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `GEMINI_API_SAFETY_BLOCKED` | Gemini API generation blocked by safety filter |
 | `GEMINI_API_NO_IMAGE` | Gemini API returned no image in response |
 | `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 the configured concurrent active generation job limit (`Retry-After: 5`; default `24`) |
 
 ## Key Management
 
@@ -495,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.
 
@@ -529,7 +647,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
 | `GET /api/history` | `ima2 ls` |
 | `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |
-| `POST /api/history/restore` | `ima2 history restore --trash-id` |
+| `POST /api/history/:filename/restore` | `ima2 history restore --trash-id` |
 | `POST /api/history/favorite` | `ima2 history favorite` |
 | `POST /api/history/import-local` | `ima2 history import` |
 | `POST /api/metadata/read` | `ima2 metadata` / `ima2 show --metadata` |
@@ -544,10 +662,16 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `…/api/cardnews/…` (gated on `features.cardNews`) | `ima2 cardnews …` |
 | `POST /api/comfy/export-image` | `ima2 comfy export` |
 | `GET /api/inflight` / `DELETE /api/inflight/:id` | `ima2 inflight ls` (alias `ps`) / `ima2 inflight rm` (alias `cancel`) |
+| `GET /api/events` (SSE multiplex) | Web UI only (persistent `EventSource`; no CLI wrapper) |
 | `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
 | `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` / `GET /api/grok/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` / `ima2 grok status` |
+| `GET /api/quota` | `ima2 billing` (includes Grok `usedUsd`/`limitUsd`) |
+| `POST /api/auth/switch` / `GET /api/auth/switch/:sessionId` | Web UI only (Settings > QuotaCard > Switch Account) |
 | `GET /api/health` | `ima2 ping` |
 | `GET /api/capabilities` | `ima2 capabilities` |
+| `GET /api/config/grok-planner` | — (Grok planner model query) |
+| `PATCH /api/config/grok-planner` | — (Grok planner model update) |
+| `GET /api/agy/status` | — (Antigravity CLI install status) |
 | `POST /api/history/backfill-thumbnails` | `ima2 backfill-thumbs` |
 | `GET /api/keys/status`, `PUT/DELETE /api/keys/:provider`, `PUT/DELETE /api/keys/vertex` | Web UI only (Settings > API Keys) |
 | `GET/POST/PATCH/DELETE /api/agent/*` (sessions, turns, queue) | — (Agent Mode; web UI only, no CLI) |
@@ -556,7 +680,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 Notes:
 - `ima2 history favorite` and `ima2 annotate …` send `X-Ima2-Browser-Id: cli-<sha1prefix>` derived from the config dir, so CLI activity does not collide with browser sessions.
 - `ima2 session graph save` performs a GET-then-PUT with `If-Match: "<version>"` to guard against `GRAPH_VERSION_CONFLICT`.
-- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`) use `Accept: text/event-stream`.
+- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`, `video`) use `Accept: text/event-stream`. The web UI instead uses `GET /api/events` plus `async: true` on POST routes.
 - `ima2 cardnews …` checks `runtimeConfig.features.cardNews` before calling the gated endpoints; when disabled the CLI exits 2 with a clear message instead of producing a 404.
 
 ## CLI Discovery

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,8 @@ 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.
 
 `ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
@@ -107,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
 
@@ -317,7 +318,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 inflight rm <requestId>` | Force-remove a stuck job |
 | `ima2 storage status` | Storage inspection (richer than `doctor`) |
 | `ima2 storage open` | Open the generated dir in the OS file manager (POST) |
-| `ima2 billing` | API usage / quota |
+| `ima2 billing` | API usage / quota; Grok result includes `billing.usedUsd` / `billing.limitUsd` drawn from the xAI billing API |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
 | `ima2 grok status` | Bundled progrok / xAI image-model probe state |
@@ -361,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

@@ -323,6 +323,22 @@ export HTTPS_PROXY=http://127.0.0.1:7890
 
 GPT OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수 있습니다. 회사 방화벽, TLS 검사, VPN, 프록시가 흐름을 깨뜨릴 수 있습니다. 로그인 실패와 `failed to fetch`가 반복되면 다른 네트워크에서도 시도해 보세요.
 
+## SSE 멀티플렉싱
+
+### 왜 웹 UI가 단일 SSE 연결을 쓰나요?
+
+브라우저는 같은 origin에 대해 동시 HTTP 연결 수를 제한합니다(보통 6개). 여러 이미지를 동시에 생성할 때 각 요청이 SSE 연결을 점유하면, multimode+node+video가 동시에 돌아갈 때 연결이 포화되어 갤러리 썸네일이 멈췄습니다.
+
+이제 웹 UI는 `GET /api/events`로 하나의 SSE 연결만 열고, 모든 생성 진행 이벤트를 멀티플렉싱합니다. 생성 요청은 `async: true`로 보내면 즉시 `202 { requestId }` 응답을 받아 연결을 바로 해제합니다. CLI는 영향 없이 기존 per-request SSE를 그대로 사용합니다.
+
+### SSE 연결이 끊기면 어떻게 되나요?
+
+이벤트 채널 클라이언트가 지수 백오프로 자동 재연결합니다. 재연결 시 `Last-Event-ID`를 보내서 서버의 링 버퍼(최대 2000건)에서 놓친 이벤트를 재전송받습니다. 버퍼에서 이미 사라진 이벤트가 있으면 `replay-gap` 이벤트로 알려줍니다.
+
+### 동시 작업 상한은 얼마인가요?
+
+서버는 동시 생성 작업을 설정값 `limits.maxParallel` 기준으로 제한합니다(기본 `24`, `IMA2_MAX_PARALLEL`로 변경 가능). 초과 요청은 `429`와 `Retry-After: 5`를 받습니다. SSE 엔드포인트 자체는 512개 동시 연결까지 지원합니다.
+
 ## CLI 점검 순서
 
 아래 순서대로 확인해 보세요.

package/docs/FAQ.md

@@ -103,6 +103,20 @@ ima2 serve
 
 If this happens on a company network, a firewall, VPN, proxy, or captive portal may also be blocking the OAuth flow.
 
+### How do I use the Gemini providers?
+
+Two Gemini providers are available:
+
+- **`agy`** — uses the Antigravity CLI (`agy -p`) with no API key needed. Requires the `agy` binary to be installed and logged in. Model is `nano-banana-2`, output is fixed at 1024×1024.
+
+- **`gemini-api`** — calls the Google Generative Language API directly. Add a `GEMINI_API_KEY` env var, or configure a key via Settings > API Keys. For Vertex AI, add a service account JSON via Settings or the `VERTEX_SERVICE_ACCOUNT_JSON` env var. When both an API key and Vertex credentials are present, Vertex takes priority. Use the auth-mode dropdown in Settings to switch between `apikey` and `vertex`; the choice is saved and restored automatically.
+
+The `gemini-api` provider supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). The web UI shows aspect-ratio and resolution controls (512px–4K) for `gemini-api`; these are honored only on the direct Gemini API path and are ignored by Vertex AI.
+
+### How do I re-authenticate Grok or Codex without restarting?
+
+Use the **Switch Account** button in Settings > QuotaCard for the provider. This starts a device-code OAuth flow: a new browser tab opens the verification URL, you complete the login, and the server automatically picks up the new credentials. The Grok quota bar also shows `$used / $limit` (in USD) drawn from the xAI billing API.
+
 ## Models and quota
 
 ### Which model should I use?
@@ -334,6 +348,22 @@ Use the host and port from your proxy client. If `ima2-gen` still fails after th
 
 GPT OAuth may require access to OpenAI and ChatGPT/Codex-related hosts. A corporate firewall, TLS inspection, VPN, or proxy can break the flow. Try a different network if login and `failed to fetch` errors keep repeating.
 
+## SSE Multiplexing
+
+### Why does the web UI use a single SSE connection?
+
+Browsers limit the number of concurrent HTTP connections to the same origin (typically 6). When generating multiple images at once, each generation request used to hold a Server-Sent Events connection open. With multimode, node, and video running simultaneously, the browser would run out of connections and gallery thumbnails would hang.
+
+The web UI now opens a single persistent `GET /api/events` SSE connection and all generation progress is multiplexed through it. Generation requests use `async: true` and receive an immediate `202 { requestId }` response, freeing the connection immediately. The CLI is unaffected — it still uses per-request SSE when `async` is not set.
+
+### What happens if the SSE connection drops?
+
+The event channel client reconnects automatically with exponential backoff. On reconnect, it sends `Last-Event-ID` so the server can replay missed events from its ring buffer (up to 2000 entries). If events have been evicted from the buffer, the server sends a `replay-gap` event so the client knows some updates may have been lost.
+
+### What is the maximum number of concurrent jobs?
+
+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
 
 Run these in order:

package/docs/README.ko.md

@@ -78,7 +78,7 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 1. **GPT OAuth** — ChatGPT 계정으로 로그인 (무료, 이미지만)
 2. **Grok OAuth** — xAI/Grok 계정으로 로그인 (이미지 + 영상)
 3. **Both** — GPT + Grok 둘 다 (전체 기능)
-4. **API Key** — OpenAI API 키 입력 (유료)
+4. **Web setup** — 웹 UI에서 전체 설정
 
 영상 생성은 Grok OAuth(2번 또는 3번)가 필요합니다.
 
@@ -95,6 +95,10 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
+### SSE 멀티플렉싱
+
+웹 UI는 단일 `GET /api/events` Server-Sent Events 연결로 모든 생성 진행 상황을 수신합니다. Multimode, node, video 요청은 비동기 POST(`202 { requestId }`)로 제출되고, 이벤트 버스를 통해 진행 이벤트가 멀티플렉싱됩니다. 기존 브라우저 6-연결 제한으로 인한 동시 생성 시 갤러리 hang 문제가 해결됩니다. `async: true`를 보내지 않는 CLI 클라이언트는 기존 per-request SSE 스트림을 그대로 사용할 수 있습니다.
+
 ## 이미지 생성 공급자
 
 이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
@@ -232,8 +236,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok 플래너 모델 (설정 UI 또는 `--planner-model` CLI 플래그로도 변경 가능) |
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | 기본 Grok 이미지 모델 |
-| `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
+| `IMA2_LOG_LEVEL` | `info` | 일반 `serve`는 `info`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | 디버그용 최근 작업 보존 시간 (5분) |
 | `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
 
 ### 로그 모드

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

@@ -4,27 +4,36 @@ 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: 177 (runtime: 61, contract: 116)
+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`
 - `tests/card-news-contract.test.ts`
+- `tests/card-news-template.test.ts`
+- `tests/classic-generate-async.test.ts`
 - `tests/cli-error-hints.test.ts`
 - `tests/cli-lib.test.ts`
 - `tests/comfy-bridge-contract.test.ts`
 - `tests/error-classify.test.ts`
+- `tests/event-bus.test.ts`
+- `tests/events-channel-contract.test.ts`
 - `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`
@@ -36,6 +45,7 @@ Total: 177 (runtime: 61, contract: 116)
 - `tests/image-metadata-route.test.ts`
 - `tests/image-metadata-xmp.test.ts`
 - `tests/image-model.test.ts`
+- `tests/inflight-guard-contract.test.ts`
 - `tests/inflight-persistence.test.ts`
 - `tests/inflight.test.ts`
 - `tests/local-import-contract.test.ts`
@@ -73,8 +83,12 @@ Total: 177 (runtime: 61, contract: 116)
 - `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`
+- `tests/async-capacity-retry-contract.test.js`
+- `tests/async-stream-subscribe-order.test.js`
 - `tests/background-cleanup-brush-rasterize.test.js`
 - `tests/background-cleanup-mask-compose.test.js`
 - `tests/bin.test.js`
@@ -92,6 +106,7 @@ Total: 177 (runtime: 61, contract: 116)
 - `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`
@@ -123,13 +138,18 @@ Total: 177 (runtime: 61, contract: 116)
 - `tests/current-image-actions-readiness-contract.test.js`
 - `tests/direct-mode-visual-contract.test.js`
 - `tests/edit-mask-api-contract.test.js`
+- `tests/frontend-connection-state-contract.test.js`
+- `tests/frontend-sse-risk-contract.test.js`
+- `tests/gallery-hang-regression-contract.test.ts`
 - `tests/gallery-load-older-contract.test.js`
 - `tests/gallery-navigation-ux-contract.test.js`
+- `tests/gallery-selection-during-generation-contract.test.js`
 - `tests/gallery-session-scope-contract.test.js`
 - `tests/gallery-shortcuts-behavior.test.js`
 - `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`
@@ -145,6 +165,7 @@ Total: 177 (runtime: 61, contract: 116)
 - `tests/multimode-backend-contract.test.js`
 - `tests/multimode-concurrent-store-contract.test.js`
 - `tests/multimode-ui-contract.test.js`
+- `tests/node-async-eventbus-contract.test.js`
 - `tests/node-batch-contract.test.js`
 - `tests/node-child-refs-contract.test.js`
 - `tests/node-child-refs-payload.test.js`
@@ -152,6 +173,7 @@ Total: 177 (runtime: 61, contract: 116)
 - `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`
@@ -171,6 +193,7 @@ Total: 177 (runtime: 61, contract: 116)
 - `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`
@@ -184,5 +207,6 @@ Total: 177 (runtime: 61, contract: 116)
 - `tests/toast-stack-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
 - `tests/video-continuity-ui-contract.test.js`
+- `tests/video-gallery-refresh-contract.test.ts`
 - `tests/vite-dev-port-contract.test.js`
 - `tests/web-search-toggle-contract.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(),
     };
 }