@cartanova/qgrid-cli 2.10.5 → 2.10.7

package/skills/qgrid/references/ai-sdk-provider-contract.md

@@ -6,13 +6,26 @@ Use this reference before changing `packages/ai-sdk`.
 
 `packages/ai-sdk` is the active public SDK package. The old v1 SDK (`@cartanova/qgrid-sdk`) has been removed from the repository.
 
-qgrid's custom provider implements the AI SDK `LanguageModelV3` contract. General usage should follow the AI SDK docs and normal AI SDK APIs such as `generateText`, `streamText`, tools, structured output, and telemetry. Do not re-document generic AI SDK usage in qgrid-specific docs unless the behavior differs. qgrid docs and this skill should focus on qgrid-specific config, `providerOptions.qgrid`, request logging, runtime routing, cache/session behavior, and provider limitations.
+qgrid's custom provider implements `LanguageModelV3` through `qgrid()` and `ImageModelV3` through `qgrid.image()`. General usage should follow the AI SDK docs and normal AI SDK APIs such as `generateText`, `streamText`, `generateImage`, tools, structured output, and telemetry. Do not re-document generic AI SDK usage in qgrid-specific docs unless the behavior differs. qgrid docs and this skill should focus on qgrid-specific config, `providerOptions.qgrid`, request logging, runtime routing, cache/session behavior, and provider limitations.
+
+## Explicit image model
+
+Use `generateImage({ model: qgrid.image("openai/gpt-image-2"), prompt })` for explicit image generation. The image factory returns `ImageModelV3`, accepts `serverUrl` and `projectName`, and sends the existing query endpoint `model: "openai/gpt-image-2", imageGeneration: true`. These image-generation fields are internal wire inputs, not public language-model options. The server calls subscription Codex Images directly, without a chat driver. `qgrid()` / `generateText` handles text, tools, and structured output. Dashboard auto-image mode registers an internal `generate_image` function, which calls the same subscription Images endpoints for ordinary or transparent output after the chat model chooses a prompt and references. Do not add a public SDK image-tool factory.
+
+Reference editing uses AI SDK `prompt: { text, images }`, with up to five references. Omitted references use `images/generations`; supplied references use `images/edits`. The new direct interface returns PNG only; unsupported output formats and masks fail before generation. `n` is handled through AI SDK batching with `maxImagesPerCall: 1`; callers cannot override this to send a multi-image backend request. `seed` and `aspectRatio` produce unsupported warnings. Size and quality are hints, never exact-output guarantees; prompt for the intended ratio and preserve observed settings.
+
+`gpt-image-2` is the Codex wire request identifier, not proof that the serving weights are Images 2.0. OpenAI announced Images 2.5 in Codex; private-route probes accepted even nonexistent model IDs, so Flare/Sunburst selection is not established. Standalone metadata preserves a reported model, otherwise it falls back to the requested identifier. Do not describe that fallback as an observed serving version. GPT Image 2 and 2.5 have the same published token rates; per-image fallback prices remain GPT Image 2 estimates when usage is absent.
+
+Use `QgridImageProviderOptions` with `satisfies` on `providerOptions.qgrid`. Options are flat: `quality`, `background`, `outputFormat: "png"`, `tokenName`, and `logger`. Standard `size` belongs at the `generateImage` top level. Do not send chat effort, thinking, tools, or structured output to the image model.
+
+Map image response usage into standard `generateImage().usage`. Preserve per-image generation metadata and request-log IDs under `providerMetadata.qgrid.images[]`: AI SDK 6 merges that array and discards arbitrary provider-level keys. The raw query's top-level usage/cost remain zero chat-driver accounting; server logs price the separate image usage using the existing API-price estimator. Do not duplicate image price calculation in the SDK or count aggregate usage once per output. Without reported image usage, keep standard usage unknown and preserve the server's existing per-image cost fallback. `logger: false`, token targeting, project labeling, and cancellation still apply.
 
 For tool calling, qgrid intentionally follows the AI SDK interface while implementing provider calls through qgrid structured-output emulation. Read `tool-calling-and-multiturn.md` before changing tool behavior, `stopWhen`/multi-step behavior, or tool-call request logs.
 
 Main files:
 
 - `packages/ai-sdk/src/index.ts`: `qgrid()` provider implementation.
+- `packages/ai-sdk/src/image-model.ts`: `qgrid.image()` provider implementation.
 - `packages/ai-sdk/src/index.types.ts`: public config/options/types.
 - `packages/ai-sdk/src/utils.ts`: prompt/history/tool conversion.
 - `packages/ai-sdk/src/logger.ts`: telemetry logger integration.
