@oh-my-pi/pi-ai 16.0.7 → 16.0.9

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [16.0.9] - 2026-06-18
+
+### Fixed
+
+- Fixed OAuth login replacing all other active accounts for the same provider, allowing multiple OAuth accounts to coexist concurrently.
+- Fixed legacy `api_key` credentials not being replaced/disabled atomically upon upgrading to OAuth login.
+- Fixed a logic issue where AuthStorage lost session-to-credential stickiness upon CLI restarts, causing cold-starts for server-side prompt cache (KV cache) and wasting tokens.
+- Fixed GitHub Copilot Responses requests rejecting image inputs that carry the `detail: "original"` hint with an HTTP 400 by degrading the hint to `"auto"` for hosts that do not support it; other hosts still preserve native-resolution frames (snapcompact). ([#2822](https://github.com/can1357/oh-my-pi/issues/2822))
+
+## [16.0.8] - 2026-06-18
+
+### Fixed
+
+- Improved reliability of auth-broker snapshot loading by implementing a robust manual schema check
+- Fixed MCP tool argument validation to drop optional empty-string parameters before schema validation, matching the existing optional null handling and avoiding pattern/type failures for omitted model-filled fields. ([#2981](https://github.com/can1357/oh-my-pi/issues/2981))
+- Fixed API-key credential replacement to hard-delete superseded disabled `api_key` rows so `auth_credentials` does not grow indefinitely after key rotation. ([#2941](https://github.com/can1357/oh-my-pi/issues/2941))
+- Fixed Cursor provider streaming to close text blocks before tool calls so post-tool text opens a new content block and TUI transcript cards render inline instead of grouped near the bottom. ([#2924](https://github.com/can1357/oh-my-pi/issues/2924))
+
 ## [16.0.7] - 2026-06-18
 
 ### Changed

package/dist/types/index.d.ts

@@ -1,8 +1,8 @@
 export { type Type, type } from "arktype";
 export { type ZodType, z } from "zod/v4";
 export * from "./api-registry";
-export * from "./auth-broker";
-export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
+export type * from "./auth-broker";
+export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";

package/dist/types/providers/openai-shared.d.ts

@@ -341,11 +341,12 @@ export declare function repairOrphanResponsesToolOutputs(input: ResponseInput):
  * {@link repairOrphanResponsesToolOutputs}.
  */
 export declare function repairOrphanResponsesToolCalls(input: ResponseInput): ResponseInput;
-export declare function convertResponsesInputContent(content: string | Array<TextContent | ImageContent>, supportsImages: boolean): ResponseInputContent[] | undefined;
+export declare function convertResponsesInputContent(content: string | Array<TextContent | ImageContent>, supportsImages: boolean, supportsImageDetailOriginal: boolean): ResponseInputContent[] | undefined;
 export interface BuildResponsesInputOptions<TApi extends Api> {
     model: Model<TApi>;
     context: Context;
     strictResponsesPairing: boolean;
+    supportsImageDetailOriginal: boolean;
     systemRole?: "system" | "developer";
     nativeHistory?: {
         replay: boolean;
@@ -357,7 +358,7 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
 }
 export declare function buildResponsesInput<TApi extends Api>(options: BuildResponsesInputOptions<TApi>): ResponseInput;
 export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>): ResponseInput;
-export declare function appendResponsesToolResultMessages<TApi extends Api>(messages: ResponseInput, toolResult: ToolResultMessage, model: Model<TApi>, strictResponsesPairing: boolean, knownCallIds: ReadonlySet<string>, customCallIds?: ReadonlySet<string>): void;
+export declare function appendResponsesToolResultMessages<TApi extends Api>(messages: ResponseInput, toolResult: ToolResultMessage, model: Model<TApi>, strictResponsesPairing: boolean, supportsImageDetailOriginal: boolean, knownCallIds: ReadonlySet<string>, customCallIds?: ReadonlySet<string>): void;
 /**
  * Per-block accumulation helpers shared by the two Responses decode loops —
  * {@link processResponsesStream} (generic Responses) and the Codex stream

package/dist/types/utils/validation.d.ts

@@ -10,7 +10,8 @@ export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): Too
 /**
  * Validates tool call arguments against the tool's schema (Zod or plain JSON
  * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
- * containers, null-for-optional, null-for-default) before declaring failure.
+ * containers, null/invalid-empty-string-for-optional, null-for-default) before
+ * declaring failure.
  *
  * @throws Error with a formatted message when validation cannot be reconciled.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.0.7",
+	"version": "16.0.9",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,8 +38,8 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.0.7",
-		"@oh-my-pi/pi-utils": "16.0.7",
+		"@oh-my-pi/pi-catalog": "16.0.9",
+		"@oh-my-pi/pi-utils": "16.0.9",
 		"arktype": "^2.2.0",
 		"partial-json": "^0.1.7",
 		"zod": "^4"

package/src/auth-broker/snapshot-cache.ts

@@ -9,9 +9,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent, logger } from "@oh-my-pi/pi-utils";
-import { type } from "arktype";
 import type { SnapshotResponse } from "./types";
-import { snapshotResponseSchema } from "./wire-schemas";
 
 const MAGIC = new Uint8Array([0x4f, 0x4d, 0x50, 0x53]); // "OMPS"
 const VERSION = 1;
@@ -40,6 +38,25 @@ export interface WriteAuthBrokerSnapshotCacheOptions {
 	snapshot: SnapshotResponse;
 }
 
+/**
+ * Cheap structural guard for a decrypted cache payload. The bytes are already
+ * AES-256-GCM authenticated, so this only rejects shape/version drift (a cache
+ * written by a different omp build, or a buggy write) — not tampering. A
+ * mismatch returns null so the caller refetches a fresh snapshot.
+ */
+function isSnapshotResponseShape(v: unknown): v is SnapshotResponse {
+	if (typeof v !== "object" || v === null) return false;
+	const o = v as Record<string, unknown>;
+	return (
+		typeof o.generation === "number" &&
+		typeof o.generatedAt === "number" &&
+		typeof o.serverNowMs === "number" &&
+		typeof o.refresher === "object" &&
+		o.refresher !== null &&
+		Array.isArray(o.credentials)
+	);
+}
+
 export async function readAuthBrokerSnapshotCache(
 	opts: ReadAuthBrokerSnapshotCacheOptions,
 ): Promise<SnapshotResponse | null> {
@@ -56,12 +73,11 @@ export async function readAuthBrokerSnapshotCache(
 		const plaintext = await decryptCachePayload(data, opts.token, opts.url);
 		if (!plaintext) return null;
 		const parsed: unknown = JSON.parse(TEXT_DECODER.decode(plaintext));
-		const result = snapshotResponseSchema(parsed);
-		if (result instanceof type.errors) {
+		if (!isSnapshotResponseShape(parsed)) {
 			logger.debug("auth-broker snapshot cache schema invalid", { path: opts.path });
 			return null;
 		}
-		const snapshot = result;
+		const snapshot = parsed;
 		const now = opts.now?.() ?? Date.now();
 		if (now - snapshot.generatedAt > opts.ttlMs) return null;
 		return snapshot;

package/src/auth-storage.ts

@@ -1352,6 +1352,19 @@ export class AuthStorage {
 		const sessionMap = this.#sessionLastCredential.get(provider) ?? new Map();
 		sessionMap.set(sessionId, { type, index });
 		this.#sessionLastCredential.set(provider, sessionMap);
+
+		try {
+			const credentialId = this.#getStoredCredentials(provider)[index]?.id;
+			if (credentialId !== undefined) {
+				const cacheKey = `session:sticky:${provider}:${sessionId}`;
+				const cacheValue = JSON.stringify({ type, index, credentialId });
+				// Expires in 30 days
+				const expiresAtSec = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
+				this.#store.setCache(cacheKey, cacheValue, expiresAtSec);
+			}
+		} catch (err) {
+			logger.debug("Failed to write session sticky credential to persistent store cache", { err });
+		}
 	}
 
 	/** Retrieves the last credential used by a session. */
@@ -1360,17 +1373,59 @@ export class AuthStorage {
 		sessionId: string | undefined,
 	): { type: AuthCredential["type"]; index: number } | undefined {
 		if (!sessionId) return undefined;
-		return this.#sessionLastCredential.get(provider)?.get(sessionId);
+		let sessionMap = this.#sessionLastCredential.get(provider);
+		if (sessionMap?.has(sessionId)) {
+			return sessionMap.get(sessionId);
+		}
+		try {
+			const cacheKey = `session:sticky:${provider}:${sessionId}`;
+			const raw = this.#store.getCache(cacheKey);
+			if (raw) {
+				const val = JSON.parse(raw) as { type: AuthCredential["type"]; index: number; credentialId?: number };
+
+				if (val.credentialId !== undefined) {
+					const stored = this.#getStoredCredentials(provider);
+					const actualIndex = stored.findIndex(entry => entry.id === val.credentialId);
+					if (actualIndex === -1 || stored[actualIndex]?.credential.type !== val.type) {
+						this.#store.setCache(cacheKey, "", 0);
+						return undefined;
+					}
+					val.index = actualIndex;
+				} else {
+					// Fallback: drop unsafe index-only cache rows to prevent wrong-account routing
+					this.#store.setCache(cacheKey, "", 0);
+					return undefined;
+				}
+
+				if (!sessionMap) {
+					sessionMap = new Map();
+					this.#sessionLastCredential.set(provider, sessionMap);
+				}
+				const sessionVal = { type: val.type, index: val.index };
+				sessionMap.set(sessionId, sessionVal);
+				return sessionVal;
+			}
+		} catch (err) {
+			logger.debug("Failed to read session sticky credential from persistent store cache", { err });
+		}
+		return undefined;
 	}
 
 	/** Clears the last credential used by a session for a provider. */
 	#clearSessionCredential(provider: string, sessionId: string | undefined): void {
 		if (!sessionId) return;
 		const sessionMap = this.#sessionLastCredential.get(provider);
-		if (!sessionMap) return;
-		sessionMap.delete(sessionId);
-		if (sessionMap.size === 0) {
-			this.#sessionLastCredential.delete(provider);
+		if (sessionMap) {
+			sessionMap.delete(sessionId);
+			if (sessionMap.size === 0) {
+				this.#sessionLastCredential.delete(provider);
+			}
+		}
+		try {
+			const cacheKey = `session:sticky:${provider}:${sessionId}`;
+			this.#store.setCache(cacheKey, "", 0);
+		} catch (err) {
+			logger.debug("Failed to clear session sticky credential from persistent store cache", { err });
 		}
 	}
 
@@ -1549,6 +1604,17 @@ export class AuthStorage {
 		return rows;
 	}
 
+	async #upsertOAuthCredential(provider: string, credential: OAuthCredential): Promise<void> {
+		const stored = this.#store.upsertAuthCredentialRemote
+			? await this.#store.upsertAuthCredentialRemote(provider, credential)
+			: this.#store.upsertAuthCredentialForProvider(provider, credential);
+		this.#setStoredCredentials(
+			provider,
+			stored.map(entry => ({ id: entry.id, credential: entry.credential })),
+		);
+		this.#resetProviderAssignments(provider);
+	}
+
 	/**
 	 * Remove credential for a provider.
 	 */
@@ -1786,10 +1852,10 @@ export class AuthStorage {
 			return;
 		}
 		const newCredential: OAuthCredential = { type: "oauth", ...result };
-		// Use set() instead of #upsertOAuthCredential to replace ALL existing credentials
-		// (including legacy api_key rows from older versions) with the new OAuth credential.
-		// This ensures getApiKey() doesn't match an old api_key row before the new OAuth row.
-		await this.set(def.storeCredentialsAs ?? provider, newCredential);
+		// Use #upsertOAuthCredential to upsert the new credential.
+		// Any legacy api_key rows from older versions will be cleaned up so they do not
+		// shadow the new OAuth row, while preserving other active OAuth credentials.
+		await this.#upsertOAuthCredential(def.storeCredentialsAs ?? provider, newCredential);
 	}
 
 	/**
@@ -4916,6 +4982,14 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 				identityKey: resolveRowCredentialIdentityKey(providerName, row),
 			}));
 
+			if (item.type === "oauth") {
+				for (const row of existing) {
+					if (row.credential && row.credential.type === "api_key") {
+						this.#deleteStmt.run("replaced by oauth login", row.id);
+					}
+				}
+			}
+
 			let targetId: number | null = null;
 			for (const row of existing) {
 				if (!matchesReplacementCredential(providerName, row.credential, row.identityKey, item)) continue;
@@ -4953,21 +5027,30 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	/**
-	 * Hard-deletes disabled rows for a provider when an active row with the same identity exists.
-	 * This prevents unbounded accumulation of soft-deleted credentials while preserving
-	 * disabled rows that have no active replacement (safety net for recovery).
+	 * Hard-deletes disabled rows for a provider when an active replacement exists.
+	 * OAuth credentials match by identity key; API keys match by provider and type.
+	 * Disabled rows without an active same-type replacement remain recoverable.
 	 */
 	#purgeSupersededDisabledRows(provider: string, activeRows: StoredAuthCredential[]): void {
 		try {
+			let hasActiveApiKey = false;
 			const activeIdentityKeys = new Set<string>();
 			for (const row of activeRows) {
+				if (row.credential.type === "api_key") {
+					hasActiveApiKey = true;
+					continue;
+				}
 				const identityKey = resolveCredentialIdentityKey(provider, row.credential);
 				if (identityKey) activeIdentityKeys.add(identityKey);
 			}
-			if (activeIdentityKeys.size === 0) return;
+			if (!hasActiveApiKey && activeIdentityKeys.size === 0) return;
 
 			const disabledRows = this.#listDisabledByProviderStmt.all(provider) as AuthRow[];
 			for (const row of disabledRows) {
+				if (hasActiveApiKey && row.credential_type === "api_key") {
+					this.#hardDeleteStmt.run(row.id);
+					continue;
+				}
 				const identityKey = resolveRowCredentialIdentityKey(provider, row);
 				if (identityKey && activeIdentityKeys.has(identityKey)) {
 					this.#hardDeleteStmt.run(row.id);

package/src/index.ts

@@ -1,8 +1,8 @@
 export { type Type, type } from "arktype";
 export { type ZodType, z } from "zod/v4";
 export * from "./api-registry";
-export * from "./auth-broker";
-export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
+export type * from "./auth-broker";
+export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";

package/src/providers/azure-openai-responses.ts

@@ -297,6 +297,7 @@ function buildParams(
 		model,
 		context,
 		strictResponsesPairing: true,
+		supportsImageDetailOriginal: model.compat.supportsImageDetailOriginal,
 		systemRole,
 		includeThinkingSignatures: true,
 		developerStringContent: true,

package/src/providers/cursor.ts

@@ -548,24 +548,8 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 				}
 			});
 
-			if (state.currentTextBlock) {
-				const idx = output.content.indexOf(state.currentTextBlock);
-				stream.push({
-					type: "text_end",
-					contentIndex: idx,
-					content: state.currentTextBlock.text,
-					partial: output,
-				});
-			}
-			if (state.currentThinkingBlock) {
-				const idx = output.content.indexOf(state.currentThinkingBlock);
-				stream.push({
-					type: "thinking_end",
-					contentIndex: idx,
-					content: state.currentThinkingBlock.thinking,
-					partial: output,
-				});
-			}
+			endCurrentTextBlock(output, stream, state);
+			endCurrentThinkingBlock(output, stream, state);
 			if (state.currentToolCall) {
 				const idx = output.content.indexOf(state.currentToolCall);
 				state.currentToolCall.arguments = parseStreamingJson(state.currentToolCall.partialJson);
@@ -1972,6 +1956,38 @@ export function mergeCursorMcpToolCallArgs(
 	return merged;
 }
 
+function endCurrentTextBlock(output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState): void {
+	const block = state.currentTextBlock;
+	if (!block) return;
+	const idx = output.content.indexOf(block);
+	delete (block as { index?: number }).index;
+	stream.push({
+		type: "text_end",
+		contentIndex: idx,
+		content: block.text,
+		partial: output,
+	});
+	state.setTextBlock(null);
+}
+
+function endCurrentThinkingBlock(
+	output: AssistantMessage,
+	stream: AssistantMessageEventStream,
+	state: BlockState,
+): void {
+	const block = state.currentThinkingBlock;
+	if (!block) return;
+	const idx = output.content.indexOf(block);
+	delete (block as { index?: number }).index;
+	stream.push({
+		type: "thinking_end",
+		contentIndex: idx,
+		content: block.thinking,
+		partial: output,
+	});
+	state.setThinkingBlock(null);
+}
+
 /** Exported for tests: drives one Cursor interaction update through the streaming state machine. */
 export function processInteractionUpdate(
 	update: any,
@@ -2017,18 +2033,10 @@ export function processInteractionUpdate(
 		const idx = output.content.indexOf(state.currentThinkingBlock!);
 		stream.push({ type: "thinking_delta", contentIndex: idx, delta, partial: output });
 	} else if (updateCase === "thinkingCompleted") {
-		if (state.currentThinkingBlock) {
-			const idx = output.content.indexOf(state.currentThinkingBlock);
-			delete (state.currentThinkingBlock as any).index;
-			stream.push({
-				type: "thinking_end",
-				contentIndex: idx,
-				content: state.currentThinkingBlock.thinking,
-				partial: output,
-			});
-			state.setThinkingBlock(null);
-		}
+		endCurrentThinkingBlock(output, stream, state);
 	} else if (updateCase === "toolCallStarted") {
+		endCurrentTextBlock(output, stream, state);
+		endCurrentThinkingBlock(output, stream, state);
 		const toolCall = update.message.value.toolCall;
 		if (toolCall) {
 			const mcpCall = toolCall.mcpToolCall;

package/src/providers/openai-codex-responses.ts

@@ -3253,7 +3253,15 @@ function convertMessages(model: Model<"openai-codex-responses">, context: Contex
 		}
 
 		if (msg.role === "toolResult") {
-			appendResponsesToolResultMessages(messages, msg, model, false, knownCallIds, customCallIds);
+			appendResponsesToolResultMessages(
+				messages,
+				msg,
+				model,
+				false,
+				model.compat.supportsImageDetailOriginal,
+				knownCallIds,
+				customCallIds,
+			);
 		}
 
 		msgIndex += 1;
@@ -3271,7 +3279,10 @@ function normalizeInputMessageContent(
 		return [{ type: "input_text", text: content.toWellFormed() }];
 	}
 
-	return convertResponsesInputContent(content, model.input.includes("image")) ?? [];
+	return (
+		convertResponsesInputContent(content, model.input.includes("image"), model.compat.supportsImageDetailOriginal) ??
+		[]
+	);
 }
 
 /** @internal Exported for tests. */

package/src/providers/openai-responses.ts

@@ -687,6 +687,7 @@ export function buildParams(
 		model,
 		context,
 		strictResponsesPairing,
+		supportsImageDetailOriginal: model.compat.supportsImageDetailOriginal,
 		nativeHistory: {
 			replay: shouldReplayNativeHistory,
 			filterReasoning: policy.reasoning.filterReasoningHistory,

package/src/providers/openai-shared.ts

@@ -1178,9 +1178,24 @@ export function repairOrphanResponsesToolCalls(input: ResponseInput): ResponseIn
 	return repaired;
 }
 
+/**
+ * Some Responses backends (notably GitHub Copilot) reject the OpenAI image
+ * `detail: "original"` value with a 400. When the model does not advertise
+ * support for it, degrade `"original"` to `"auto"` so the request still goes
+ * through with the closest valid fidelity instead of failing outright. See #2822.
+ */
+function clampResponsesImageDetail(
+	detail: ImageContent["detail"],
+	supportsImageDetailOriginal: boolean,
+): ResponseInputImage["detail"] {
+	const resolved = detail ?? "auto";
+	return resolved === "original" && !supportsImageDetailOriginal ? "auto" : resolved;
+}
+
 export function convertResponsesInputContent(
 	content: string | Array<TextContent | ImageContent>,
 	supportsImages: boolean,
+	supportsImageDetailOriginal: boolean,
 ): ResponseInputContent[] | undefined {
 	if (typeof content === "string") {
 		if (content.trim().length === 0) return undefined;
@@ -1200,7 +1215,7 @@ export function convertResponsesInputContent(
 	for (const item of imageBlocks) {
 		normalizedContent.push({
 			type: "input_image",
-			detail: item.detail ?? "auto",
+			detail: clampResponsesImageDetail(item.detail, supportsImageDetailOriginal),
 			image_url: `data:${item.mimeType};base64,${item.data}`,
 		} satisfies ResponseInputImage);
 	}
@@ -1217,6 +1232,7 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
 	model: Model<TApi>;
 	context: Context;
 	strictResponsesPairing: boolean;
+	supportsImageDetailOriginal: boolean;
 	systemRole?: "system" | "developer";
 	nativeHistory?: {
 		replay: boolean;
@@ -1267,7 +1283,11 @@ export function buildResponsesInput<TApi extends Api>(options: BuildResponsesInp
 				msgIndex++;
 				continue;
 			}
-			const content = convertResponsesInputContent(msg.content, options.model.input.includes("image"));
+			const content = convertResponsesInputContent(
+				msg.content,
+				options.model.input.includes("image"),
+				options.supportsImageDetailOriginal,
+			);
 			if (!content) continue;
 			messages.push({
 				role: "user",
@@ -1318,6 +1338,7 @@ export function buildResponsesInput<TApi extends Api>(options: BuildResponsesInp
 				msg,
 				options.model,
 				options.strictResponsesPairing,
+				options.supportsImageDetailOriginal,
 				knownCallIds,
 				customCallIds,
 			);
@@ -1419,6 +1440,7 @@ export function appendResponsesToolResultMessages<TApi extends Api>(
 	toolResult: ToolResultMessage,
 	model: Model<TApi>,
 	strictResponsesPairing: boolean,
+	supportsImageDetailOriginal: boolean,
 	knownCallIds: ReadonlySet<string>,
 	customCallIds?: ReadonlySet<string>,
 ): void {
@@ -1475,7 +1497,7 @@ export function appendResponsesToolResultMessages<TApi extends Api>(
 		if (block.type === "image") {
 			contentParts.push({
 				type: "input_image",
-				detail: block.detail ?? "auto",
+				detail: clampResponsesImageDetail(block.detail, supportsImageDetailOriginal),
 				image_url: `data:${block.mimeType};base64,${block.data}`,
 			} satisfies ResponseInputImage);
 		}

package/src/utils/validation.ts

@@ -764,10 +764,13 @@ function normalizeOptionalNullsForSchema(
 		if (!(key in nextValue)) continue;
 		const currentValue = nextValue[key];
 		const isNullish = currentValue === null || currentValue === "null";
+		const isInvalidEmptyString =
+			currentValue === "" && !required.has(key) && !branchMatchesSchema(propertySchema, currentValue);
 
-		// Strip null and the string "null" from optional fields.
-		// The LLM sometimes outputs string "null" to mean "no value".
-		if (isNullish && !required.has(key)) {
+		// Strip null/string "null" from optional fields, and strip empty
+		// strings only when the property schema would reject the explicit value.
+		// LLMs sometimes output these placeholders to mean "no value".
+		if ((isNullish || isInvalidEmptyString) && !required.has(key)) {
 			if (!changed) {
 				nextValue = { ...nextValue };
 				changed = true;
@@ -1281,7 +1284,8 @@ function truncateArgsForError(value: unknown): unknown {
 /**
  * Validates tool call arguments against the tool's schema (Zod or plain JSON
  * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
- * containers, null-for-optional, null-for-default) before declaring failure.
+ * containers, null/invalid-empty-string-for-optional, null-for-default) before
+ * declaring failure.
  *
  * @throws Error with a formatted message when validation cannot be reconciled.
  */
@@ -1290,9 +1294,10 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 	const ctx = getValidationContext(tool);
 	const { json } = ctx;
 
-	// Always normalize first — strip null and string "null" from optional
-	// fields and substitute defaults. Handles LLM outputting string "null"
-	// to mean "no value" even when validation would otherwise pass.
+	// Always normalize first — strip null/string "null" from optional fields,
+	// strip optional empty strings only when their property schema rejects the
+	// explicit value, and substitute defaults. Handles LLM outputting
+	// placeholders for "no value" even when validation would otherwise pass.
 	let normalizedArgs: unknown = originalArgs;
 	let changed = false;
 	const initialNormalization = normalizeOptionalNullsForSchema(json, normalizedArgs);