@cartanova/qgrid-cli 2.10.4 → 2.10.6

package/bundle/web-dist/server/assets/{show-C4jk1Hrp.js → show-DY396-LD.js}

@@ -1,7 +1,7 @@
-import { A as require_react, E as useQuery, X as __toESM, i as RequestLogStepService, k as require_jsx_runtime, l as isSonamuError, q as __commonJSMin, r as RequestLogService } from "./services.generated-FPwsG9p3.js";
-import { a as Link } from "./lazyRouteComponent-CUR-kWzI.js";
+import { A as require_react, E as useQuery, X as __toESM, i as RequestLogStepService, k as require_jsx_runtime, l as isSonamuError, q as __commonJSMin, r as RequestLogService } from "./services.generated-607iwhMI.js";
+import { a as Link } from "./lazyRouteComponent-Bi0fYGLs.js";
 import { c as lucideX, d as Markdown, t as Route, u as remarkGfm } from "../entry-server.generated.js";
-import { n as formatMicroUsd, t as cacheHitRate } from "./cost-CSH_t17I.js";
+import { n as formatMicroUsd, t as cacheHitRate } from "./cost-eEHeTRT5.js";
 import { t as requestModelDisplay } from "./request-model-CnCeaNLE.js";
 //#region ../../node_modules/.pnpm/@babel+runtime@7.29.2/node_modules/@babel/runtime/helpers/extends.js
 var require_extends = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -2194,15 +2194,11 @@ function MetricsPanel({ data, toolCallCount }) {
 					value: formatTokensPerSec(data.output_tokens, data.duration_ms, data.ttft_ms, tokensPerSecEnabled)
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Metric, {
-					label: "Driver Cost",
+					label: "Driver",
 					value: data.cost_usd !== null ? formatMicroUsd(data.cost_usd) : "—"
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Metric, {
-					label: "Cost Source",
-					value: data.cost_source ?? "legacy"
-				}),
-				/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Metric, {
-					label: "Image Cost",
+					label: "Image",
 					value: data.image_cost_usd !== null ? formatMicroUsd(data.image_cost_usd) : "—"
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Metric, {
@@ -2277,8 +2273,8 @@ function formatTokensPerSec(outputTokens, durationMs, ttftMs, enabled) {
 }
 function CompactMetric({ label, value }) {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
-		className: "min-w-0",
-		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
+		className: "min-w-0 self-end",
+		children: [label && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
 			className: "text-[10px] uppercase tracking-wider text-sand-400 font-medium truncate",
 			children: label
 		}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
@@ -2534,14 +2530,7 @@ function StepTreeItem({ entry, tokensPerSecEnabled }) {
 							label: "Cache 5m / 1h",
 							value: `${generate.cacheCreation5mTokens === null ? "—" : formatNum(generate.cacheCreation5mTokens)} / ${generate.cacheCreation1hTokens === null ? "—" : formatNum(generate.cacheCreation1hTokens)}`
 						}),
-						/* @__PURE__ */ (0, import_jsx_runtime.jsx)(CompactMetric, {
-							label: "Cost",
-							value: generate.costUsd === null ? "—" : formatMicroUsd(generate.costUsd)
-						}),
-						/* @__PURE__ */ (0, import_jsx_runtime.jsx)(CompactMetric, {
-							label: "Cost Source",
-							value: generate.costSource ?? "legacy"
-						}),
+						/* @__PURE__ */ (0, import_jsx_runtime.jsx)(CompactMetric, { value: generate.costUsd === null ? "—" : formatMicroUsd(generate.costUsd) }),
 						/* @__PURE__ */ (0, import_jsx_runtime.jsx)(CompactMetric, {
 							label: "Reasoning",
 							value: generate.reasoningTokens !== null && generate.reasoningTokens !== void 0 ? formatNum(generate.reasoningTokens) : "—"
@@ -2598,7 +2587,6 @@ function buildStepTree(steps) {
 				cacheCreation5mTokens: step.cache_creation_5m_tokens,
 				cacheCreation1hTokens: step.cache_creation_1h_tokens,
 				costUsd: step.cost_usd,
-				costSource: step.cost_source,
 				durationMs: step.duration_ms,
 				ttftMs: step.ttft_ms,
 				finishReason: step.finish_reason,

package/bundle/web-dist/server/assets/{tokens-odgS2-9q.js → tokens-COvV7qUP.js}

@@ -1,8 +1,8 @@
-import { A as require_react, O as useQueryClient, X as __toESM, k as require_jsx_runtime, n as QgridService, o as TokenService } from "./services.generated-FPwsG9p3.js";
+import { A as require_react, O as useQueryClient, X as __toESM, k as require_jsx_runtime, n as QgridService, o as TokenService } from "./services.generated-607iwhMI.js";
 import { f as lucideKeyRound, o as Q } from "../entry-server.generated.js";
-import { t as useUpdateTokenMutation } from "./use-update-token-mutation-xvXbPrCI.js";
-import { n as OAuthCodeEntry, t as useOAuthLoginFlow } from "./use-oauth-login-flow-DTQKdYBO.js";
-import { t as lucidePlus } from "./plus-Bvdj8Pwx.js";
+import { t as useUpdateTokenMutation } from "./use-update-token-mutation-D8XYV5of.js";
+import { n as OAuthCodeEntry, t as useOAuthLoginFlow } from "./use-oauth-login-flow-VYCYf3uv.js";
+import { t as lucidePlus } from "./plus-BH-t4cm_.js";
 //#region src/components/qgrid/AddTokenModal.tsx
 var import_react = /* @__PURE__ */ __toESM(require_react(), 1);
 var import_jsx_runtime = require_jsx_runtime();

package/bundle/web-dist/server/assets/{use-oauth-login-flow-DTQKdYBO.js → use-oauth-login-flow-VYCYf3uv.js}

@@ -1,4 +1,4 @@
-import { A as require_react, O as useQueryClient, X as __toESM, k as require_jsx_runtime, n as QgridService, o as TokenService } from "./services.generated-FPwsG9p3.js";
+import { A as require_react, O as useQueryClient, X as __toESM, k as require_jsx_runtime, n as QgridService, o as TokenService } from "./services.generated-607iwhMI.js";
 import { o as Q } from "../entry-server.generated.js";
 //#region src/components/qgrid/OAuthCodeEntry.tsx
 var import_react = /* @__PURE__ */ __toESM(require_react(), 1);

package/bundle/web-dist/server/assets/{use-update-token-mutation-xvXbPrCI.js → use-update-token-mutation-D8XYV5of.js}

@@ -1,4 +1,4 @@
-import { T as useMutation, n as QgridService } from "./services.generated-FPwsG9p3.js";
+import { T as useMutation, n as QgridService } from "./services.generated-607iwhMI.js";
 //#region src/services/token/use-update-token-mutation.ts
 function useUpdateTokenMutation() {
 	return useMutation({ mutationFn: ({ id, name, quotaThreshold, weight, keepaliveEnabled }) => QgridService.updateToken(id, name, quotaThreshold, weight, keepaliveEnabled) });

package/bundle/web-dist/server/entry-server.generated.js

@@ -1,6 +1,6 @@
-import { A as require_react, B as matchQuery, C as union, D as QueryClientProvider, F as notifyManager, G as focusManager, H as partialMatchKey, I as functionalUpdate, J as __exportAll, K as Subscribable, L as hashKey, M as infiniteQueryBehavior, N as Query, P as onlineManager, R as hashQueryKeyByOptions, S as string$2, U as resolveStaleTime, V as noop$1, W as skipToken, X as __toESM, Y as __require, _ as custom, b as number$1, c as fetch$1, d as SD, f as SUPPORTED_LOCALES, g as boolean$1, h as array, j as Mutation, k as require_jsx_runtime, m as _enum, n as QgridService, o as TokenService, p as setLocale, q as __commonJSMin, s as SonamuQueryMode, u as zArrayable, v as date, w as unknown, x as object, y as int, z as matchMutation } from "./assets/services.generated-FPwsG9p3.js";
-import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-CUR-kWzI.js";
-import { n as require_shim, t as require_react_dom } from "./assets/react-dom-CyuShs9K.js";
+import { A as require_react, B as matchQuery, C as union, D as QueryClientProvider, F as notifyManager, G as focusManager, H as partialMatchKey, I as functionalUpdate, J as __exportAll, K as Subscribable, L as hashKey, M as infiniteQueryBehavior, N as Query, P as onlineManager, R as hashQueryKeyByOptions, S as string$2, U as resolveStaleTime, V as noop$1, W as skipToken, X as __toESM, Y as __require, _ as custom, b as number$1, c as fetch$1, d as SD, f as SUPPORTED_LOCALES, g as boolean$1, h as array, j as Mutation, k as require_jsx_runtime, m as _enum, n as QgridService, o as TokenService, p as setLocale, q as __commonJSMin, s as SonamuQueryMode, u as zArrayable, v as date, w as unknown, x as object, y as int, z as matchMutation } from "./assets/services.generated-607iwhMI.js";
+import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-Bi0fYGLs.js";
+import { n as require_shim, t as require_react_dom } from "./assets/react-dom-CZ2eynd8.js";
 import minpath from "node:path";
 import minproc from "node:process";
 import { fileURLToPath as urlToPath } from "node:url";
@@ -46874,7 +46874,7 @@ function ChatWidget() {
 }
 //#endregion
 //#region src/components/Sidebar.tsx
-var qgridVersion = "2.10.4";
+var qgridVersion = "2.10.6";
 function Sidebar({ className }) {
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("aside", {
@@ -68752,15 +68752,15 @@ function RootComponent() {
 }
 //#endregion
 //#region src/routes/tokens.tsx
-var $$splitComponentImporter$5 = () => import("./assets/tokens-odgS2-9q.js");
+var $$splitComponentImporter$5 = () => import("./assets/tokens-COvV7qUP.js");
 var Route$5 = createFileRoute("/tokens")({ component: lazyRouteComponent($$splitComponentImporter$5, "component") });
 //#endregion
 //#region src/routes/settings.tsx
-var $$splitComponentImporter$4 = () => import("./assets/settings-DeHNwoMv.js");
+var $$splitComponentImporter$4 = () => import("./assets/settings-C_6dpK5p.js");
 var Route$4 = createFileRoute("/settings")({ component: lazyRouteComponent($$splitComponentImporter$4, "component") });
 //#endregion
 //#region src/routes/monit.tsx
-var $$splitComponentImporter$3 = () => import("./assets/monit-DSxs4Jnl.js");
+var $$splitComponentImporter$3 = () => import("./assets/monit-DBXezg7R.js");
 var monitSearchSchema = object({ level: _enum([
 	"all",
 	"warn",
@@ -69137,7 +69137,7 @@ object({
 _enum(["A"]);
 //#endregion
 //#region src/routes/logs.tsx
-var $$splitComponentImporter$2 = () => import("./assets/logs-CagNGTBj.js");
+var $$splitComponentImporter$2 = () => import("./assets/logs-CIVFxfoi.js");
 var logsSearchSchema = object({
 	token: string$2().optional(),
 	project: string$2().optional(),
@@ -69151,11 +69151,11 @@ var Route$2 = createFileRoute("/logs")({
 });
 //#endregion
 //#region src/routes/index.tsx
-var $$splitComponentImporter$1 = () => import("./assets/routes-i-sTqXMX.js");
+var $$splitComponentImporter$1 = () => import("./assets/routes-COWYIvA-.js");
 var Route$1 = createFileRoute("/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 //#endregion
 //#region src/routes/requests/show.tsx
-var $$splitComponentImporter = () => import("./assets/show-C4jk1Hrp.js");
+var $$splitComponentImporter = () => import("./assets/show-DY396-LD.js");
 var showSearchSchema = object({ id: number$1() });
 var Route = createFileRoute("/requests/show")({
 	validateSearch: showSearchSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.10.4",
+  "version": "2.10.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"
@@ -59,7 +59,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "bundle": "pnpm run check:bundle-dependencies && cd ../api && pnpm build && cd ../cli && rm -rf bundle && mkdir -p bundle/public && touch bundle/.env && cp -r ../api/dist ./bundle/dist && cp -r ../api/web-dist ./bundle/web-dist && cp -r ../api/src ./bundle/src",
+    "bundle": "cd ../api && pnpm build && cd ../cli && pnpm run bundle:copy",
+    "bundle:copy": "pnpm run check:bundle-dependencies && rm -rf bundle && mkdir -p bundle/public && touch bundle/.env && cp -r ../api/dist ./bundle/dist && cp -r ../api/web-dist ./bundle/web-dist && cp -r ../api/src ./bundle/src",
     "build": "tsdown",
     "check:bundle-dependencies": "node tooling/check-bundled-api-dependencies.mjs",
     "postinstall": "node postinstall.mjs",

package/skills/qgrid/SKILL.md

@@ -38,13 +38,13 @@ When helping a user set up local `@cartanova/qgrid-ai-sdk`, `createQgridLogger`,
 
 Prefer `QGRID_PROJECT_NAME` as the project-wide default. Use config `projectName` only for a deliberate per-call/per-provider override. Do not add `projectName` or `project_name` under `providerOptions.qgrid`; current code does not read it there.
 
-When writing AI SDK examples or setup code, import the public `QgridProviderOptions` type and apply `satisfies QgridProviderOptions` to the value under `providerOptions.qgrid`. AI SDK types the outer `providerOptions` as a generic JSON record, so it cannot infer qgrid's option names and values by itself. `QgridProviderOptions` is the inner qgrid namespace type, not the outer record type.
+When writing AI SDK examples or setup code, use `satisfies QgridProviderOptions` for language-model options or `satisfies QgridImageProviderOptions` for image-model options under `providerOptions.qgrid`. AI SDK types the outer `providerOptions` as a generic JSON record, so it cannot infer qgrid's option names and values by itself. These types describe the inner qgrid namespace, not the outer record.
 
 Request logging is enabled by default. Use `providerOptions.qgrid.logger: false` only for a call that must create zero qgrid request-log rows. The same option suppresses both qgrid's server-native logging and `createQgridLogger` telemetry logging for that generation; it does not disable generation, AI SDK tool execution, multi-step continuation, or OpenAI cache affinity. The old `logMode` input has been removed and must not appear in setup code or raw qgrid payloads.
 
 ## Non-Negotiable Boundaries
 
-- Use `packages/ai-sdk` as the active public SDK surface.
+- Use `packages/ai-sdk` as the active public SDK surface. `qgrid()` implements `LanguageModelV3` for text, tools, and structured output; it has no public image-generation options and does not support general vision. `qgrid.image("openai/gpt-image-2")` implements `ImageModelV3` for standard AI SDK `generateImage`, directly calling subscription Images for generation or reference editing without a chat driver. Dashboard chat registers its image tool internally; do not add a public SDK tool factory. See `references/ai-sdk-provider-contract.md` for image options, usage, and metadata.
 - Expose thinking only as `providerOptions.qgrid.thinking?: boolean`: omission preserves the model policy, false overrides effort, and unsupported/unverified off requests fail explicitly. See the SDK and provider runtime references for the dated support snapshot. Keep Anthropic thinking controls separate from mandatory configuration and memory isolation. Haiku/Sonnet 5.5 off uses a computed thinking-only native body override with Claude Code >=2.1.295; never inherit or expose arbitrary extra body.
 - The old v1 SDK package (`packages/sdk`, `@cartanova/qgrid-sdk`) has been removed from the repository. It survives only as a deprecated npm artifact (1.9.0); do not resurrect it or write new code against it.
 - Let the server infer single-turn versus tool-run request-log lifecycle. Do not recreate caller-selected logging modes in the SDK or API examples.
@@ -54,11 +54,11 @@ Request logging is enabled by default. Use `providerOptions.qgrid.logger: false`
 - Prefer `getPuri()` for Sonamu model queries. Treat `getDB()` as a legacy escape hatch only when Puri cannot express the required query. Inside `@transactional` methods, all participating queries must use `getPuri()`; `getDB()` does not reuse Sonamu's ambient transaction connection.
 - Never hand-author migration files for Sonamu-managed schema. In the qgrid source repository, change the entity definition, inspect `sonamu migrate status`, and create migration files with `mise exec -- pnpm --dir packages/api sonamu migrate generate`. Inspect the generated files before applying them. If Sonamu cannot express a required schema change, stop and ask rather than silently replacing its workflow with a custom migration.
 - Keep OpenAI Codex built-in tools, apps, plugins, skills, web search, shell, and environment instruction blocks disabled unless the user explicitly asks for agentic Codex behavior.
-- Treat OpenAI image generation as opt-in outside dashboard chat. In 2.9.8, OpenAI `qgrid_chat` opts into raw API `imageGeneration: "auto"` on every turn; the public AI SDK option remains boolean. Ordinary images use the hosted Responses image tool; a server-executed transparent-image function calls Codex standalone Images directly with subscription credentials. Do not reintroduce a client decision tool followed by another GPT generation request. Image costs remain API-price estimates.
+- Treat OpenAI image generation as opt-in outside dashboard chat. OpenAI `qgrid_chat` opts into raw API `imageGeneration: "auto"` on every turn. Auto mode registers only the server-executed `generate_image` function and calls Codex standalone Images for ordinary or transparent output. The raw explicit chat-model `imageGeneration: true` hosted route remains supported separately. The public SDK uses only `qgrid.image()` / `generateImage` for images, calling standalone Images for every background. Do not expose the raw `imageGeneration` or `imageGenerationOptions` fields as language-model options or retain deprecated shims. Do not reintroduce a client decision tool followed by another GPT generation request. Image costs use reported image usage at public token rates when available; otherwise estimate per image from the requested quality/size table. Auto or unsupported sizes use the 1536x1024 price; omitted quality uses medium. Display combined driver and image costs as dollar amounts without Cost labels. Do not show Known/Estimated labels, pricing disclaimers, or cost-source metadata in the dashboard.
 
 ## Request log IDs (2.10.0+)
 
-- Successful raw query responses and stream `done` events expose optional top-level `requestLogId`. The AI SDK exposes it as `providerMetadata.qgrid.requestLogId`; await stream metadata after consuming the stream.
+- Successful raw query responses and stream `done` events expose optional top-level `requestLogId`. AI SDK text calls expose it as `providerMetadata.qgrid.requestLogId`; await stream metadata after consuming the stream. `generateImage` exposes each call's ID under `providerMetadata.qgrid.images[]` alongside generation metadata.
 - The ID identifies the parent request log and stays the same across tool-run steps. It is omitted with `logger: false`. Keep `runContext.requestLogId` for tool continuation only; do not replay the top-level ID as continuation state.
 - Update both server and AI SDK to 2.10.0 or later to consume the metadata. Older servers may omit the ID. This contract does not add IDs to delta or error events or change `createQgridLogger` for external providers.
 
@@ -66,17 +66,18 @@ Request logging is enabled by default. Use `providerOptions.qgrid.logger: false`
 
 - Raw `imageGeneration: "auto"` permits text-only replies; explicit `true` still requires an image. Both use non-stream requests. Auto mode rejects caller tools and output schemas.
 - Dashboard chat sends complete text and image history, including prior generated images as user visual references. Do not assume provider conversation state retains image bytes or send assistant `input_image` blocks.
-- The model chooses ordinary `image_generation` or `generate_transparent_image`; the server runs the latter directly with the selected token and cancellation signal. Preserve driver usage separately from image usage.
+- Register only `generate_image` for auto mode, with server-validated arguments `prompt: string`, `transparent_background: boolean`, and `num_last_images_to_include: integer` from 0 to 5. Use `strict: false` on the wire, matching Codex; Astra subscription requests fail with `strict: true`. Keep complete server-side validation. The driver sees the complete conversation and writes a self-contained image prompt. Zero references means fresh generation; a positive count selects the last N conversation images in chronological order for editing. Do not forward all historical images automatically.
+- Run the function directly against subscription Images with the selected token and cancellation signal, without a second text-driver request. Preserve driver usage separately from image usage. Do not register the native hosted `image_generation` tool in auto mode.
 - Request-log model labels show requested model to image model using serving/image-cost metadata. Do not hardcode `gpt-image-2.5` or restore image-generation/assumption badges. In auto mode, mark image generation only when an image was produced.
 - Read `references/decision-rationale.md` and `references/openai-codex-runtime.md` before changing this routing or its cache boundary.
 
 ## Image output formats (2.9.6+)
 
-- Use `imageGenerationOptions.outputFormat: "png" | "jpeg" | "webp"` on the hosted Responses image path. Omission retains PNG.
+- Raw explicit chat-model hosted Responses requests support `imageGenerationOptions.outputFormat: "png" | "jpeg" | "webp"`. Omission retains PNG. Auto chat and public `generateImage` use standalone Images and support PNG only; reject other formats before generation. Public image options use flat `QgridImageProviderOptions`.
 - Preserve the actual returned MIME type in qgrid content, AI SDK files, and request-log image URLs; do not relabel bytes as the requested format.
-- Transparent generation keeps the standalone Codex Images route and accepts PNG only. Reject transparent JPEG/WebP requests before generation.
+- Transparent generation uses the standalone Codex Images route and accepts PNG only. Reject transparent JPEG/WebP requests before generation. Do not convert output or fall back to another route.
 - Keep the AI SDK standard `GeneratedFile.mediaType: string` contract. Do not add a qgrid-specific image wrapper or conditional return type.
-- A 2026-09-29 live probe returned PNG for a prompt-only WebP request and WebP when `outputFormat: "webp"` was supplied. Model prose is not format evidence; inspect file bytes. Chat does not infer output format from prose, and no post-generation conversion is performed.
+- A 2026-09-29 hosted-route probe returned PNG for a prompt-only WebP request and WebP when `outputFormat: "webp"` was supplied. Model prose is not format evidence; inspect file bytes. Chat does not infer output format from prose, and no post-generation conversion is performed.
 
 ## Verification
 

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: "1024x1024" | "1024x1536" | "1536x1024"`, 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. 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,7 +144,7 @@ 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.
 - Fast mode changes upstream service-tier routing only. It does not change token weights or client concurrency.
@@ -139,7 +152,7 @@ Fast mode contract:
 
 ## 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 +166,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 +206,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 +216,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 +229,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. Hosted-route pricing assumptions use `gpt-image-2`, `medium`, and `1536x1024` when omitted; these do not establish actual output settings. Transparent-route image usage and observed settings are recorded 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. Because Codex does not expose exact image tool usage, `image_cost_usd` is a price-table estimate and may be inaccurate.
+- 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,20 +181,30 @@ 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. Recorded image cost remains an estimate based on qgrid's configured public image price table because this route does not expose exact image-tool billing.
+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)
+
+`size` accepts `auto` or positive-integer WIDTHxHEIGHT hints. Keep the requested value separate from observed output metadata; do not promise exact dimensions or inject a resize. Prompt for the desired ratio. Twelve live subscription requests across hosted Responses and standalone generation/edit returned 841x1870 for 9:20, 941x1672 for 4K portrait, and 2172x724 for 4:1 (clamped to 3:1). Explicit 1152x2560 and even 1x1 hints returned 1254x1254 for a neutral prompt. These approximately 1.57MP observations are not a universal limit. Public API limits (16-pixel multiples, up to 4K) are not the private backend contract. Latest upstream Codex at `12cca49c81c8aa6a37a5cc4e39964ee3b70f9458` hardcodes `size: auto` for image generation/editing and saves bytes without resizing.

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

@@ -82,9 +82,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 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.
+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.
+
+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.