@oh-my-pi/pi-ai 18.11.0 → 18.11.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [18.11.1] - 2026-10-15
+
+### Added
+
+- Added image support for native OpenAI Decisions and Workers AI judgments, prompted vision chat, and auth-gateway System One requests; images exceeding a judgment API's documented caps (e.g. Clef's 4 images, 4 MiB each) are rejected locally ([#15471](https://github.com/can1357/oh-my-pi/pull/15471) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy)).
+- `isSurvivingAssistant` in `providers/transform-messages`: whether an assistant turn reaches a replay, malformed tool calls dropped first, so callers outside `transformMessages` pick the same latest turn ([#15791](https://github.com/can1357/oh-my-pi/pull/15791) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed Codex-hosted image generation ignoring the requested `aspect_ratio`/`image_size`, and `3:2`/`2:3` requests sending no size to OpenAI image models ([#15601](https://github.com/can1357/oh-my-pi/pull/15601) by [@chulmin-dev](https://github.com/chulmin-dev))
+- Fixed Claude subagents failing to return structured results when `yield` arguments arrived as invalid JSON ([#15605](https://github.com/can1357/oh-my-pi/pull/15605) by [@farnoy](https://github.com/farnoy))
+- Fixed turns stopping instead of retrying when a gateway reports its upstream WebSocket closed before `response.completed` ([#15628](https://github.com/can1357/oh-my-pi/pull/15628) by [@nqrwhal](https://github.com/nqrwhal)).
+- Fixed Claude on Google Vertex ignoring `cacheRetention: "long"`: prompt caches now get the 1h TTL instead of expiring after 5 minutes, and the `extended-cache-ttl` beta (which Vertex rejects) is never sent there ([#15505](https://github.com/can1357/oh-my-pi/pull/15505) by [@hpost](https://github.com/hpost))
+- Fixed Gemini tool continuations failing on OpenAI-compatible gateways that return `reasoning_signature`, including restored sessions ([#15678](https://github.com/can1357/oh-my-pi/pull/15678) by [@Zzz141592653](https://github.com/Zzz141592653))
+- Fixed Cursor sessions failing every rebuilt request with `PROVIDER_ERROR` after the server re-sent a tool call: the call is recorded once, and histories that already repeat it replay it once with its latest result ([#15749](https://github.com/can1357/oh-my-pi/issues/15749))
+- Fixed Cursor turns cut off mid-stream failing every retry with `PROVIDER_ERROR` until you sent a new message; the retry now starts a fresh Cursor conversation ([#15830](https://github.com/can1357/oh-my-pi/issues/15830))
+- Fixed malformed image-generation inputs being forwarded to providers or reported as credential/upstream errors ([#15765](https://github.com/can1357/oh-my-pi/pull/15765) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy)).
+- Fixed broker-backed auth-gateway processes retaining a cache entry for every distinct client session indefinitely under sustained traffic ([#15841](https://github.com/can1357/oh-my-pi/issues/15841)).
+- Fixed turns ending on a pinned error when a provider reports "temporarily unavailable" or finishes with an `unknown`, `other` or `unspecified` finish reason: these now retry automatically ([#15424](https://github.com/can1357/oh-my-pi/pull/15424) by [@lockwo](https://github.com/lockwo))
+
 ## [18.11.0] - 2026-10-14
 
 ### Fixed

package/dist/types/images/shared.d.ts

@@ -1,7 +1,8 @@
 import type { FetchImpl, Model, Usage } from "@oh-my-pi/pi-catalog/types";
 import type { ApiKey } from "../auth-retry.js";
 import * as AIError from "../error/index.js";
-import type { GeneratedImage } from "./types.js";
+import type { ImageContent } from "../types.js";
+import type { GeneratedImage, ImageInput } from "./types.js";
 export declare class ImageApiError extends AIError.ProviderHttpError {
     readonly name = "ImageApiError";
 }
@@ -38,6 +39,29 @@ export declare function decodeImageResponse(value: unknown, fetch: FetchImpl, si
  * multi-MB payloads are never fully decoded just to be labelled.
  */
 export declare function sniffBase64ImageMimeType(base64: string): string | undefined;
-export declare function toDataUrl(image: GeneratedImage): string;
+/**
+ * Validate provider-bound image input without changing it. Accepts non-empty standard base64
+ * with canonical trailing bits and optional padding, and case-insensitive image MIME syntax
+ * (RFC 6838 restricted names). Does not sniff the MIME type, decode image pixels, or enforce
+ * provider-specific format support; data-URL transports additionally go through `toDataUrl`.
+ *
+ * @throws {AIError.ValidationError} If the base64 data or image MIME type is invalid.
+ */
+export declare function validateImageInput(image: ImageInput): void;
+/**
+ * Encode validated image input as a base64 data URL.
+ *
+ * @throws {AIError.ValidationError} If the input is invalid or its MIME type cannot survive a data URL.
+ */
+export declare function toDataUrl(image: ImageInput): string;
+/**
+ * Whether a MIME type survives a data URL intact: a raw `#` starts a URL fragment and
+ * data-URL consumers leave a `%23` escape undecoded, so no data-URL transport preserves it.
+ */
+export declare function isDataUrlMimeType(mimeType: string): boolean;
+/** Whether a value is an embedded image with valid base64 data, MIME type, and detail. */
+export declare function isEmbeddedImageContent(image: unknown): image is ImageContent;
+/** Convert one validated embedded image to a lowercase-MIME inline data URL. */
+export declare function embeddedImageDataUrl(image: unknown): string;
 export declare function resolveOpenAIImageSize(aspectRatio?: string, imageSize?: string): string | undefined;
 export {};

package/dist/types/judgment/native.d.ts

@@ -1,7 +1,7 @@
 import type { Api, FetchImpl } from "@oh-my-pi/pi-catalog/types";
 import { type ApiKey } from "../auth-retry.js";
 import * as AIError from "../error/index.js";
-import type { Model, Usage } from "../types.js";
+import type { ImageContent, Model, Usage } from "../types.js";
 import { type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type Questions } from "./types.js";
 import type { JudgmentWire } from "./wire.js";
 export declare const TYPESAFE_PROVIDER = "typesafe";
@@ -16,6 +16,14 @@ declare const JUDGMENT_WIRES: {
 export type JudgmentApi = keyof typeof JUDGMENT_WIRES;
 /** Whether a catalog API answers judgments natively. */
 export declare function isJudgmentApi(api: Api): api is JudgmentApi;
+/** Whether both the native protocol and catalog model support image input. */
+export declare function nativeJudgmentSupportsImages(model: Model): boolean;
+/**
+ * Reject `images` that `model`'s native judgment API cannot take — no image support, or a
+ * documented per-dialect cap exceeded — before any credential or upstream work.
+ * @throws {AIError.ValidationError} naming the reason.
+ */
+export declare function checkNativeJudgmentImages(model: Model, images: readonly ImageContent[]): void;
 /** `TYPESAFE_BASE_URL` when set, else the public API root; trailing slashes stripped. */
 export declare function typesafeBaseUrl(): string;
 /** `TYPESAFE_DEFAULT_MODEL` when set, else {@link TYPESAFE_DEFAULT_MODEL}. */
@@ -43,6 +51,11 @@ export interface NativeJudgeOptions extends NativeJudgeConnection {
      * requests are split. Unset: no cap.
      */
     maxQuestions?: number;
+    /**
+     * Whether the catalogued model accepts images. `false` disables image input;
+     * a `true` value cannot enable a wire dialect that does not support images.
+     */
+    supportsImages?: boolean;
 }
 /** Per-call options for {@link NativeJudge.judge}. */
 export interface NativeJudgeCallOptions extends JudgeOptions {
@@ -60,6 +73,8 @@ export declare class JudgmentApiError extends AIError.ProviderHttpError {
 export declare class NativeJudge implements Judge {
     #private;
     readonly label: string;
+    /** True when the selected native wire and model both accept image inputs. */
+    readonly supportsImages?: boolean;
     readonly api: JudgmentApi;
     readonly provider: string;
     /** Wire model id sent with every request. */

package/dist/types/judgment/text.d.ts

@@ -1,8 +1,10 @@
-import type { Usage } from "../types.js";
+import type { ImageContent, Usage } from "../types.js";
 import { type Answer, type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type JudgmentState, type Question, type Questions } from "./types.js";
 export interface TextPrompt {
     system: string;
     user: string;
+    /** Images are kept as distinct content blocks, never rendered into JSON text. */
+    images?: readonly ImageContent[];
     /** Format-correction attempt; chat backends may enforce tool suppression on the wire. */
     retry?: boolean;
 }
@@ -16,6 +18,8 @@ export interface TextBackend {
     readonly api: string;
     readonly provider: string;
     readonly model: string;
+    /** Whether this backend can send image content on the wire. */
+    readonly supportsImages?: boolean;
     /** State guard for agent-tuned chat models; on-device classifier workers may disable it. */
     readonly guardState?: boolean;
     /** Format-correction retries after a completion cannot be parsed. */
@@ -26,10 +30,11 @@ export interface TextBackend {
 export declare function renderJudgmentState(state: JudgmentState): string;
 /**
  * Render a request: the system prompt carries the preamble and question
- * definitions (constant across states, so prompt caches hit); the user message
- * carries XML-field state followed by the answer-format cue. Small models act
- * on a bare request (answer it, emit tool calls) instead of classifying it —
- * explicit tags and the trailing cue keep them on task.
+ * definitions (constant across states, so prompt caches hit); the user text
+ * carries XML-field state followed by the answer-format cue. Images remain
+ * separate content blocks. Small models act on a bare request (answer it,
+ * emit tool calls) instead of classifying it — explicit tags and the trailing
+ * cue keep them on task.
  */
 export declare function renderJudgmentPrompt(request: JudgmentRequest, options?: {
     guardState?: boolean;
@@ -53,6 +58,7 @@ export declare function splitAnswerLines(text: string, ids: readonly string[]):
 export declare function parseAnswer(id: string, question: Question, reply: string): Answer;
 export declare class TextJudge implements Judge {
     #private;
+    readonly supportsImages?: boolean;
     readonly label: string;
     constructor(backend: TextBackend);
     judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;

package/dist/types/judgment/types.d.ts

@@ -11,7 +11,7 @@
  * bridge ({@link TextJudge}) renders the same questions into keyword prompts
  * for an ordinary chat model.
  */
-import type { Usage } from "../types.js";
+import type { ImageContent, Usage } from "../types.js";
 /** JSON-compatible value; readonly containers are accepted so `as const` state passes through. */
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -73,6 +73,8 @@ export type AnswerFor<Q extends Question> = Q extends ChoiceQuestion<infer L> ?
 export interface JudgmentRequest<Q extends Questions = Questions> {
     state: JudgmentState;
     questions: Q;
+    /** Images evaluated alongside the state; never part of the JSON state itself. */
+    images?: readonly ImageContent[];
 }
 export interface JudgmentResult<Q extends Questions = Questions> {
     /** Transport that produced the answers (a judgment api such as `typesafe`, or the chat model's api). */
@@ -89,6 +91,8 @@ export interface JudgeOptions {
 }
 /** Answers typed questions about a state. Implementations are stateless and safe to share. */
 export interface Judge {
+    /** Whether this backend can consume separate image content blocks. */
+    readonly supportsImages?: boolean;
     /** Backend description for logs, e.g. `typesafe/jev-latest`. */
     readonly label: string;
     judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;

package/dist/types/judgment/wire.d.ts

@@ -20,6 +20,22 @@ export interface DecodedJudgment {
     refused: readonly string[];
     usage: Usage;
 }
+/**
+ * Image input one judgment dialect accepts. Every cap is optional; {@link NativeJudge}
+ * rejects a request exceeding one locally instead of spending an upstream call on it.
+ */
+export interface JudgmentImageInput {
+    /** Accepted lowercase MIME types; unset accepts any image type. */
+    mimeTypes?: readonly string[];
+    /** Images per request. */
+    maxCount?: number;
+    /** Decoded bytes per image. */
+    maxBytes?: number;
+    /** Decoded bytes across all images. */
+    maxTotalBytes?: number;
+    /** Pixels per image, when the image header reports dimensions. */
+    maxPixels?: number;
+}
 /** How one judgment API addresses, encodes, and decodes a request. */
 export interface JudgmentWire {
     /**
@@ -29,6 +45,8 @@ export interface JudgmentWire {
     target(baseUrl: string, model: string, key: string): JudgmentTarget;
     /** Request body for `model`. */
     encode(request: JudgmentRequest, model: string): unknown;
+    /** Image input this dialect accepts; absent means text-only. */
+    images?: JudgmentImageInput;
     /** The response's answers and usage; `undefined` when the payload is not this API's response shape. */
     decode(payload: unknown): DecodedJudgment | undefined;
 }

package/dist/types/providers/anthropic.d.ts

@@ -133,6 +133,8 @@ export type AnthropicClientOptionsArgs = {
     dynamicHeaders?: Record<string, string>;
     isOAuth?: boolean;
     hasTools?: boolean;
+    /** Whether a tool in ANTHROPIC_BUFFERED_INPUT_TOOLS is present; suppresses the request-wide fine-grained streaming beta. */
+    hasBufferedInputTools?: boolean;
     thinkingEnabled?: boolean;
     thinkingDisplay?: AnthropicThinkingDisplay;
     disableStrictTools?: boolean;

package/dist/types/providers/cursor.d.ts

@@ -218,6 +218,13 @@ export declare function mergeCursorMcpToolCallArgs(streamed: Record<string, unkn
  * call handed to an external executor is only a handoff while the marker is
  * absent, and the consumer that runs it needs a runnable block.
  *
+ * A frame whose `toolCallId` already has a block in `output` is the server
+ * re-dispatching that call (a new `execId`, e.g. a `read` re-sent once a
+ * parallel shell created the file). It adds no block: a second block with the
+ * same id makes every rebuilt history replay the call twice, which Cursor
+ * rejects (issue #15749). The re-run's result supersedes the first one in the
+ * host's result buffer.
+ *
  * Exported for tests to exercise ordering with adjacent text/thinking blocks.
  */
 export declare function synthesizeCursorExecToolCall(output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, toolCallId: string, toolName: string, args: Record<string, unknown>, { executed }?: {

package/dist/types/providers/systemone-server.d.ts

@@ -14,10 +14,11 @@ export interface SystemOneResponseBody {
     };
 }
 /**
- * Validate the routing-relevant parts of a System One request body.
+ * Validate the routing-relevant parts of a System One request body, including
+ * optional embedded base64 images.
  *
- * @throws {AIError.ValidationError} naming the offending field when `model`,
- * `state`, or `questions` is missing or malformed.
+ * @throws {AIError.ValidationError} when required routing fields are missing
+ * or malformed, or a supplied image is malformed.
  */
 export declare function parseRequest(body: unknown): SystemOneParsedRequest;
 /** Re-encode a judgment result in TypeSafe's response shape. */

package/dist/types/providers/transform-messages.d.ts

@@ -36,6 +36,14 @@ export declare function isMalformedToolCallName(name: unknown): boolean;
  * off by `length` / `error` / `aborted` that carries no text and no tool call.
  */
 export declare function shouldDropTruncatedThinkingOnlyAssistant(msg: AssistantMessage): boolean;
+/**
+ * Whether `msg` reaches a replay as an assistant turn, so it can be the latest
+ * surviving one: {@link sanitizeMalformedToolCalls} drops its malformed tool
+ * calls, then {@link shouldDropTruncatedThinkingOnlyAssistant} a truncated
+ * turn left with no text and no tool call. On an already sanitized list this
+ * is `!shouldDropTruncatedThinkingOnlyAssistant(msg)`.
+ */
+export declare function isSurvivingAssistant(msg: AssistantMessage): boolean;
 /**
  * Normalize tool call ID for cross-provider compatibility.
  * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.

package/dist/types/types.d.ts

@@ -982,6 +982,12 @@ export type AssistantRetryRecovery = {
 export interface ContextSnapshot {
     promptTokens: number;
     nonMessageTokens: number;
+    /**
+     * Estimated tool-schema tokens included in `nonMessageTokens` (0 when the
+     * model defers schemas server-side). Lets a later model whose schema policy
+     * differs rebase the provider anchor instead of inheriting its schemas.
+     */
+    toolSchemaTokens?: number;
     /** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
     historyRewriteTokensRemoved?: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.11.0",
+	"version": "18.11.1",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.11.0",
-		"@oh-my-pi/pi-catalog": "18.11.0",
-		"@oh-my-pi/pi-natives": "18.11.0",
-		"@oh-my-pi/pi-utils": "18.11.0",
-		"@oh-my-pi/pi-wire": "18.11.0"
+		"@oh-my-pi/omptype": "18.11.1",
+		"@oh-my-pi/pi-catalog": "18.11.1",
+		"@oh-my-pi/pi-natives": "18.11.1",
+		"@oh-my-pi/pi-utils": "18.11.1",
+		"@oh-my-pi/pi-wire": "18.11.1"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth-broker/remote-store.ts

@@ -3,9 +3,9 @@
  * snapshot. Refresh tokens never leave the broker; mutating methods (`replace*`,
  * `upsert*`, `delete*ForProvider`) throw because login flows are server-side.
  *
- * Cache (`getCache`/`setCache`/`cleanExpiredCache`) is in-memory and ephemeral —
- * usage reports cache TTL is 5 minutes per credential, so durability across
- * runs isn't required.
+ * Cache (`getCache`/`setCache`/`cleanExpiredCache`) is in-memory and ephemeral.
+ * The bounded hot set preserves recently used session pins without keeping
+ * every gateway client's 30-day sticky row resident.
  */
 import * as os from "node:os";
 import { getAppName, getInstallId, logger, postmortem } from "@oh-my-pi/pi-utils";
@@ -36,6 +36,11 @@ import type {
 	SnapshotStreamEvent,
 } from "./types";
 
+// Bound both the number of distinct session pins and the size of caller-supplied
+// keys/values; an evicted session falls back to normal credential selection.
+const REMOTE_CACHE_MAX_ENTRIES = 4096;
+const REMOTE_CACHE_MAX_CHARACTERS = 4 * 1024 * 1024;
+
 /**
  * Per-provider OAuth identities visible to this trusted broker client.
  * Missing providers are unrestricted; an empty set excludes that provider's
@@ -289,6 +294,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	/** Present while the background loop is parked; resolved by `#noteActivity` or `close()`. */
 	#activityWakeup: PromiseWithResolvers<void> | null = null;
 	#cache: Map<string, CacheEntry> = new Map();
+	#cacheCharacters = 0;
 	#usageCache?: UsageCacheEntry;
 	#usageInflight?: Promise<UsageReport[] | null>;
 	#credentialBlockReconcileAfter: Map<string, number> = new Map();
@@ -1177,28 +1183,46 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		const entry = this.#cache.get(key);
 		if (!entry) return null;
 		if (entry.expiresAtSec * 1000 <= Date.now()) {
-			this.#cache.delete(key);
+			this.#deleteCache(key);
 			return null;
 		}
+		this.#cache.delete(key);
+		this.#cache.set(key, entry);
 		return entry.value;
 	}
 
 	setCache(key: string, value: string, expiresAtSec: number): void {
 		this.#noteActivity();
+		this.#deleteCache(key);
+		const size = key.length + value.length;
+		if (size > REMOTE_CACHE_MAX_CHARACTERS) return;
 		this.#cache.set(key, { value, expiresAtSec });
+		this.#cacheCharacters += size;
+		while (this.#cache.size > REMOTE_CACHE_MAX_ENTRIES || this.#cacheCharacters > REMOTE_CACHE_MAX_CHARACTERS) {
+			const oldest = this.#cache.keys().next().value;
+			if (oldest === undefined) break;
+			this.#deleteCache(oldest);
+		}
+	}
+
+	#deleteCache(key: string): void {
+		const entry = this.#cache.get(key);
+		if (!entry) return;
+		this.#cacheCharacters -= key.length + entry.value.length;
+		this.#cache.delete(key);
 	}
 
 	/** Drop all cache rows whose keys start with the supplied prefix. */
 	deleteCachePrefix(prefix: string): void {
 		for (const key of this.#cache.keys()) {
-			if (key.startsWith(prefix)) this.#cache.delete(key);
+			if (key.startsWith(prefix)) this.#deleteCache(key);
 		}
 	}
 
 	cleanExpiredCache(): void {
 		const nowSec = Math.floor(Date.now() / 1000);
 		for (const [key, entry] of this.#cache) {
-			if (entry.expiresAtSec <= nowSec) this.#cache.delete(key);
+			if (entry.expiresAtSec <= nowSec) this.#deleteCache(key);
 		}
 	}
 
@@ -1572,6 +1596,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		// process exiting right after close() still sends it; failures are dropped.
 		void this.#flushObservedUsage().finally(() => this.#cancelObservedUsageExitFlush?.());
 		this.#cache.clear();
+		this.#cacheCharacters = 0;
 		this.#usageOverlays.clear();
 	}
 }

package/src/auth-gateway/routes/images.ts

@@ -2,6 +2,7 @@ import { calculateCost } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
 import { classifyGatewayError } from "../../error/gateway";
 import { generateImage } from "../../images";
+import { validateImageInput } from "../../images/shared";
 import * as imagesServer from "../../providers/images-server";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
@@ -49,6 +50,7 @@ async function handleImages(
 	let parsed: imagesServer.ImagesParsedRequest;
 	try {
 		parsed = await imagesServer.parseRequest(body, kind);
+		for (const image of parsed.request.inputImages ?? []) validateImageInput(image);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return imagesServer.formatError(400, "invalid_request_error", message);

package/src/auth-gateway/routes/systemone.ts

@@ -13,8 +13,9 @@
  */
 import { calculateCost } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
+import * as AIError from "../../error";
 import { classifyGatewayError } from "../../error/gateway";
-import { createNativeJudge, isJudgmentApi } from "../../judgment/native";
+import { checkNativeJudgmentImages, createNativeJudge, isJudgmentApi } from "../../judgment/native";
 import * as systemOne from "../../providers/systemone-server";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
@@ -66,6 +67,16 @@ export async function handleSystemOne(
 			`Model ${parsed.modelId} does not answer System One judgments`,
 		);
 	}
+	// Model capability and dialect caps are known locally: reject before credential lookup or refresh.
+	try {
+		checkNativeJudgmentImages(model, parsed.request.images ?? []);
+	} catch (error) {
+		return systemOne.formatError(
+			422,
+			"invalid_request_error",
+			error instanceof Error ? error.message : String(error),
+		);
+	}
 	const client = resolveClientIdentity(req.headers);
 	// Judgments carry no conversation to derive a session from. One sticky
 	// session per model keeps credential selection stable across calls and
@@ -117,7 +128,11 @@ export async function handleSystemOne(
 		return json(200, body, gatewayResponseHeaders(model, { requestId, costUsd: result.usage.cost.total, startedAt }));
 	} catch (error) {
 		if (controller.signal.aborted) return aborted();
-		const classified = classifyGatewayError(error);
+		const message = error instanceof Error ? error.message : String(error);
+		const classified =
+			error instanceof AIError.ValidationError
+				? { status: 422, type: "invalid_request_error", message }
+				: classifyGatewayError(error);
 		logger.warn("auth-gateway judgment failed", { format: "systemone", error: classified.message, peer });
 		return systemOne.formatError(classified.status, classified.type, classified.message);
 	}

package/src/error/flags.ts

@@ -224,7 +224,7 @@ export function isCodexSteerRejection(message: { api?: Api; errorMessage?: strin
  * network connection", #15385).
  */
 export const TRANSIENT_TRANSPORT_PATTERN =
-	/\b(?:no[_ -]?capacity|(?:high|peak)[ _-]?demand|(?:at|over|insufficient)[ _-]?capacity|capacity[ _-]?(?:exceeded|exhausted)|peak[ _-]?load)\b|overloaded|provider.?returned.?error|rate.?limit|too many requests|auth-gateway\s+5\d{2}(?=[:\s]|$)|\b(?:429|500|502|503|504)\b|service.?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|unable.?to.?connect\.\s*is the computer able to access the url\?|other side closed|use of closed network connection|fetch failed|upstream.?connect|upstream.?request.?failed|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)|nghttp2_(?:internal_error|refused_stream)|stream closed with error code nghttp2_(?:internal_error|refused_stream)|malformed.?function.?call/i;
+	/\b(?:no[_ -]?capacity|(?:high|peak)[ _-]?demand|(?:at|over|insufficient)[ _-]?capacity|capacity[ _-]?(?:exceeded|exhausted)|peak[ _-]?load)\b|overloaded|provider.?returned.?error|rate.?limit|too many requests|auth-gateway\s+5\d{2}(?=[:\s]|$)|\b(?:429|500|502|503|504)\b|service.?unavailable|temporar(?:y|ily)[ _-]?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|unable.?to.?connect\.\s*is the computer able to access the url\?|other side closed|use of closed network connection|fetch failed|upstream.?connect|upstream.?request.?failed|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)|nghttp2_(?:internal_error|refused_stream)|stream closed with error code nghttp2_(?:internal_error|refused_stream)|malformed.?function.?call/i;
 const AUTH_FAILURE_PATTERN =
 	/\b(?:401|403|unauthorized|forbidden|authentication|auth[_ ]?unavailable|no auth available|(?:invalid|no)[_ ]?api[_ ]?key)\b/i;
 const MALFORMED_FUNCTION_CALL_PATTERN = /\bmalformed.?function.?call\b/i;
@@ -1100,7 +1100,7 @@ export function isTransientStreamParseError(error: unknown): boolean {
  * non-terminal status treat it as transient (#11805).
  */
 const STREAM_DROP_PATTERN =
-	/stream disconnected before completion|stream closed before response\.completed|stream was interrupted|stream ended before terminal (?:chunk|completion event)|socket disconnected before secure tls connection/i;
+	/stream disconnected before completion|(?:stream|websocket) closed before response\.completed|stream was interrupted|stream ended before terminal (?:chunk|completion event)|socket disconnected before secure tls connection/i;
 
 /**
  * Transport stream-drop diagnostic (see {@link STREAM_DROP_PATTERN}). Unlike

package/src/images/codex-format-directive.md

@@ -0,0 +1,3 @@
+{{{prompt}}}
+
+Output format: {{shape}} image, {{#if pixels}}{{width}}x{{height}} pixels{{else}}{{width}}:{{height}} aspect ratio{{/if}}.

package/src/images/google-antigravity.ts

@@ -8,7 +8,7 @@ import { getAntigravityUserAgent } from "@oh-my-pi/pi-catalog/wire/gemini-header
 import { readSseJson } from "@oh-my-pi/pi-utils";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import { errorMessage, ImageApiError, usageFromWire } from "./shared";
+import { errorMessage, ImageApiError, usageFromWire, validateImageInput } from "./shared";
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 const IMAGE_SYSTEM_INSTRUCTION =
@@ -138,6 +138,7 @@ export async function generateAntigravityImage(
 	request: ImageGenerationRequest,
 	options: ImageGenerationOptions,
 ): Promise<ImageGenerationResult> {
+	for (const image of request.inputImages ?? []) validateImageInput(image);
 	const fetchImpl = options.fetch ?? fetch;
 	const response = await withAuth(
 		options.apiKey,

package/src/images/google-generative-ai.ts

@@ -1,7 +1,7 @@
 import type { Model } from "@oh-my-pi/pi-catalog/types";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
-import { errorMessage, ImageApiError, imageBaseUrl, modelHeaders, usageFromWire } from "./shared";
+import { errorMessage, ImageApiError, imageBaseUrl, modelHeaders, usageFromWire, validateImageInput } from "./shared";
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 interface GeminiPart {
@@ -20,7 +20,9 @@ export async function generateGoogleImage(
 	options: ImageGenerationOptions,
 ): Promise<ImageGenerationResult> {
 	const fetchImpl = options.fetch ?? fetch;
-	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = (request.inputImages ?? []).map(image => ({
+	const inputImages = request.inputImages ?? [];
+	for (const image of inputImages) validateImageInput(image);
+	const parts: Array<{ text?: string; inlineData?: GeneratedImage }> = inputImages.map(image => ({
 		inlineData: image,
 	}));
 	parts.push({ text: request.prompt });

package/src/images/openai-hosted.ts

@@ -7,7 +7,7 @@ import {
 	OPENAI_HEADERS,
 	URL_PATHS,
 } from "@oh-my-pi/pi-catalog/wire/codex";
-import { readSseJson, USER_AGENT } from "@oh-my-pi/pi-utils";
+import { prompt, readSseJson, USER_AGENT } from "@oh-my-pi/pi-utils";
 import { withAuth } from "../auth-retry";
 import * as AIError from "../error";
 import { applySessionHeader } from "../providers/inference-headers";
@@ -20,6 +20,7 @@ import {
 	toDataUrl,
 	usageFromWire,
 } from "./shared";
+import codexFormatDirective from "./codex-format-directive.md" with { type: "text" };
 import type { GeneratedImage, ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
@@ -143,6 +144,27 @@ async function parseSse(response: Response, signal?: AbortSignal): Promise<Image
 	return collectResponse(completed?.output?.length ? completed : { ...completed, output: fallbackOutput });
 }
 
+/**
+ * The Codex backend runs its image tool with `size: "auto"`, ignoring the requested `size`, and
+ * shapes the canvas from the prompt alone. Spell the requested shape out so it is honored.
+ */
+function withCodexFormatDirective(request: ImageGenerationRequest): string {
+	const dimensions = request.imageSize?.match(/^(\d+)x(\d+)$/);
+	const ratio = dimensions ? undefined : request.aspectRatio?.match(/^(\d+):(\d+)$/);
+	const match = dimensions ?? ratio;
+	if (!match) return request.prompt;
+	const width = Number(match[1]);
+	const height = Number(match[2]);
+	const shape = width === height ? "square" : width > height ? "landscape" : "portrait";
+	return prompt.render(codexFormatDirective, {
+		prompt: request.prompt,
+		shape,
+		width,
+		height,
+		pixels: dimensions !== undefined,
+	});
+}
+
 export async function generateHostedImage(
 	model: Model,
 	request: ImageGenerationRequest,
@@ -154,7 +176,8 @@ export async function generateHostedImage(
 		throw new AIError.ValidationError(`Hosted image carrier API ${carrier.api} is unsupported`);
 	}
 	const stream = carrier.api === "openai-codex-responses";
-	const content: Array<Record<string, unknown>> = [{ type: "input_text", text: request.prompt }];
+	const inputText = stream ? withCodexFormatDirective(request) : request.prompt;
+	const content: Array<Record<string, unknown>> = [{ type: "input_text", text: inputText }];
 	for (const image of request.inputImages ?? []) {
 		content.push({ type: "input_image", detail: "auto", image_url: toDataUrl(image) });
 	}

package/src/images/openai-images.ts

@@ -8,6 +8,7 @@ import {
 	postMultipart,
 	resolveOpenAIImageSize,
 	toDataUrl,
+	validateImageInput,
 } from "./shared";
 import type { ImageGenerationOptions, ImageGenerationRequest, ImageGenerationResult } from "./types";
 
@@ -85,6 +86,7 @@ export async function generateOpenAIImage(
 				form.set("response_format", "b64_json");
 				if (size) form.set("size", size);
 				for (const image of inputImages) {
+					validateImageInput(image);
 					form.append("image", new File([Buffer.from(image.data, "base64")], "image", { type: image.mimeType }));
 				}
 				response = await postMultipart({