ima2-gen 3.12.3 → 3.13.0

package/README.md

@@ -16,7 +16,7 @@
 
 `ima2-gen` is a local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.
 
-Install globally and generate images and videos from eight core lanes: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, and MiniMax. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup — now with one-click GPT background transparency (server-verified real alpha), annotation hover feedback, and a full light/dark/system theme.
+Install globally and generate images and videos through the core registry: OpenAI OAuth/API, Grok OAuth/API, Antigravity CLI, Gemini API, AtlasCloud, MiniMax, NovelAI, and registered ComfyUI workflows. Runway and Higgsfield remain separate MCP-backed integrations. Iterate with history, references, node branches, multimode batches, and Canvas Mode cleanup — now with one-click GPT background transparency (server-verified real alpha), annotation hover feedback, and a full light/dark/system theme.
 
 ![ima2-gen classic workspace in light mode with a transparent-background result on the canvas.](assets/screenshots/classic-generate-lightmode.png)
 
@@ -107,6 +107,9 @@ Ctrl+C now performs a clean shutdown — closing the database, stopping child pr
 - **Video generation**: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done. Video frame copy buttons (First/Mid/Last) let you extract and copy keyframes from generated videos.
 - **Storyboard mode**: toggle storyboard mode in the composer to maintain character and scene continuity across sequential frames. Works with both image and video generation — image keyframes are composed for video production, and video clips inherit character/environment lock rules.
 - **Canvas Mode**: zoom, pan, annotate (with hover highlighting), erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions. A one-click **GPT transparency** button sends the current image through the i2i edit lane and reports honestly whether the result carries real pixel alpha — verified on the server, never trusted from provider metadata.
+- **Raster-to-vector SVG**: trace flat raster art into real SVG paths with `ima2 vectorize`, from AssetGen/Assets, or from Canvas Export. Canvas labels its older self-contained wrapper as **SVG (embedded raster)** so it cannot be mistaken for a trace.
+- **NovelAI dual prompt**: when NovelAI is selected, Classic, Home, and the mobile compose sheet show **Positive prompt** and **Undesired content** as peer panes; they stack below a 719px composer container. Other providers keep the normal single prompt.
+- **Prompt Builder backend choice**: Settings > Providers can keep Builder routing on **Auto** or pin a supported text backend and model, and the **via <backend>** badge shows which backend actually answered.
 - **Light & dark themes**: a token-based light mode with tinted neutrals and AA contrast, switchable between light / dark / system in Settings, with no flash on load.
 - **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
 - **Reference images**: drag, drop, paste, and attach up to 5 references (images) or up to 7 references (video); large images are compressed before upload.
@@ -172,9 +175,9 @@ Grok video generation defaults to canonical `grok-imagine-video-1.5`; `grok-imag
 
 ## Model Guidance
 
-The app defaults to **`gpt-5.6-luna`** for image generation and Prompt Builder planning. Older supported models remain explicit compatibility choices.
+Image generation defaults to **`gpt-5.6-luna`** on the GPT lane. Prompt Builder backend selection is separate: **Auto** chooses the first ready supported text backend, while Settings can pin one explicitly. The `via <backend>` badge reports the backend that actually answered.
 
-- `gpt-5.6-luna` — current image and Prompt Builder default.
+- `gpt-5.6-luna` — current default image model on the GPT lane and the default GPT Builder model when that backend is selected.
 - `gpt-5.6-terra` / `gpt-5.6-sol` — current GPT-5.6 alternatives when your account exposes them.
 - `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini` — supported compatibility choices.
 
@@ -187,6 +190,7 @@ The app also exposes quality (`low`, `medium`, `high`) and moderation (`auto`, `
 Use Classic when you want one strong result quickly.
 
 1. Write a prompt.
+   With NovelAI, use **Positive prompt** for desired content and **Undesired content** for what the image should avoid.
 2. Attach or paste references if needed.
 3. Pick model, quality, size, format, and moderation.
 4. Generate one image, or enable multimode to fan out several candidate slots from the same prompt.