@@ -55,7 +68,7 @@ const result = await generateText({
 
 Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the exported type describes the nested qgrid options object, not AI SDK's outer provider-name map. Use this typed pattern in qgrid setup guidance and examples so misspelled keys and invalid option values fail at compile time.
 
-`providerOptions.qgrid` supports:
+Language-model `providerOptions.qgrid` supports:
 
 - `tokenName`: strict active-token targeting for both providers. Include the provider prefix and
   match it to the model (`anthropic/yds` with `anthropic/*`, for example). Missing, inactive, or
@@ -70,8 +83,8 @@ Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the expo
 - `serviceTier`: OpenAI/Codex route only.
 - `timeoutMs`: Anthropic server-side Claude Code process timeout in milliseconds. It must be a positive integer no greater than 30 minutes and defaults to 240 seconds. For non-stream `generateText`, the SDK derives request-scoped Undici `headersTimeout` and `bodyTimeout` values as `timeoutMs + 60_000` without changing the process-global dispatcher.
 - `fallbackModels`: deprecated, ignored compatibility field. The provider emits a standard unsupported-option warning when supplied; remove it from callers. It is not Claude Code's upstream Fable safety-refusal fallback.
-- `imageGeneration`: OpenAI/Codex non-stream only. Enables Codex's built-in `image_generation` tool for that request.
-- `imageGenerationOptions`: optional `quality: "low" | "medium" | "high"`, `size` (`auto` or positive-integer `WIDTHxHEIGHT`), and `background: "auto" | "opaque" | "transparent"`. Transparent requests use Codex standalone Images with `gpt-image-2`; other requests use the hosted Responses tool. Transparent mode rejects tools/structured output, supports up to five references, validates real transparent and visible PNG pixels, and never invokes background-removal fallback. Size is a positive-integer WIDTHxHEIGHT hint, not an exact-output guarantee; omit it or use auto and put the desired aspect ratio in the prompt. Do not impose public Images API 16-pixel/4K rules on the private subscription route. Both routes expose observations (`codex-responses` or `codex-images`); hosted model is optional. PNG dimensions come from bytes; JPEG/WebP size comes from backend metadata. Hosted image cost is null, and arbitrary/auto size hints never receive a made-up price-table estimate. Returned size/quality may differ from requested settings; read `result.providerMetadata.qgrid.imageGeneration` or per-file `result.content` metadata. `result.files[]` contains bytes/mediaType only. Logs separate `requestedOptions` from `observedGeneration`; image usage is separate from the zero text-driver usage on this route.
+
+`imageGeneration` and `imageGenerationOptions` are not public SDK options. Language-model generation and streaming reject either key before transport, directing callers to `generateImage` with `qgrid.image()`. Use flat `QgridImageProviderOptions`; do not add deprecated language-model shims for the removed fields.
 
 `providerOptions.qgrid` does not currently support `projectName` or `project_name`. Prefer `QGRID_PROJECT_NAME` for the default project label; use config `projectName` only when a caller needs to override that default.
 
@@ -131,15 +144,16 @@ const result = await generateText({
 Fast mode contract:
 
 - It is OpenAI/Codex-only. Do not send it to `anthropic/*` models.
-- It works on both `generateText` and `streamText`; image generation remains non-stream for unrelated reasons.
+- It works on both `generateText` and `streamText`; it is not an image-model option.
 - Omit `serviceTier` for normal/default routing. qgrid's current API accepts `"fast"` and `"flex"`; callers should not send Codex's normalized `"priority"` value directly.
-- qgrid is a pass-through for this selection. Codex applies the tier only when its Fast mode feature is enabled and the selected model advertises support; otherwise Codex can omit the unsupported tier.
+- qgrid forwards this selection to the subscription backend; sending it does not by itself prove the upstream serving tier. Do not assume that public API Flex discounts or availability apply to the subscription route. Omitting `serviceTier` does not select `flex`.
 - Fast mode changes upstream service-tier routing only. It does not change token weights or client concurrency.
 - Do not promise a fixed latency improvement. Verify TTFT, duration, throughput, and quota consumption with a workload-specific A/B test.
+- Since 2.10.7, native request logs retain the requested tier and show fast requests with a filled blue lightning icon. New OpenAI query/stream costs use the verified Fast API rates for supported current models. See `request-log-run-lifecycle.md` and `prompt-cache-and-usage.md` for storage and pricing semantics.
 
 ## Request construction
 
-The provider sends `POST /api/qgrid/query` for generate and `prepareStream` plus SSE for stream.
+The language provider sends `POST /api/qgrid/query` for generate and `prepareStream` plus SSE for stream.
 
 Payload responsibilities:
 
@@ -153,9 +167,8 @@ Payload responsibilities:
 - Preserve and resend `runContext` for tool-call follow-ups.
 - Let the server infer single-turn completion versus an open tool-call run. Logging-disabled tool calls still use the SDK's local pending-call correlation and continue without a request-log id.
 - Derive/store/resend opaque OpenAI affinity coordinates by `sessionKey`.
-- Send `imageGeneration` and `imageGenerationOptions` when configured.
-- Send AI SDK multimodal image/file message parts as qgrid `input` only when `imageGeneration` is enabled. Normal non-image-generation calls keep `user_prompt` text-only and do not forward image input.
-- Reject oversized reference-image data URLs before the request leaves the SDK. Reference images travel as JSON data URLs; callers should compress/resize large photos, preferably to WebP/JPEG.
+- Keep language-model prompts text-only. Ignore image parts with an unsupported warning; this adapter does not support general vision.
+- The separate image provider converts `generateImage` prompt references to qgrid `input` and rejects oversized inline reference images before transport. Callers should compress/resize large reference photos, preferably to WebP/JPEG.
 
 Tools and `jsonSchema` can be used together as of qgrid 2.5.4. On OpenAI the
 server composes them into one strict action envelope enforced by constrained
@@ -194,9 +207,7 @@ rejected.
 
 When tools are present, qgrid sends tool definitions to the server as `tools`; it does not send them to OpenAI or Anthropic as native provider tools. The server converts them into a strict structured-output schema and maps the model's structured result back into AI SDK `tool-call` content.
 
-Image generation is different from AI SDK client tools: it is an opt-in Codex-hosted tool exposed by qgrid through `providerOptions.qgrid.imageGeneration`. Use `generateText`; `streamText` rejects image generation before opening the stream.
-
-Reference images for image generation use normal AI SDK multimodal message parts. The provider wraps image/file base64 as `data:${mediaType};base64,...` qgrid `input` items. This is intentionally scoped to image-generation requests, not general vision/chat behavior.
+SDK image generation uses `ImageModelV3`, independently of AI SDK language-model tools. Pass references through `generateImage`'s `prompt: { text, images }`; the image provider wraps inline image bytes as data URLs and accepts HTTPS reference URLs. This supports image generation/editing, not general vision chat. Raw/server image flags remain available for dashboard chat and internal routing; they are not part of `QgridProviderOptions`.
 
 ## Response mapping
 
@@ -206,13 +217,12 @@ Since 2.10.0, `generateText` exposes the parent request-log ID at `result.provid
 
 Update both server and SDK to use this metadata. The field is omitted when logging is disabled or an older server does not return it. Tool-run steps share the parent ID; `runContext.requestLogId` remains separate continuation state. This does not expose external-provider telemetry logger IDs or add IDs to stream delta/error events.
 
-qgrid response content maps to AI SDK content:
+Language-model response content maps to AI SDK content:
 
 - qgrid `text` -> AI SDK text content.
 - qgrid `tool-call` -> AI SDK tool-call content.
-- qgrid `image` -> AI SDK file content with the returned `mediaType` (`image/png`, `image/jpeg`, or `image/webp`). Older responses without `mediaType` retain the PNG default.
 
-`imageGenerationOptions.outputFormat` accepts `png | jpeg | webp` for the hosted Responses route and maps to `image_generation.output_format`. Omission retains PNG. The standalone transparent route only supports PNG; a transparent request with JPEG/WebP is rejected before generation. Preserve the returned MIME type through response content, SDK file parts, and request-log image data URLs.
+The image provider maps direct Images output to standard AI SDK `image`/`images` and image `usage`, preserving generation metadata under `providerMetadata.qgrid.images[]`. It supports PNG output only. Raw/server hosted Responses output can be PNG/JPEG/WebP; preserve its actual MIME type in raw content and request-log data URLs.
 
 `finishReason` maps `tool-calls` when qgrid returns tool calls.
 
@@ -220,7 +230,7 @@ For tools plus structured output, qgrid serializes the final schema-constrained
 `answer` as JSON text. AI SDK then parses and validates that text into
 `Output.object`'s `output`. This path requires both server and SDK 2.5.4 or later.
 
-When `imageGeneration` was requested and the server returns no image part, the AI SDK provider throws a version-skew/error guard instead of silently accepting text-only output.
+The image provider requires exactly one output from route `codex-images` per call and rejects text-only, hosted-route, or multiple-image responses with a server/SDK version-skew guard.
 
 For a successful Fable refusal fallback (Fable 5 or 5.1):
 

package/skills/qgrid/references/decision-rationale.md

@@ -231,20 +231,20 @@ Sources:
 
 Key decisions:
 
-- Image generation is OpenAI/Codex-only and request-level opt-in outside dashboard chat. In 2.9.8, chat explicitly opts into raw `imageGeneration: "auto"` each turn. Most requests use the Codex-hosted `image_generation` tool. Transparent backgrounds use Codex standalone Images because the hosted route rejected them in live probes. Do not globally enable image tools for other callers: that would change their tool framing and cache behavior.
+- Image generation is OpenAI/Codex-only and request-level opt-in outside dashboard chat. Chat explicitly opts into raw `imageGeneration: "auto"` each turn. Auto mode registers one internal `generate_image` function and calls standalone Images for ordinary and transparent backgrounds. Raw explicit chat-model `imageGeneration: true` retains its hosted route for non-transparent images. Public SDK image requests use `qgrid.image()` / `generateImage` and standalone Images for any background, following AI SDK's separate `ImageModelV3` contract. The language-model SDK has no image-generation options; the former boolean and nested options are removed without deprecated shims. Do not add a public image-tool factory or globally enable image tools for other callers: that would change their tool framing and cache behavior.
 - It is non-stream only. Codex returns completed base64 image payloads, not useful image deltas.
 - Image turns send full input directly and retain no provider conversation state. This prevents base64 payloads from entering reusable state.
-- qgrid performs preflight capability/model gates. Explicit `imageGeneration: true` requires an image; `"auto"` allows normal text replies but still rejects attempted image generation without a completed image. The public AI SDK retains its boolean option and image-required contract.
-- Returned images are inline base64 content parts for consumers and AI SDK `file` parts. Reference images are accepted through AI SDK multimodal message parts only on the `imageGeneration` path, and are transported as JSON data URLs with SDK-side size guarding.
-- `imageGenerationOptions` supports quality, size, and background. Size accepts `auto` or positive-integer `WIDTHxHEIGHT` hints; the subscription backend can ignore them. Put desired ratios in the prompt, report observed output settings, and never silently resize. Hosted image cost is unknown because image usage/model are not reliably exposed. Only legacy responses without observations retain known three-size pricing assumptions. Transparent-route image usage is priced separately, and no background-removal fallback is allowed.
+- qgrid performs preflight capability/model gates. Raw `imageGeneration: true` requires an image; `"auto"` allows normal text replies but still rejects attempted image generation without a completed image. Public `generateImage` requires one direct Images output per provider call; AI SDK batches requests for `n` outputs.
+- Raw returned images are inline base64 content parts. The image SDK maps them to AI SDK `image`/`images` and takes references through standard `prompt: { text, images }`, with JSON data URL size guarding and HTTPS reference URL support. The language SDK ignores image parts with a warning and does not implement general vision.
+- Raw/server `imageGenerationOptions` supports quality, size, and background. The public image SDK uses flat `QgridImageProviderOptions` and standard top-level `size`. The subscription backend can ignore size and quality hints. Put desired ratios in the prompt, report observed output settings, and never silently resize. Reported image usage is priced at public token rates; without it, use the requested quality/size table with a default-size price for auto/custom hints. Preserve observed settings separately from pricing assumptions. No background-removal fallback is allowed.
 - qgrid does not manage generated or reference images as durable assets through a `generated_images` table or object-storage layer. Current request logs can still contain inline image data URLs for inspection and synthetic `image_generation` tool-call steps; reference input images live in the first synthetic step's `tool_args.inputImages`.
-- Image cost is stored separately in `request_logs.image_cost_usd`; `request_logs.cost_usd` remains the Codex driver model token cost. Hosted image cost is unknown (`null`). Standalone image costs are public-price estimates from reported image usage. Only legacy responses without observations and with known size prices retain size-table estimates. List rows and filtered totals mark known subtotals when image costs are unknown; `totalCost.unknownImageCostCount` counts those requests under the same filters.
+- Image cost is stored separately in `request_logs.image_cost_usd`; `request_logs.cost_usd` remains the Codex driver model token cost. Image costs use reported image usage at public token rates, or per-image quality/size estimates when usage is absent. Auto/custom sizes fall back to the 1536x1024 price; omitted quality uses medium. Rows and totals display combined costs as dollar amounts without Cost labels, without Known/Estimated labels or pricing disclaimers. Existing stored null costs are not backfilled; `totalCost.unknownImageCostCount` remains for API compatibility.
 - Inspect current plans, tests, and implementation before changing behavior; the Codex tool surface can change underneath qgrid.
 
-The 2.9.8 chat design removes the discarded client `request_image_generation` decision step, which asked GPT to choose a tool and then called GPT again for ordinary generation. Native `image_generation` handles ordinary generation directly. A separate qgrid-defined `generate_transparent_image` function is necessary to reach the standalone transparent endpoint, but the server executes it with the same token and cancellation signal without another GPT request. Routing belongs to the server; the chat only sends context and displays results.
+The current chat design registers `generate_image` for both ordinary and transparent images instead of splitting native hosted generation from a transparent-only function. The driver decides whether an image is needed, writes a self-contained prompt, and chooses `transparent_background` and `num_last_images_to_include` (0–5). Zero references starts a fresh image; a positive count selects only the last N conversation images, preserving their chronological order. The server executes the standalone request with the same token and cancellation signal without a second text-driver request. Routing belongs to the server; the chat only sends context and displays results. This preserves conversational interpretation while sharing direct Images execution with explicit SDK generation.
 
 Image edits need complete prior image bytes, not just text history or an assumption that the backend remembers earlier outputs. Chat replays uploaded and generated images, representing generated images as user visual references because assistant `input_image` blocks are invalid. Image previews report actual extension, decoded byte size, and natural dimensions. Uploaded images describe the existing resized JPEG sent to the model; generated images retain their returned bytes.
 
-Model labels show requested model to image model using serving metadata or the image model encoded in the logged cost method. The cost-method fallback remains an accounting assumption, not new evidence of the upstream model version. The UI has no image-generation or assumption badge and never fixes the name to `gpt-image-2.5`. Hosted and auto transparent logs retain driver identity and token costs separately from image metadata/cost.
+Model labels show requested model to image model using serving metadata or the image model encoded in the logged cost method. The cost-method fallback remains an accounting assumption, not new evidence of the upstream model version. The UI has no image-generation or assumption badge and never fixes the name to `gpt-image-2.5`. The `gpt-image-2` wire ID also does not prove Images 2.0 serving weights or selectable 2.5 variants. Hosted and auto image logs retain driver identity and token costs separately from image metadata/cost; direct `qgrid.image()` requests have no driver cost.
 
-Prompt wording alone is not a reliable format control: a 2026-09-29 probe returned PNG for a WebP prompt and WebP with explicit `outputFormat: "webp"`. Model prose contradicted the output and must not be used as evidence. Transparent generation remains PNG-only, and this release does not infer format from chat prose or introduce post-generation conversion.
+Prompt wording alone is not a reliable format control: a 2026-09-29 hosted-route probe returned PNG for a WebP prompt and WebP with explicit `outputFormat: "webp"`. Model prose contradicted the output and must not be used as evidence. Auto chat and standalone generation are PNG-only and reject explicit non-PNG options. Do not infer format from chat prose or introduce post-generation conversion or a hosted fallback.

package/skills/qgrid/references/openai-codex-runtime.md

@@ -48,8 +48,10 @@ availability or identical limits on qgrid's ChatGPT-subscription route.
 ### GPT-6 Astra, Sol, Luna, and GPT-6.1 Sol
 
 `openai/gpt-6-astra` uses the existing text generation, streaming and structured-output paths.
-The model supports image input, but qgrid keeps its existing SDK restriction: image parts are
-forwarded only for opt-in `imageGeneration` reference-image requests, not general vision chat.
+The model supports image input, but qgrid's language-model SDK adapter does not support general
+vision: it ignores image parts with a warning. Image generation/editing references belong to
+`generateImage({ model: qgrid.image(...), prompt: { text, images } })`; dashboard chat uses its
+own raw/server image inputs.
 Standard API-equivalent prices per million tokens are input $10, cached input $1, cache write
 $12.50, and output $50. Above 272,000 input tokens, the full request uses 2x input/cache rates and
 1.5x output rates. These are qgrid's cost estimates, not subscription billing amounts or Fast-tier prices.
@@ -179,23 +181,29 @@ Quota is fetched directly from `https://chatgpt.com/backend-api/wham/usage` with
 
 OpenAI usage reports total input, cached input, output, reasoning, and total tokens for the request. Preserve cached input as a subset of input; do not add it to input again when computing cache-hit rate.
 
-Image generation is opt-in and non-stream at the AI SDK interface. The backend still delivers its response through SSE. `imageGenerationOptions.outputFormat` maps to the hosted tool's `output_format` (`png`, `jpeg`, or `webp`); omission retains PNG. Returned bytes determine the MIME type when recognizable, with the reported format as fallback. Preserve that type through qgrid content, AI SDK file parts, and request-log image data URLs. The standalone transparent route remains PNG-only and rejects other output formats. Hosted Responses preserves observed image settings with route `codex-responses`, using PNG byte dimensions or the backend-reported JPEG/WebP size. Unreported model/settings stay absent. Hosted image cost is null because exact image usage/model are unavailable; requested settings cannot establish a price. Legacy responses without observations retain known three-size estimates only.
+Raw/server chat-model image requests are opt-in and non-stream to the caller, while the Responses backend still delivers its response through SSE. Explicit chat-model `imageGeneration: true` retains the hosted image tool for non-transparent requests. On that route, raw `imageGenerationOptions.outputFormat` maps to the hosted tool's `output_format` (`png`, `jpeg`, or `webp`); omission retains PNG. These are not public language-model SDK options: SDK image generation uses `qgrid.image()` / `generateImage` and calls standalone Images directly. Auto chat also calls standalone Images through its internal function and accepts PNG only. Returned bytes determine the MIME type when recognizable, with the reported format as fallback. Preserve that type through qgrid content and request-log image data URLs. Standalone Images rejects other output formats. Hosted Responses preserves observed image settings with route `codex-responses`, using PNG byte dimensions or the backend-reported JPEG/WebP size. Unreported model/settings stay absent. Image costs use reported image usage when available, otherwise the requested quality/size price table. Auto or unsupported sizes use the 1536x1024 price, and omitted quality uses medium. These are API-price estimates, not observed output settings or subscription charges.
 
-### Transparent image route
+Hosted image accounting reads `response.completed.response.tool_usage.image_gen`, separately from the driver's top-level `response.usage`. Preserve the response-level image usage on the first hosted output only, and obtain a missing image model from the response's `tools` entry. Do not overwrite per-image observed size/quality with that entry's `auto` configuration. On 2026-10-14, a raw subscription response reported image input/output usage and `model: gpt-image-2-codex`, while echoing `quality: auto` and `size: auto` despite explicit outgoing `high`/`1024x1536`. The raw image output was medium/1037x1517. This is an upstream override; qgrid must preserve observations rather than claim the requested controls were honored. Image costs remain GPT Image 2 public-price equivalents, not subscription billing.
 
-Explicit `imageGeneration: true` with `imageGenerationOptions.background: "transparent"` switches from hosted Responses to Codex `images/generations` or `images/edits`. The same selected subscription token, cancellation deadline, in-flight tracking, and one definitive 401 refresh apply. Use JSON content negotiation; do not reuse the Responses SSE Accept header. Never replay an ambiguous generation or fall back to opaque output/IS-Net. This explicit route runs `gpt-image-2` directly, so actual model metadata differs from the requested driver ID and ordinary driver usage stays zero. Image response usage and actual settings are preserved on `generation`; usage belongs to the first output only. Costs remain explicitly estimated from public prices.
+### Standalone image routes
 
-The image request adapter preserves text/system context and reference images (maximum five), rejects unsupported structured/tool requests before generation, and validates PNG contents with pngjs. Both a fully transparent pixel and visible content are required. Invalid, opaque, empty, or oversized results fail. Returned dimensions come from the decoded PNG; qgrid never silently resizes. A 2026-09-08 live request returned 1254x1254/medium for requested 1024x1024/high. Do not promise exact size/quality enforcement. See `openai-image-generation.ts` and opt-in `transparent`/`transparent-edit` cases in the image smoke script.
+The explicit image-model route `openai/gpt-image-2` with raw `imageGeneration: true` uses standalone Images for opaque, auto, or transparent backgrounds. It is exposed by `qgrid.image()` / AI SDK `generateImage`; the raw flag is an internal transport detail. Public `generateText` has no image-generation options. Reference inputs select `images/edits`, otherwise `images/generations`. Direct image output is PNG-only; decode and validate returned dimensions, applying the transparent-and-visible pixel requirement only when transparency was explicitly requested. Preserve returned background, quality, model, and image usage without claiming requested hints were honored. Image-model requests cannot use chat tools, structured output, auto-image mode, or streaming. The `gpt-image-2` wire identifier does not establish the serving Images version or selectable 2.5 variant.
 
-### Automatic dashboard chat images (2.9.8)
+Raw/server chat-model requests with explicit `imageGeneration: true` and `imageGenerationOptions.background: "transparent"` switch from hosted Responses to Codex `images/generations` or `images/edits`. The same selected subscription token, cancellation deadline, in-flight tracking, and one definitive 401 refresh apply. Use JSON content negotiation; do not reuse the Responses SSE Accept header. Never replay an ambiguous generation or fall back to opaque output/IS-Net. This explicit route runs `gpt-image-2` directly, so actual model metadata differs from the requested driver ID and ordinary driver usage stays zero. Image response usage and actual settings are preserved on `generation`; usage belongs to the first output only. Costs remain explicitly estimated from public prices.
 
-Raw `QueryInput.imageGeneration` accepts boolean or `"auto"`; the public AI SDK option remains boolean. OpenAI dashboard chat sends `"auto"` through one non-stream POST per turn. The dispatcher offers native `image_generation` plus a qgrid-defined Responses function, `generate_transparent_image`, reserved for transparent backgrounds. It executes that function server-side against standalone Codex Images using the same selected token and abort signal, without another GPT request. The client must not implement a `request_image_generation` decision loop.
+The direct image request adapter preserves text/system context and reference images (maximum five), rejects unsupported structured/tool requests before generation, and validates PNG contents with pngjs. Explicit transparency requires both a fully transparent pixel and visible content; opaque or entirely empty results fail that requirement. Invalid or oversized results fail for every background. Returned dimensions come from the decoded PNG; qgrid never silently resizes. A 2026-09-08 live request returned 1254x1254/medium for requested 1024x1024/high. Do not promise exact size/quality enforcement. See `openai-image-generation.ts` and opt-in `transparent`/`transparent-edit` cases in the image smoke script.
 
-Auto mode accepts text-only completion when no image tool was attempted. Explicit `true` still requires an image, and an attempted image tool that returns no complete image still fails. Caller tools and `outputSchema` are incompatible with auto mode. The transparent function and native image tool must not be mixed in one response; at most one transparent call is allowed.
+### Automatic dashboard chat images
 
-Auto transparent turns preserve the Responses driver model and token usage; image model, settings, and usage remain separate generation metadata. Do not apply the explicit standalone route's zero-driver accounting to auto turns. Full image history is replayed on each turn without reusable provider conversation state. Global image-tool opt-in remains unchanged outside chat to preserve regular callers' tool framing and cache behavior.
+Raw `QueryInput.imageGeneration` accepts boolean or `"auto"`; these flags are absent from the public AI SDK language-model options. OpenAI dashboard chat sends `"auto"` through one non-stream POST per turn. The dispatcher registers only the qgrid-defined Responses function `generate_image`, with server-validated arguments `prompt: string`, `transparent_background: boolean`, and `num_last_images_to_include: integer` from 0 to 5. Its wire setting is `strict: false`, matching Codex: the 2026-10-14 live Astra probe failed with `strict: true` even after removing bounds, and succeeded with `strict: false` with bounds retained. Keep server-side required-field/type/range/extra-field validation. It does not register the native hosted `image_generation` tool in auto mode. The server executes the function against standalone Codex Images with `model: gpt-image-2`, using the same selected token and abort signal, without another text-driver request. Both ordinary and transparent images use this route. The client must not implement a `request_image_generation` decision loop; no public SDK tool factory is exposed.
 
-The 2026-09-29 hosted-route probe returned PNG for a prompt-only WebP request and WebP for explicit `imageGenerationOptions.outputFormat: "webp"`. Verify bytes rather than model claims. The standalone transparent endpoint still returns PNG; no format conversion is added. See `output/webp-prompt-probe-2026-09-29/verification.md` and `docs/solutions/architecture-patterns/qgrid-native-auto-image-generation-2.9.8.md`.
+The driver receives complete text and image history and writes a self-contained generation/edit prompt. `num_last_images_to_include: 0` starts a fresh generation, even when historical images exist. A positive count selects the last N conversation images in chronological order for editing, up to five. Do not pass all history to the Images endpoint or assume it retains previous images. Use the selected references and the function's prompt for the direct request.
+
+Auto mode accepts text-only completion when no image tool was attempted. Explicit `true` still requires an image, and an attempted image tool that returns no complete image still fails. Caller tools and `outputSchema` are incompatible with auto mode. At most one `generate_image` call is allowed per turn. Auto image output is PNG-only; reject explicit JPEG/WebP options before generation rather than converting output or falling back to hosted Responses.
+
+Auto image turns preserve the Responses driver model and token usage; image model, settings, and usage remain separate generation metadata. Their combined cost is a chat-driver estimate plus an image-usage estimate. If the image stage fails after the driver completed, carry that completed driver result internally so error/aborted logs still record its usage and price once. Do not attach partial image output or claim a successful image cost. Do not apply the explicit standalone route's zero-driver accounting to auto turns. Full image history is replayed on each turn without reusable provider conversation state. Global image-tool opt-in remains unchanged outside chat to preserve regular callers' tool framing and cache behavior.
+
+The 2026-09-29 hosted-route probe returned PNG for a prompt-only WebP request and WebP for the raw/server option `imageGenerationOptions.outputFormat: "webp"`. Verify bytes rather than model claims. Standalone Images still returns PNG; no format conversion is added. See `output/webp-prompt-probe-2026-09-29/verification.md` and `docs/solutions/architecture-patterns/qgrid-native-auto-image-generation-2.9.8.md`.
 
 ### Size hints and observed dimensions (2026-10-13)
 

package/skills/qgrid/references/prompt-cache-and-usage.md

@@ -64,6 +64,9 @@ Cache-hit rate uses `input_tokens` as its denominator. Do not add cache subfield
 `packages/api/src/utils/providers/common/model-cost.ts` contains model-price fallback.
 
 - OpenAI cost normally uses qgrid's price table.
+- Since 2.10.7, native OpenAI `serviceTier: "fast"` calls apply the verified Fast API multiplier for the actual serving model: 2x for GPT-6 Astra, 6.1 Sol, 6 Sol, 6 Luna, and GPT-5.6 Sol/Terra/Luna (verified 2026-10-16 at https://developers.openai.com/api/docs/pricing). Apply it to input, cached input, cache writes, and output after the existing long-context calculation. Keep the explicit model allowlist; do not extrapolate to unverified or retired models.
+- This is an API-equivalent estimate based on the requested tier, not confirmed upstream billing or subscription quota consumption. Do not use the subscription quota multiplier for dollar costs. Omitted/flex tiers, models without verified Fast rates, and external telemetry keep their existing pricing behavior; positive provider-reported costs remain authoritative.
+- Query, stream, tool turns, and completed chat drivers preserved after image failures share the tier-aware calculation. Image costs stay separate and receive no Fast multiplier. Persist step costs and sum them once; do not reprice existing logs or infer their missing tiers.
 - OpenAI image generation stores a separate `image_cost_usd` estimate because the direct private route does not expose exact image-tool billing.
 - Anthropic prefers a positive Claude Code `total_cost_usd`; otherwise qgrid uses its price table.
 - Preserve Anthropic's five-minute and one-hour cache-creation token split and price each TTL separately.

package/skills/qgrid/references/request-log-run-lifecycle.md

@@ -61,6 +61,16 @@ This is a forward-only storage normalization. Do not backfill legacy prefixless
 
 Provider-qualified ids widen `model_name` and `requested_model_name` from 50 to 255 characters on both request-log entities. Generate and apply the normal Sonamu schema migration before running the new server. Do not hand-edit generated types, hand-author a derivable migration, or rewrite existing model values as part of that width migration.
 
+## Requested service tier (2.10.7+)
+
+Native OpenAI query/stream logs store the requested `serviceTier` in nullable `request_logs.service_tier`: `fast`, `flex`, or `NULL` when omitted. Other providers and external telemetry logger calls leave it `NULL`. Creation records the initial turn's tier; successful completion replaces it with the final turn's tier alongside the final model. Pending tool runs and error/aborted runs retain the initial tier; this is not a per-step tier history.
+
+The list and detail subsets expose this field. Show a filled lightning icon in `#1877F2` after the model display only when the stored value is `fast`, with the accessible label and tooltip `Fast 모드`. Do not mark `flex` or `NULL` as fast.
+
+This records caller intent, not the service tier confirmed by the upstream response. The OpenAI transport sends `fast` as `service_tier: "priority"`. Existing rows remain `NULL`; this means unrecorded, not proof of default mode. Do not infer historical tiers from model names, latency, or cost. Apply the generated service-tier migration before using the updated log queries.
+
+Each new generate step stores its tier-aware API-equivalent cost; the parent sums those step costs, including runs whose tier changes between turns. Do not multiply the parent total again based on its final `service_tier`. See `prompt-cache-and-usage.md` for pricing scope.
+
 ## Usage fields
 
 The dashboard total includes driver `cost_usd` and `image_cost_usd` once each. Both the stored sum and legacy driver-price adjustment apply the same normalized Sonamu filters as the list. The `/api/qgrid/stats` `requests` field is an in-memory count of completed provider generations since process start, separated by provider and token name; tool follow-up generations count separately. It is not a persisted lifetime count or a count of failed attempts.
@@ -82,9 +92,11 @@ OpenAI uses the completed Responses event's per-request usage fields.
 
 Anthropic normalizes native mutually exclusive categories by summing input + cache creation + cache read into total input. Prefer positive Claude Code `total_cost_usd`; otherwise calculate from the actual serving model and TTL split.
 
-For image requests, keep `cost_usd` as the Codex driver model token cost. Hosted image output costs use quality/size assumptions because image-tool usage is not exposed. Explicit transparent standalone Images requests run no driver and report zero driver usage/cost; auto transparent turns preserve the Responses driver model and usage while keeping image usage/settings separately. Image usage and actual settings are preserved as `observedGeneration` alongside `requestedOptions` in the synthetic tool log. Their separate image cost uses reported usage with an explicitly conservative public-price estimate. Treat `image_cost_usd` as a price-table estimate that may be inaccurate if Codex changes its underlying image accounting.
+For image requests, keep `cost_usd` as the Codex driver model token cost. Hosted image usage comes from `response.tool_usage.image_gen`, separately from the driver's `response.usage`. Explicit standalone Images requests, including `qgrid.image()`, run no driver and report zero driver usage/cost. Auto image turns preserve the Responses driver model and usage for every background while keeping standalone image usage/settings separately. Image usage and actual settings are preserved as `observedGeneration` alongside `requestedOptions` in the synthetic tool log. Price reported image usage at public token rates; only fall back to requested quality/size estimates when usage is absent. Display combined driver and image costs as dollar amounts without Cost labels; omit pricing disclaimers and cost-source metadata from the dashboard. Treat `image_cost_usd` as an API-price estimate, not subscription billing.
+
+For `imageGeneration: "auto"`, set `is_image_generation` only when returned content actually contains an image; offering the `generate_image` function is not sufficient. Keep stored `model_name` as the driver for hosted and auto image turns. Dashboard requested-to-image labels can derive the image model from serving/image-cost metadata without changing the stored driver or adding image-generation/assumption badges.
 
-For `imageGeneration: "auto"`, set `is_image_generation` only when returned content actually contains an image; offering image tools is not sufficient. Keep stored `model_name` as the driver for hosted and auto transparent turns. Dashboard requested-to-image labels can derive the image model from serving/image-cost metadata without changing the stored driver or adding image-generation/assumption badges.
+If the auto image stage fails or is cancelled after the chat driver has completed, preserve the completed driver result as internal failure metadata. The frame converts it with the same usage/pricing mapper used on success; terminal logging writes one generate step before aggregating the run and retains the actual/requested model and token. The parent remains `error` or `aborted` with the original error message. Do not write a completed image step, invent an image cost, expose failure metadata in the HTTP error, or record this step again on success. A driver that never completed and a direct image-only call have no completed chat usage to retain. `logger: false` still creates no logs. Log-writing failures must not replace the original generation failure.
 
 Reference images for image generation are not stored in `request_logs.user_prompt`; that field remains the text prompt. For inspection in the detail view, qgrid stores reference image metadata/base64 in the synthetic `image_generation` step's `tool_args.inputImages`. If Codex returns multiple image outputs, store `inputImages` only on the first synthetic image tool step so multi-output logs do not duplicate the same input payload on every output.
 

package/skills/qgrid/references/sonamu-api-web-flow.md

@@ -62,13 +62,13 @@ In 2.9.8, list and detail model labels show requested model to image model for g
 
 The list header ends its filter row with a reload button (2.10.2+) that calls the generated hooks' `refresh()` for the list and the total-cost query with the current filters; it does not refetch the token/project/model filter options, and TanStack Query's `isRefreshing` disables it while a reload is in flight.
 
-Structured output visibility: the list has an `Fmt` column (`json` badge from `is_structured` vs `text`) and a `broken` badge driven by `response_json_ok = false`; there is no broken-JSON list filter. At review time, all 114,647 succeeded structured rows had `response_json_ok = true` and zero false rows existed; the unindexed zero-result lookup scanned 1,286,016 rows and took about 3 seconds. Before reinstating the filter, validate the failure-signal semantics and index the predicate. The detail page shows a dark Response Type panel (zod expression by default, `type` declaration via toggle) rendered server-side from the stored `json_schema`. Plain-text rows render no panel. Rows written by pre-2.7.2 servers show `text`.
+Structured output visibility: the list has an `Fmt` column (`img` when `is_image_generation` is true, otherwise `json` when `is_structured` is true, otherwise `text`) and a `broken` badge driven by `response_json_ok = false`; there is no broken-JSON list filter. At review time, all 114,647 succeeded structured rows had `response_json_ok = true` and zero false rows existed; the unindexed zero-result lookup scanned 1,286,016 rows and took about 3 seconds. Before reinstating the filter, validate the failure-signal semantics and index the predicate. The detail page shows a dark Response Type panel (zod expression by default, `type` declaration via toggle) rendered server-side from the stored `json_schema`. Plain-text rows render no panel. Rows written by pre-2.7.2 servers show `text`.
 
 Tool contract visibility: the detail page renders a Tools panel between Response Type and Steps for requests whose `tools` is non-empty. It starts collapsed and its header shows the tool count plus a responsive, truncated name list built from the detail subset — collapsed views issue no extra query. Expanding fires `toolsView` once and caches it for that request id, since a stored tool contract never changes. Each card shows the name, the full description, the parameter count, and a compact display-only zod shape; enum values past the sixth collapse to `/* +N */`, with the full shape reachable through hover and keyboard focus. All JSON Schema conversion happens server-side — the web renders completed strings and holds no schema logic.
 
 Chat token targeting: the dashboard chat panel can pin a conversation to one account. It defaults to automatic distribution and lists only active tokens whose provider matches the selected model, sending the choice as `tokenName` so the request lands on exactly that account with no fallback. Changing either the model or the token resets the existing conversation coordinates, because a thread's prompt cache belongs to the account that built it. A selection that disappears — deactivated or deleted — is cleared automatically, but the selection is preserved while the token list is still loading so a slow fetch does not silently reset the user's choice.
 
-OpenAI chat in 2.9.8 uses one non-stream POST with `imageGeneration: "auto"` per turn, allowing native image generation or an ordinary text response. The server handles transparent image calls directly. Keep the removed image-generation checkbox, background checkbox, automatic-generation label, and client decision tool out of the UI. Replay full text and image history, including generated images as user visual references. Abort in-flight requests when chat unmounts.
+OpenAI chat uses one non-stream POST with `imageGeneration: "auto"` per turn, allowing image generation or an ordinary text response. The server registers one `generate_image` function and directly calls subscription Images for ordinary or transparent output. The driver sees full text and image history, writes the image prompt, and chooses the last 0–5 conversation images to include; zero starts a fresh image. Keep the removed image-generation checkbox, background checkbox, automatic-generation label, and client decision tool out of the UI. Replay full text and image history, including generated images as user visual references. Abort in-flight requests when chat unmounts.
 
 Clicking an attached or generated image opens a preview with extension, decoded byte size, natural width/height, original-size viewing, and download. Attachment metadata describes the existing resized JPEG conversion sent by chat; generated image bytes are preserved. Do not label attachment preview metadata as the original upload's metadata.
 

package/skills/qgrid/references/verification-and-debugging.md

@@ -128,15 +128,25 @@ AI SDK tools plus structured output:
 
 Image generation:
 
-- `packages/api/scripts/smoke-test-image-generation.ts`
+- `packages/api/e2e/image-generation.ts`
 - Human-initiated only.
 - Requires active OpenAI token with image entitlement and applicable migration.
 - For 2.9.8 chat, verify the actual browser POST and served bundle, not only a direct function test. A globally installed CLI on port 44900 can serve stale assets while repository tests pass; identify the listening process and its executable before assuming a rebuild or refresh affects it.
-- Cover auto text-only replies, native ordinary generation, server-side transparent editing, and replay of prior generated images. Explicit `true` must retain its image-required behavior. Verify driver usage stays separate from image usage and auto text replies are not image logs.
-- Verify extension, decoded bytes, and natural dimensions in chat image previews. A format request in prose is not evidence: the 2026-09-29 WebP probe returned PNG from a prompt-only request and WebP from explicit `outputFormat: "webp"`. Transparent output remains PNG.
-- Env: `QGRID_URL`, `QGRID_OPENAI_MODEL`.
+- Cover auto text-only replies and the single server-side `generate_image` function for ordinary generation and transparent editing. Zero selected references must create a fresh image despite older history; positive counts must select only the last N conversation images in order, up to five. Explicit raw `true` must retain its image-required hosted behavior for non-transparent chat-model requests. Verify driver usage stays separate from image usage and auto text replies are not image logs.
+- Verify extension, decoded bytes, and natural dimensions in chat image previews. A format request in prose is not evidence: the 2026-09-29 hosted-route WebP probe returned PNG from a prompt-only request and WebP from explicit `outputFormat: "webp"`. Auto chat and standalone output remain PNG-only and must reject explicit non-PNG options.
+- Requires `QGRID_REAL_PROVIDER_ACCEPTANCE=1`, explicit `QGRID_URL` and `QGRID_OPENAI_MODEL`. Optional `QGRID_TOKEN_NAME` pins a subscription token. `QGRID_IMAGE_SMOKE_CASES` selects named cases; the default covers eight images plus text, rejected inputs, and cancellation. Optional `batch`, `logger-off`, and `cancel-direct` cover SDK batching, no-log calls, and cancellation during direct Images requests. Never replay generations automatically.
+- Set `QGRID_IMAGE_E2E_OUTPUT` for PNGs and sanitized usage/cost/log evidence; `QGRID_IMAGE_E2E_PROJECT` groups test logs. Use an isolated DB and access-only test token, with notifications and keepalive disabled. For final acceptance, build the current API and cold-start `sonamu start` against that isolated DB rather than relying on HMR. HMR can leave a fresh dispatcher uninitialized; readiness alone does not prove the intended module version. The suite checks readiness before live calls.
+- Subscription `response.completed.tool_usage.image_gen` can be present with all-zero usage for text-only or function-tool replies. This metadata alone is not a hosted image execution. Keep the zero-usage regression test and verify auto text against the real backend.
+- Run auto text and generation with both Luna and Astra when changing the internal tool schema. Astra's private backend failed with `strict: true` even with bounds removed, while the same schema succeeded with `strict: false`. Keep `strict: false` and server-side validation; do not add a runtime fallback/retry.
 - Not part of CI; it consumes ChatGPT subscription quota.
 
+Image failure accounting:
+
+- `packages/api/e2e/image-failure-accounting.ts` calls the real subscription chat model and compares its completed usage with the persisted failed/aborted request and generate step.
+- Start a separate built local API with `NODE_OPTIONS=--import=<absolute path>/packages/api/e2e/image-failure-preload.mjs`. This test-only preload intercepts standalone Images requests with HTTP errors, network errors, invalid image responses, cancellation waits, or a synthetic success control. It never forwards Images requests upstream; no production test switch or fallback is added.
+- Both processes require `QGRID_REAL_PROVIDER_ACCEPTANCE=1`, `QGRID_IMAGE_E2E_FAULT_FILE`, and `QGRID_IMAGE_E2E_TRACE_FILE`. The preload requires `HOST=127.0.0.1` and an isolated `SONAMU_DB_NAME` starting with `qgrid_e2e_`. The runner also requires `QGRID_URL`, `QGRID_TOKEN_NAME`, and `QGRID_IMAGE_E2E_OUTPUT`.
+- Verify one completed driver step and exact input/output/cache usage and cost on failure; parent status and original errors stay failed/aborted, image cost stays unknown, and `logger: false` creates no records. The success control must not double-count driver usage. Trace files retain only completed model/usage metadata, never credentials or image bytes.
+
 Other scripts under `scripts/smoke-test-*` and `scripts/debug-*` are ad hoc probes. Read the script header and env vars before running.
 
 ## Common Error Triage
@@ -188,21 +198,25 @@ Generated SSE handlers missing a newly added event field:
 - Treat as a real error, not a recoverable partial result.
 - Check schema strictness and `stream-json-adapter` behavior.
 
-`qgrid: imageGeneration is not supported with streamText`:
+`qgrid: imageGeneration and imageGenerationOptions were removed from language-model options`:
+
+- Either removed key makes `generateText` and `streamText` fail before transport. Use `generateImage` with `qgrid.image()` and flat `QgridImageProviderOptions` for image output.
+
+`qgrid language models do not support image input`:
 
-- Image generation is non-stream only. Use `generateText`.
+- General vision remains unsupported by the language adapter; it ignores image parts with this warning. Reference-image editing belongs in `generateImage`'s `prompt: { text, images }`.
 
 `image generation is not supported on the Anthropic route`:
 
 - Image generation is OpenAI/Codex-only.
 
-`imageGeneration was requested but the response contained no image`:
+`qgrid.image: expected one image from the direct subscription Images route`:
 
-- AI SDK version-skew guard. The client requested image generation, but the server returned text-only content. Check server version and the OpenAI image-generation path.
+- Image-provider version-skew guard. Each call requires exactly one image with `generation.route: "codex-images"`. Check that the server supports the explicit image model and update the server and SDK together.
 
 `reference image input is too large for JSON transport`:
 
-- AI SDK reference-image guard. The client passed a base64 image data URL large enough to likely exceed qgrid's JSON request body transport. Compress or resize the image before calling `generateText`, preferably as WebP/JPEG.
+- AI SDK reference-image guard. The client passed a base64 image data URL large enough to likely exceed qgrid's JSON request body transport. Compress or resize the image before calling `generateImage`, preferably as WebP/JPEG.
 
 `qgrid query transport failed: response headers timed out`:
 

package/bundle/web-dist/client/assets/cost-CY2BJEPC.js

@@ -1 +0,0 @@
-var e=1e6,t=4;function n(t){return t/e}function r(e,n=!1){return`${n?`Known `:``}$${e.toFixed(t)}`}function i(e){return r(n(e))}function a(e){let t=e.is_image_generation&&e.image_cost_usd===null;return e.cost_usd===null&&e.image_cost_usd===null?t?`Unknown`:`—`:r(n((e.cost_usd??0)+(e.image_cost_usd??0)),t)}function o(e){return e.input_tokens<=0?`—`:`${Math.round(e.cache_read_tokens/e.input_tokens*100)}%`}export{r as i,i as n,a as r,o as t};