@@ -214,6 +218,7 @@ Use Canvas Mode when a generated image is close but needs targeted cleanup befor
 - Use annotation, eraser, multiselect, grouping, undo/redo, and sticky notes while keeping the original gallery image available.
 - Pick background-cleanup seeds, preview the mask, and save the cleanup as a canvas version.
 - Detect transparent images and show a checkerboard preview; export with preserved alpha or with a chosen matte color.
+- Choose **SVG (embedded raster)** for a self-contained canvas document, or **Trace to SVG (vector)** to flatten the composition and open the shared real-vector tracing panel.
 - Saved canvas versions stay hidden from Gallery and HistoryStrip, but Canvas Mode can reuse them and attach a canvas version as the next reference.
 - Hover any annotation with the select tool to see a live outline and a move cursor before you click.
 - Press the **GPT transparency** button in the canvas toolbar to remove the background through the OAuth i2i lane in one click. The server decodes the returned bytes and reports `alphaVerified` — the toast tells you whether real transparency actually landed, instead of assuming.
@@ -237,6 +242,7 @@ be treated as a stable public feature yet.
 ### Settings
 
 The settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.
+Prompt Builder backend lives under Providers: Auto tries GPT OAuth, Grok, OpenAI API, then Grok API and uses the first ready lane. An explicit choice stays pinned and returns a typed error when unavailable; the Builder surface displays the backend that actually answered.
 Appearance now includes a light / dark / system theme toggle; the light palette uses tinted neutrals with AA contrast and applies before first paint.
 
 ![Settings workspace with account navigation and generation model controls.](assets/screenshots/settings-workspace.png)
@@ -270,6 +276,8 @@ These require a running `ima2 serve`. The CLI covers every server route. The mos
 | `ima2 defaults reset image\|video` | Remove a persisted CLI generation target |
 | `ima2 gen <prompt> [--model <lane>/<model>]` | Generate from the CLI; requires an explicit target or saved image default |
 | `ima2 edit <file> --prompt <text>` | Edit an existing image |
+| `ima2 vectorize <input.png> [-o output.svg]` | Trace PNG/JPEG/WebP into a real SVG locally; no server or provider required |
+| `ima2 prompt build --message <text> [--backend <backend>] [--model <model>]` | Refine prompt intent through the configured or explicitly selected Prompt Builder backend; requires the local server |
 | `ima2 multimode <prompt>` | Multi-image SSE generation |
 | `ima2 video <prompt> [--model <lane>/<model>]` | Generate video through a Grok or MCP lane; requires an explicit target or saved video default |
 | `ima2 ls [--session <id>] [--favorites]` | List recent history |
@@ -284,6 +292,9 @@ The server advertises its actual port at `~/.ima2/server.json`. If `3333` is bus
 ```bash
 ima2 models --kind image
 ima2 gen "poster" --model oauth/gpt-5.6-luna --reasoning-effort high
+ima2 gen "1girl, blue hair" --model nai/nai-diffusion-5-full --nai-negative-prompt "lowres, watermark"
+ima2 vectorize logo.png -o logo.svg --json
+ima2 prompt build --message "Make this prompt production-ready" --backend auto --model auto
 ima2 edit input.png --prompt "make it rainy" --web-search
 ima2 multimode "two cats playing" -n 2
 ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
@@ -312,6 +323,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_ADVERTISE_FILE` | `~/.ima2/server.json` | Runtime discovery file |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | Server fallback image model |
+| `IMA2_PROMPT_BUILDER_BACKEND` | `auto` | Prompt Builder text backend (`auto`, `oauth`, `grok`, `api`, or `grok-api`); Settings persists the same value as `promptBuilder.backend` |
+| `IMA2_PROMPT_BUILDER_MODEL` | `auto` with Auto backend | Backend-scoped Builder model; Settings persists the same value as `promptBuilder.model` |
 | `IMA2_REASONING_EFFORT` | `medium` | Default reasoning effort for the default (GPT OAuth) path; one of `none`, `low`, `medium`, `high`, `xhigh` |
 | `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |
 | `IMA2_LOG_LEVEL` | `info` | Normal serve defaults to `info`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
@@ -351,6 +364,7 @@ Use `ima2 serve --dev`, `npm run dev`, or `IMA2_LOG_LEVEL=debug ima2 serve` when
 ## API Reference
 
 The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay focused on first-run use.
+The relevant feature groups are `POST /api/assets/derived` with `kind=vector-svg`, NovelAI's `negativePrompt` generation field, `POST /api/prompt-builder/chat`, and `GET`/`PUT /api/prompt-builder/config`.
 
 Useful references:
 

package/bin/commands/prompt-sub/build.js

@@ -12,7 +12,8 @@ const BUILD_HELP = `
     --message <text>          User message (required unless --messages)
     --messages <file|@file|-> Multi-turn conversation as JSON array
     --ref <image>             Image reference (repeatable)
-    --model <model>           Builder model (gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
+    --backend <backend>       Backend override (auto, oauth, api, grok, grok-api)
+    --model <model>           Model for the configured Prompt Builder backend
     --language <ko|en|both>   Preferred output language hint
     --server <url>            Override server URL
     --json                    Output raw JSON
@@ -27,6 +28,7 @@ const FLAGS = {
     message: { type: "string" },
     messages: { type: "string" },
     ref: { type: "string", repeatable: true },
+    backend: { type: "string" },
     model: { type: "string" },
     language: { type: "string" },
     server: { type: "string" },
@@ -65,6 +67,8 @@ export default async function buildSub(argv) {
     }
     const messages = await resolveMessages(args);
     const body = { messages };
+    if (args.backend)
+        body.backend = args.backend;
     if (args.model)
         body.model = args.model;
     let server;

package/config.js

@@ -15,6 +15,7 @@ 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";
+import { DEFAULT_PROMPT_BUILDER_MODELS, PROMPT_BUILDER_BACKENDS, PROMPT_BUILDER_MODELS, } from "./lib/promptBuilder/constants.js";
 // 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";
@@ -80,6 +81,13 @@ function pickBool(envVal, fileVal, fallback) {
     const s = String(v).toLowerCase();
     return s === "1" || s === "true" || s === "yes";
 }
+function promptBuilderBackend(raw) {
+    return PROMPT_BUILDER_BACKENDS.includes(raw)
+        ? raw
+        : "auto";
+}
+const selectedPromptBuilderBackend = promptBuilderBackend(pickStr(env.IMA2_PROMPT_BUILDER_BACKEND, fileCfg.promptBuilder?.backend, "auto"));
+const selectedPromptBuilderModel = pickStr(env.IMA2_PROMPT_BUILDER_MODEL, fileCfg.promptBuilder?.model, DEFAULT_PROMPT_BUILDER_MODELS[selectedPromptBuilderBackend]);
 export function defaultLogLevelForEnv(runtimeEnv = env) {
     return runtimeEnv.IMA2_DEV === "1" ? "debug" : "info";
 }
@@ -135,6 +143,12 @@ export const config = {
             ? fileCfg.oauth.validModeration
             : ["auto", "low"]),
     },
+    promptBuilder: {
+        backend: selectedPromptBuilderBackend,
+        model: PROMPT_BUILDER_MODELS[selectedPromptBuilderBackend].includes(selectedPromptBuilderModel)
+            ? selectedPromptBuilderModel
+            : DEFAULT_PROMPT_BUILDER_MODELS[selectedPromptBuilderBackend],
+    },
     github: {
         token: pickStr(env.IMA2_GITHUB_TOKEN, fileCfg.github?.token, ""),
     },

package/docs/API.md

@@ -810,6 +810,26 @@ Agent Mode is a conversational image workspace (web UI only — no CLI). All rou
 | `POST` | `/api/agent/queue/:itemId/cancel` | Cancel queued item |
 | `POST` | `/api/agent/queue/:itemId/retry` | Retry failed item |
 
+## Prompt Builder
+
+| Method | Path | Body | Response |
+|---|---|---|---|
+| `POST` | `/api/prompt-builder/chat` | `{ messages, backend?, model?, context? }` | `{ provider, backend, requestedBackend, model, message, usage }` |
+| `GET` | `/api/prompt-builder/config` | none | `{ backend, model, options: { backends, models, autoOrder }, locked }` |
+| `PUT` | `/api/prompt-builder/config` | `{ backend, model? }` | Same config payload after atomic persistence |
+
+The persisted keys are `promptBuilder.backend` and `promptBuilder.model`; the corresponding
+environment locks are `IMA2_PROMPT_BUILDER_BACKEND` and `IMA2_PROMPT_BUILDER_MODEL`.
+`backend=auto` tries `oauth -> grok -> api -> grok-api` and selects the first ready lane.
+An explicit backend stays pinned and never falls back. Chat responses separate
+`requestedBackend` from the answering `backend`, which the UI renders as `via <backend>`.
+
+Invalid backend/model pairs return typed 400 errors. An unavailable explicit lane returns its
+typed 401/503 error, no ready Auto lane returns 503 `PROMPT_BUILDER_NO_BACKEND_READY`, and
+environment-locked config writes return 409 `PROMPT_BUILDER_CONFIG_ENV_LOCKED`. Auto selection
+happens before sending upstream; an accepted or failed upstream request is not retried on another
+backend.
+
 ## Endpoint → CLI Mapping
 
 Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent Mode** (`/api/agent/*`), which is server + web-UI-only and has no `ima2` subcommand. The prompt builder HTTP route (`POST /api/prompt-builder/chat`) is wrapped by `ima2 prompt build`. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
@@ -862,6 +882,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `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) |
 | `POST /api/prompt-builder/chat` | `ima2 prompt build` |
+| `GET/PUT /api/prompt-builder/config` | Web UI only (Settings > Providers > Prompt Builder backend / Builder model) |
 
 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.

package/docs/CLI.md

@@ -365,6 +365,13 @@ Windows DNS/fragmentation bypass tool such as SecretDNS is in use.
 | `ima2 prompt build --message <text> [--ref <file>] [--model <id>] [--json]` | Build a structured image prompt through `/api/prompt-builder/chat` |
 | `ima2 prompt build --messages <file\|@file\|-> [--json]` | Build from a message transcript file or stdin |
 
+Prompt Builder uses the server's persisted `promptBuilder.backend` preference unless
+`--backend <auto|oauth|api|grok|grok-api>` overrides it for one request. `auto`
+chooses the first ready supported text backend (oauth, grok, api, grok-api); an explicit
+value pins routing and fails with a typed error instead of falling back. The result
+identifies `requestedBackend`, the answering `backend`, and `model`, so callers can
+detect an Auto fallback.
+
 ## Card News (gated)
 
 Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `features.cardNews: true` in `~/.ima2/config.json`). When disabled, the CLI exits 2 with a clear message instead of producing a 404.

package/docs/PROMPT_STUDIO.md

@@ -21,6 +21,15 @@ you want a reproducible way to report a workspace issue.
 | 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. |
 
+### Provider-specific prompt surfaces
+
+NovelAI shows Positive prompt and Undesired content as separate panes in Classic, Home,
+and the mobile compose sheet (side by side when the composer is wider than 719px,
+stacked otherwise). Switching away from NovelAI restores the single prompt without
+deleting the saved undesired-content text. Prompt Builder routing is configured in
+Settings > Providers; the Builder badge shows the backend that actually answered,
+including an Auto selection or fallback.
+
 ## Multimode Prompting
 
 Multimode repeats one generation request shape across several candidate slots.

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: 412 (runtime: 191, contract: 221)
+Total: 415 (runtime: 191, contract: 224)
 
 ## Runtime-importing tests
 - `tests/agent-image-reference-contract.test.ts`
@@ -251,6 +251,7 @@ Total: 412 (runtime: 191, contract: 221)
 - `tests/canvas-selection-contract.test.js`
 - `tests/canvas-style-contract.test.js`
 - `tests/canvas-svg-export-contract.test.ts`
+- `tests/canvas-vectorize-entry-contract.test.ts`
 - `tests/canvas-version-api.test.js`
 - `tests/canvas-version-contract.test.js`
 - `tests/canvas-viewport-pan-contract.test.js`
@@ -337,6 +338,7 @@ Total: 412 (runtime: 191, contract: 221)
 - `tests/multimode-concurrent-store-contract.test.js`
 - `tests/multimode-ui-contract.test.js`
 - `tests/nai-cli-built-smoke.test.ts`
+- `tests/nai-dual-prompt-contract.test.ts`
 - `tests/nai-ui-registration-contract.test.ts`
 - `tests/navrail-hover-label-contract.test.ts`
 - `tests/node-async-eventbus-contract.test.js`
@@ -397,6 +399,7 @@ Total: 412 (runtime: 191, contract: 221)
 - `tests/star-surface-controls-contract.test.ts`
 - `tests/storage-open-generated-dir.test.js`
 - `tests/structure-line-counts-contract.test.js`
+- `tests/studio-surface-docs-contract.test.ts`
 - `tests/style-feature-removal-contract.test.js`
 - `tests/subprocess-deadline-contract.test.ts`
 - `tests/toast-stack-contract.test.js`

package/lib/configFileStore.js

@@ -0,0 +1,44 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+let configMutationQueue = Promise.resolve();
+function serializeConfigMutation(mutation) {
+    const result = configMutationQueue.then(mutation, mutation);
+    configMutationQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+async function writeConfigAtomic(cfgPath, data) {
+    const tmp = `${cfgPath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        await mkdir(dirname(cfgPath), { recursive: true, mode: 0o700 });
+        await writeFile(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+        await rename(tmp, cfgPath);
+    }
+    catch (error) {
+        throw error;
+    }
+}
+export async function updateConfigFileAtomic(cfgPath, mutate) {
+    try {
+        await serializeConfigMutation(async () => {
+            let existing = {};
+            try {
+                existing = JSON.parse(await readFile(cfgPath, "utf8"));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "ENOENT") {
+                    throw Object.assign(new Error(`config file unreadable: ${cfgPath}`), {
+                        code: "CONFIG_UNREADABLE",
+                        cause: error,
+                    });
+                }
+            }
+            mutate(existing);
+            await writeConfigAtomic(cfgPath, existing);
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+}

package/lib/configKeys.js

@@ -1,5 +1,7 @@
 export const AUTH_CONFIG_KEYS = new Set(["provider", "apiKey"]);
 export const WRITABLE_CONFIG_KEYS = new Set([
+    "promptBuilder.backend",
+    "promptBuilder.model",
     "imageModels.default",
     "imageModels.reasoningEffort",
     "apiProvider.defaultImageModel",
@@ -37,6 +39,8 @@ export const WRITABLE_CONFIG_KEYS = new Set([
     "history.maxPageCap",
 ]);
 export const KEY_TO_ENV = {
+    "promptBuilder.backend": "IMA2_PROMPT_BUILDER_BACKEND",
+    "promptBuilder.model": "IMA2_PROMPT_BUILDER_MODEL",
     "imageModels.default": "IMA2_IMAGE_MODEL_DEFAULT",
     "imageModels.reasoningEffort": "IMA2_REASONING_EFFORT",
     "apiProvider.defaultImageModel": "IMA2_API_IMAGE_MODEL_DEFAULT",

package/lib/promptBuilder/client.js

@@ -1,76 +1,118 @@
 import { errInfo } from "../errInfo.js";
-import { logWarn } from "../logger.js";
-import { fetchOAuth, waitForOAuthReady } from "../oauthProxy/runtime.js";
+import { logEvent, logWarn } from "../logger.js";
+import { fetchOAuth } from "../oauthProxy/runtime.js";
+import { requireRuntimeContext, } from "../runtimeContext.js";
+import { DEFAULT_PROMPT_BUILDER_MODELS, PROMPT_BUILDER_AUTO_ORDER, } from "./constants.js";
 import { promptBuilderError } from "./errors.js";
-import { normalizeModel, normalizeMessages } from "./requestSchema.js";
+import { lanesForModel, normalizeMessages, normalizePromptBuilderBackend, normalizeRequestModel, } from "./requestSchema.js";
+import { resolvePromptBuilderTransport, selectPromptBuilderBackend, } from "./router.js";
 import { buildTransportPayload } from "./transport.js";
 import { parseUpstreamError, responseSummary, extractChatText, readResponsesResult, } from "./responseParser.js";
-export async function requestPromptBuilderChat(ctx, input) {
-    const model = normalizeModel(input.model);
+async function prepareRequest(ctx, input, lanes) {
+    const persistedBackend = normalizePromptBuilderBackend(ctx.config.promptBuilder.backend);
+    const requestedBackend = normalizePromptBuilderBackend(input.backend, persistedBackend);
+    const backendOverridden = requestedBackend !== persistedBackend;
+    const requestedModel = normalizeRequestModel(requestedBackend, input.model ?? (backendOverridden
+        ? DEFAULT_PROMPT_BUILDER_MODELS[requestedBackend]
+        : ctx.config.promptBuilder.model));
+    const allowedLanes = requestedBackend === "auto" && requestedModel !== "auto"
+        ? lanesForModel(requestedModel)
+        : PROMPT_BUILDER_AUTO_ORDER;
+    const selection = selectPromptBuilderBackend(requestedBackend, lanes, allowedLanes);
+    const model = requestedBackend === "auto"
+        ? (requestedModel === "auto" ? DEFAULT_PROMPT_BUILDER_MODELS[selection.backend] : requestedModel)
+        : requestedModel;
     const messages = normalizeMessages(input.messages);
-    await waitForOAuthReady(ctx);
-    const timeoutMs = ctx.config?.oauth?.generationTimeoutMs ?? 120_000;
+    if (selection.fallbackFrom)
+        logFallback(selection);
+    const payload = buildTransportPayload(selection.backend, model, messages, input.context);
+    const target = await resolvePromptBuilderTransport(ctx, selection.backend, payload.endpoint);
+    return { selection, model, payload, target };
+}
+function logFallback(selection) {
+    logEvent("prompt-builder", "backend_fallback", {
+        requestedBackend: selection.requestedBackend,
+        from: selection.fallbackFrom,
+        to: selection.backend,
+        reason: selection.fallbackReason,
+    });
+}
+function sendUpstream(prepared, signal) {
+    const init = {
+        method: "POST",
+        headers: prepared.target.headers,
+        signal,
+        body: JSON.stringify(prepared.payload.body),
+    };
+    return prepared.target.useOAuthFetch
+        ? fetchOAuth(prepared.target.url, init, { scope: "prompt-builder" })
+        : fetch(prepared.target.url, init);
+}
+async function throwUpstreamFailure(res, prepared) {
+    const text = await res.text();
+    const upstream = parseUpstreamError(text);
+    logWarn("prompt-builder", "upstream_failed", {
+        endpoint: prepared.payload.endpoint,
+        model: prepared.model,
+        status: res.status,
+        hasImageAttachments: prepared.payload.endpoint === "responses",
+        upstreamBodyChars: text.length,
+        upstreamCode: upstream.upstreamCode,
+        upstreamType: upstream.upstreamType,
+        upstreamParam: upstream.upstreamParam,
+    });
+    const err = promptBuilderError("Prompt builder upstream failed", "PROMPT_BUILDER_UPSTREAM_FAILED", 502);
+    Object.assign(err, {
+        upstreamStatus: res.status,
+        upstreamBodyChars: text.length,
+        upstreamEndpoint: prepared.payload.endpoint,
+        ...upstream,
+    });
+    throw err;
+}
+async function parseResponse(res, endpoint) {
+    if (endpoint === "responses") {
+        return readResponsesResult(res);
+    }
+    const body = (await res.json());
+    return {
+        content: extractChatText(body),
+        usage: body.usage ?? null,
+        summary: responseSummary(body),
+    };
+}
+function requireContent(parsed, prepared) {
+    const content = parsed.content.trim();
+    if (content)
+        return content;
+    logWarn("prompt-builder", "empty_response", {
+        endpoint: prepared.payload.endpoint,
+        model: prepared.model,
+        ...parsed.summary,
+    });
+    const err = promptBuilderError("Prompt builder returned an empty response", "PROMPT_BUILDER_EMPTY_RESPONSE", 502);
+    err.upstreamEndpoint = prepared.payload.endpoint;
+    Object.assign(err, parsed.summary);
+    throw err;
+}
+export async function requestPromptBuilderChat(ctxRaw, input, lanes) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    const prepared = await prepareRequest(ctx, input, lanes);
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => controller.abort(), ctx.config.oauth.generationTimeoutMs);
     try {
-        const { endpoint, body: payload } = buildTransportPayload(model, messages, input.context);
-        const url = `${ctx.oauthUrl}${endpoint === "responses" ? "/v1/responses" : "/v1/chat/completions"}`;
-        const res = await fetchOAuth(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            signal: controller.signal,
-            body: JSON.stringify(payload),
-        }, { scope: "prompt-builder" });
-        if (!res.ok) {
-            const text = await res.text();
-            const upstream = parseUpstreamError(text);
-            logWarn("prompt-builder", "upstream_failed", {
-                endpoint,
-                model,
-                status: res.status,
-                hasImageAttachments: endpoint === "responses",
-                upstreamBodyChars: text.length,
-                upstreamCode: upstream.upstreamCode,
-                upstreamType: upstream.upstreamType,
-                upstreamParam: upstream.upstreamParam,
-            });
-            const err = promptBuilderError("Prompt builder upstream failed", "PROMPT_BUILDER_UPSTREAM_FAILED", 502);
-            err.upstreamStatus = res.status;
-            err.upstreamBodyChars = text.length;
-            err.upstreamEndpoint = endpoint;
-            err.upstreamCode = upstream.upstreamCode;
-            err.upstreamType = upstream.upstreamType;
-            err.upstreamParam = upstream.upstreamParam;
-            throw err;
-        }
-        const useResponses = endpoint === "responses";
-        const responseBody = useResponses
-            ? await readResponsesResult(res)
-            : (await res.json());
-        const content = (useResponses
-            ? responseBody.content
-            : extractChatText(responseBody)).trim();
-        if (!content) {
-            const summary = useResponses
-                ? responseBody.summary
-                : responseSummary(responseBody);
-            logWarn("prompt-builder", "empty_response", {
-                endpoint,
-                model,
-                ...summary,
-            });
-            const err = promptBuilderError("Prompt builder returned an empty response", "PROMPT_BUILDER_EMPTY_RESPONSE", 502);
-            err.upstreamEndpoint = endpoint;
-            Object.assign(err, summary);
-            throw err;
-        }
+        const res = await sendUpstream(prepared, controller.signal);
+        if (!res.ok)
+            await throwUpstreamFailure(res, prepared);
+        const parsed = await parseResponse(res, prepared.payload.endpoint);
+        const content = requireContent(parsed, prepared);
         return {
-            provider: "oauth",
-            model,
+            provider: prepared.selection.backend,
+            backend: prepared.selection.backend,
+            requestedBackend: prepared.selection.requestedBackend,
+            model: prepared.model,
             message: { role: "assistant", content },
-            usage: useResponses
-                ? responseBody.usage
-                : (responseBody.usage ?? null),
+            usage: parsed.usage,
         };
     }
     catch (error) {

package/lib/promptBuilder/constants.js

@@ -1,5 +1,23 @@
-export const VALID_PROMPT_BUILDER_MODELS = new Set(["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"]);
-export const DEFAULT_PROMPT_BUILDER_MODEL = "gpt-5.6-luna";
+export const PROMPT_BUILDER_BACKENDS = ["auto", "oauth", "grok", "api", "grok-api"];
+const GPT_MODELS = ["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"];
+const grokModels = ["grok-4.3", "grok-4.6", "grok-4.5"];
+export const PROMPT_BUILDER_MODELS = {
+    auto: ["auto"],
+    oauth: GPT_MODELS,
+    grok: grokModels,
+    api: GPT_MODELS,
+    "grok-api": grokModels,
+};
+export const DEFAULT_PROMPT_BUILDER_MODELS = {
+    auto: "auto",
+    oauth: "gpt-5.6-luna",
+    grok: "grok-4.3",
+    api: "gpt-5.6-luna",
+    "grok-api": "grok-4.3",
+};
+export const PROMPT_BUILDER_AUTO_ORDER = [
+    "oauth", "grok", "api", "grok-api",
+];
 export const MAX_MESSAGES = 24;
 export const MAX_MESSAGE_CHARS = 16_000;
 export const MAX_ATTACHMENTS = 6;

package/lib/promptBuilder/requestSchema.js

@@ -1,13 +1,48 @@
-import { VALID_PROMPT_BUILDER_MODELS, DEFAULT_PROMPT_BUILDER_MODEL, MAX_MESSAGES, MAX_MESSAGE_CHARS, } from "./constants.js";
+import { DEFAULT_PROMPT_BUILDER_MODELS, MAX_MESSAGES, MAX_MESSAGE_CHARS, PROMPT_BUILDER_AUTO_ORDER, PROMPT_BUILDER_BACKENDS, PROMPT_BUILDER_MODELS, } from "./constants.js";
 import { promptBuilderError } from "./errors.js";
 import { normalizeAttachments } from "./attachments.js";
-export function normalizeModel(raw) {
-    if (typeof raw !== "string" || raw.trim().length === 0)
-        return DEFAULT_PROMPT_BUILDER_MODEL;
-    if (!VALID_PROMPT_BUILDER_MODELS.has(raw)) {
-        throw promptBuilderError(`model must be one of: ${[...VALID_PROMPT_BUILDER_MODELS].join(", ")}`, "PROMPT_BUILDER_BAD_MODEL");
+export function normalizePromptBuilderBackend(raw, fallback = "auto") {
+    if (raw === undefined || raw === null)
+        return fallback;
+    if (typeof raw === "string") {
+        const candidate = raw.trim();
+        if (!candidate)
+            return fallback;
+        if (PROMPT_BUILDER_BACKENDS.includes(candidate)) {
+            return candidate;
+        }
+    }
+    throw promptBuilderError(`backend must be one of: ${PROMPT_BUILDER_BACKENDS.join(", ")}`, "PROMPT_BUILDER_BAD_BACKEND");
+}
+export function normalizePromptBuilderModel(backend, raw) {
+    const candidate = typeof raw === "string" && raw.trim()
+        ? raw.trim()
+        : DEFAULT_PROMPT_BUILDER_MODELS[backend];
+    if (!PROMPT_BUILDER_MODELS[backend].includes(candidate)) {
+        throw promptBuilderError(`model for ${backend} must be one of: ${PROMPT_BUILDER_MODELS[backend].join(", ")}`, "PROMPT_BUILDER_BAD_MODEL");
+    }
+    return candidate;
+}
+export function normalizeRequestModel(backend, raw) {
+    const candidate = typeof raw === "string" && raw.trim() ? raw.trim() : "";
+    if (backend === "auto" && candidate && candidate !== "auto") {
+        if (!lanesForModel(candidate).length) {
+            throw promptBuilderError(`model ${candidate} is not in any Prompt Builder catalog`, "PROMPT_BUILDER_BAD_MODEL");
+        }
+        return candidate;
     }
-    return raw;
+    return normalizePromptBuilderModel(backend, candidate || undefined);
+}
+export function lanesForModel(model) {
+    return PROMPT_BUILDER_AUTO_ORDER.filter((lane) => PROMPT_BUILDER_MODELS[lane].includes(model));
+}
+export function normalizePromptBuilderConfig(raw, current) {
+    const body = raw && typeof raw === "object" ? raw : {};
+    const backend = normalizePromptBuilderBackend(body.backend, current.backend);
+    const modelInput = body.model === undefined && backend !== current.backend
+        ? DEFAULT_PROMPT_BUILDER_MODELS[backend]
+        : body.model ?? current.model;
+    return { backend, model: normalizePromptBuilderModel(backend, modelInput) };
 }
 export function normalizeMessages(raw) {
     if (!Array.isArray(raw)) {