@cartanova/qgrid-ai-sdk 2.10.10 → 2.11.1

package/dist/index.js

@@ -1,15 +1,16 @@
+import { z } from "zod";
 import { Agent } from "undici";
 //#region src/envelope-stream-parser.ts
-const ESCAPE_MAP = {
-	"\"": "\"",
-	"\\": "\\",
-	"/": "/",
-	b: "\b",
-	f: "\f",
-	n: "\n",
-	r: "\r",
-	t: "	"
-};
+const ESCAPE_MAP = /* @__PURE__ */ new Map([
+	["\"", "\""],
+	["\\", "\\"],
+	["/", "/"],
+	["b", "\b"],
+	["f", "\f"],
+	["n", "\n"],
+	["r", "\r"],
+	["t", "	"]
+]);
 const LITERAL_CHARS = /[0-9a-zA-Z+\-.eE]/;
 function createEnvelopeStreamParser(answerKind) {
 	let action = null;
@@ -179,7 +180,7 @@ function createEnvelopeStreamParser(answerKind) {
 					unicode = "";
 					return;
 				}
-				const mapped = ESCAPE_MAP[c];
+				const mapped = ESCAPE_MAP.get(c);
 				if (mapped === void 0) {
 					discard = true;
 					return;
@@ -253,9 +254,300 @@ function createEnvelopeStreamParser(answerKind) {
 	} };
 }
 //#endregion
+//#region src/index.types.ts
+/**
+* `providerOptions.xai` for Grok models, cloned field-for-field from `@ai-sdk/xai`
+* (`xai-responses-language-model-options.ts`) so code written for `@ai-sdk/xai` keeps parsing.
+* Parsing only proves the shape; `mapXaiProviderOptions` decides which keys qgrid honors.
+*/
+const qgridXaiProviderOptionsSchema = z.object({
+	/**
+	* Constrains how hard a reasoning model thinks before responding. qgrid validates the value
+	* against the model's catalog effort set; `none` is rejected because the proxy always reasons.
+	*/
+	reasoningEffort: z.enum([
+		"none",
+		"low",
+		"medium",
+		"high",
+		"xhigh"
+	]).optional(),
+	/** Maximum number of agentic tool-calling turns. Rejected by qgrid. */
+	maxTurns: z.number().int().optional(),
+	/** Whether the model may call tools in parallel. @default true */
+	parallelToolCalls: z.boolean().optional(),
+	/** Cache key used to route requests with shared prompt prefixes. */
+	promptCacheKey: z.string().optional(),
+	/** Stable identifier used to attribute policy violations to an end user. Rejected by qgrid. */
+	safetyIdentifier: z.string().optional(),
+	serviceTier: z.enum(["default", "priority"]).optional(),
+	/** Rejected by qgrid: it always sends `store: false`. */
+	store: z.boolean().optional(),
+	/** Rejected by qgrid: it replays history itself. */
+	previousResponseId: z.string().optional(),
+	/** A unique identifier for the end user, used for abuse monitoring. Rejected by qgrid. */
+	user: z.string().optional(),
+	/** Rejected by qgrid: it fixes `include` itself. */
+	include: z.array(z.enum([
+		"file_search_call.results",
+		"web_search_call.action.sources",
+		"code_interpreter_call.outputs",
+		"reasoning.encrypted_content",
+		"no_inline_citations"
+	])).nullish()
+});
+const imageGenerationMetadataSchema = z.looseObject({
+	route: z.enum(["codex-images", "codex-responses"]),
+	model: z.string().optional(),
+	background: z.string().optional(),
+	quality: z.string().optional(),
+	size: z.string().optional(),
+	usage: z.looseObject({
+		input_tokens: z.number(),
+		output_tokens: z.number(),
+		total_tokens: z.number(),
+		input_tokens_details: z.looseObject({
+			image_tokens: z.number(),
+			text_tokens: z.number(),
+			cached_tokens: z.number().optional()
+		}).optional(),
+		output_tokens_details: z.looseObject({
+			image_tokens: z.number(),
+			text_tokens: z.number()
+		}).optional()
+	}).optional()
+});
+const queryContentPartSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("text"),
+		text: z.string()
+	}),
+	z.object({
+		type: z.literal("tool-call"),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		input: z.string()
+	}),
+	z.object({
+		type: z.literal("image"),
+		data: z.string(),
+		mediaType: z.enum([
+			"image/png",
+			"image/jpeg",
+			"image/webp"
+		]).optional(),
+		revisedPrompt: z.string().nullable().optional(),
+		generation: imageGenerationMetadataSchema.optional()
+	})
+]);
+const threadCoordSchema = z.looseObject({
+	workerId: z.number(),
+	threadId: z.string(),
+	epoch: z.number(),
+	systemHash: z.string().optional()
+});
+/**
+* Response of `/api/qgrid/query` and the stream `done` event. Content variants this SDK does not
+* know are skipped rather than rejected, so a newer server can add variants. The object stays
+* loose because `providerMetadata` is read by a separate schema.
+*/
+const queryOutputSchema = z.looseObject({
+	requestLogId: z.number().optional(),
+	text: z.string(),
+	content: z.array(z.looseObject({ type: z.string() })).optional().transform((items) => items?.flatMap((item) => {
+		const part = queryContentPartSchema.safeParse(item);
+		return part.success ? [part.data] : [];
+	})),
+	finishReason: z.enum(["stop", "tool-calls"]).optional(),
+	model: z.string().optional(),
+	requestedModel: z.string().optional(),
+	modelFallbacks: z.array(z.object({
+		trigger: z.literal("refusal"),
+		fromModel: z.string(),
+		toModel: z.string(),
+		category: z.string().optional(),
+		explanation: z.string().optional()
+	})).optional(),
+	tokenName: z.string().optional(),
+	usage: z.object({
+		input_tokens: z.number(),
+		output_tokens: z.number(),
+		reasoning_tokens: z.number().optional(),
+		cache_creation_input_tokens: z.number(),
+		cache_creation_5m_input_tokens: z.number().optional(),
+		cache_creation_1h_input_tokens: z.number().optional(),
+		cache_read_input_tokens: z.number()
+	}),
+	durationMs: z.number().optional(),
+	costUsd: z.number().optional(),
+	costSource: z.enum([
+		"provider",
+		"pricing_table",
+		"mixed"
+	]).optional(),
+	runContext: z.object({
+		requestLogId: z.number().optional(),
+		threadCoord: threadCoordSchema.optional()
+	}).optional()
+});
+//#endregion
+//#region src/grok-options.ts
+/**
+* How each documented `providerOptions.xai` key reaches the qgrid request.
+* faithful: same meaning, same name. transformed: renamed and validated. rejected: dropped with a warning.
+*/
+const XAI_PROVIDER_OPTION_CLASSIFICATION = {
+	reasoningEffort: {
+		kind: "transformed",
+		target: "effort"
+	},
+	promptCacheKey: {
+		kind: "faithful",
+		target: "promptCacheKey"
+	},
+	serviceTier: {
+		kind: "rejected",
+		reason: "the Grok subscription proxy's handling of serviceTier is unverified"
+	},
+	parallelToolCalls: {
+		kind: "rejected",
+		reason: "the Grok subscription proxy's handling of parallelToolCalls is unverified"
+	},
+	store: {
+		kind: "rejected",
+		reason: "qgrid always sends store: false"
+	},
+	previousResponseId: {
+		kind: "rejected",
+		reason: "qgrid replays conversation history itself"
+	},
+	include: {
+		kind: "rejected",
+		reason: "qgrid fixes the include list itself"
+	},
+	maxTurns: {
+		kind: "rejected",
+		reason: "qgrid does not run server-side agentic turns"
+	},
+	user: {
+		kind: "rejected",
+		reason: "qgrid does not forward end-user identifiers"
+	},
+	safetyIdentifier: {
+		kind: "rejected",
+		reason: "qgrid does not forward end-user identifiers"
+	}
+};
+/** Catalog effort set (`/models` `reasoning_efforts`) observed at GROK_BUILD_VERSION 1.0.60. */
+const DEFAULT_GROK_EFFORTS = [
+	"xhigh",
+	"high",
+	"medium",
+	"low"
+];
+/** Per-model overrides of `DEFAULT_GROK_EFFORTS`, keyed by the backend id without the `grok/` prefix. */
+const GROK_MODEL_EFFORTS = /* @__PURE__ */ new Map([
+	["grok-4.7", DEFAULT_GROK_EFFORTS],
+	["grok-4.7-build-fast", DEFAULT_GROK_EFFORTS],
+	["grok-4.6", DEFAULT_GROK_EFFORTS],
+	["grok-4.5", DEFAULT_GROK_EFFORTS]
+]);
+/** Thrown when `providerOptions.xai` has an invalid shape or value type. */
+var QgridXaiOptionsError = class extends Error {
+	issues;
+	constructor(issues) {
+		const detail = issues.map((issue) => `${issue.path || "(root)"}: ${issue.message}`).join("; ");
+		super(`qgrid: invalid providerOptions.xai: ${detail}`);
+		this.name = "QgridXaiOptionsError";
+		this.issues = issues;
+	}
+};
+/** Object.getPrototypeOf boxes primitives, so only plain and null-prototype objects pass. */
+function isPlainJsonObject(value) {
+	if (value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function isClassifiedKey(key) {
+	return Object.hasOwn(XAI_PROVIDER_OPTION_CLASSIFICATION, key);
+}
+function isGrokEffort(value) {
+	return value === "low" || value === "medium" || value === "high" || value === "xhigh";
+}
+function grokEffortsForModel(modelId) {
+	const backendId = modelId.startsWith("grok/") ? modelId.slice(5) : modelId;
+	return GROK_MODEL_EFFORTS.get(backendId) ?? DEFAULT_GROK_EFFORTS;
+}
+/**
+* Validates `providerOptions.xai` (the `@ai-sdk/xai` option shape) and maps the keys qgrid honors
+* onto its request fields. Unsupported keys and values become warnings; malformed values throw
+* `QgridXaiOptionsError`.
+*/
+function mapXaiProviderOptions(options, modelId) {
+	const result = {
+		request: {},
+		warnings: [],
+		rejected: []
+	};
+	if (options === void 0 || options === null) return result;
+	if (!isPlainJsonObject(options)) throw new QgridXaiOptionsError([{
+		path: "",
+		message: "expected an object"
+	}]);
+	const parsed = qgridXaiProviderOptionsSchema.safeParse(options);
+	if (!parsed.success) throw new QgridXaiOptionsError(parsed.error.issues.map((issue) => ({
+		path: issue.path.map(String).join("."),
+		message: issue.message
+	})));
+	const values = parsed.data;
+	for (const key of Object.keys(options)) {
+		if (!isClassifiedKey(key)) {
+			result.warnings.push({
+				key,
+				reason: "unknown providerOptions.xai key; ignored by qgrid"
+			});
+			continue;
+		}
+		const value = values[key];
+		if (value === void 0 || value === null) continue;
+		const classification = XAI_PROVIDER_OPTION_CLASSIFICATION[key];
+		if (classification.kind === "rejected") {
+			result.warnings.push({
+				key,
+				reason: classification.reason
+			});
+			result.rejected.push(key);
+		}
+	}
+	const effort = values.reasoningEffort;
+	if (effort !== void 0) if (effort === "none") {
+		result.warnings.push({
+			key: "reasoningEffort",
+			reason: "reasoningEffort \"none\" is not supported; the qgrid Grok route always reasons"
+		});
+		result.rejected.push("reasoningEffort");
+	} else if (isGrokEffort(effort) && grokEffortsForModel(modelId).includes(effort)) result.request.effort = effort;
+	else {
+		result.warnings.push({
+			key: "reasoningEffort",
+			reason: `reasoningEffort "${effort}" is not supported by ${modelId}`
+		});
+		result.rejected.push("reasoningEffort");
+	}
+	if (values.promptCacheKey !== void 0) result.request.promptCacheKey = values.promptCacheKey;
+	return result;
+}
+//#endregion
 //#region src/http-transport.ts
 const DEFAULT_ANTHROPIC_TIMEOUT_MS = 24e4;
 const TRANSPORT_RESPONSE_GRACE_MS = 6e4;
+const errorChainLinkSchema = z.looseObject({
+	cause: z.unknown().optional(),
+	code: z.unknown().optional(),
+	errors: z.unknown().optional(),
+	message: z.unknown().optional()
+});
+const nestedErrorsSchema = z.array(z.unknown());
 function anthropicTransportOptions(timeoutMs) {
 	const transportTimeoutMs = (Number.isFinite(timeoutMs) && timeoutMs !== void 0 && timeoutMs > 0 ? timeoutMs : DEFAULT_ANTHROPIC_TIMEOUT_MS) + TRANSPORT_RESPONSE_GRACE_MS;
 	return {
@@ -282,49 +574,51 @@ async function qgridFetch(input, init, context) {
 		throw toQgridTransportError(error, context);
 	}
 }
-function toQgridTransportError(error, context) {
-	if (isAbortError(error)) return error;
-	const code = findErrorCode(error);
+function toQgridTransportError(cause, context) {
+	if (isAbortError$1(cause)) return cause;
+	const code = findErrorCode(cause);
 	const prefix = `qgrid ${context.operation} transport failed`;
 	if (code === "UND_ERR_HEADERS_TIMEOUT") {
 		const budget = context.transportTimeoutMs ? ` after ${context.transportTimeoutMs}ms` : "";
-		return new Error(`${prefix}: response headers timed out${budget} (${code})`, { cause: error });
+		return new Error(`${prefix}: response headers timed out${budget} (${code})`, { cause });
 	}
 	if (code === "UND_ERR_BODY_TIMEOUT") {
 		const budget = context.transportTimeoutMs ? ` after ${context.transportTimeoutMs}ms` : "";
-		return new Error(`${prefix}: response body timed out${budget} (${code})`, { cause: error });
+		return new Error(`${prefix}: response body timed out${budget} (${code})`, { cause });
 	}
-	if (code === "ECONNREFUSED") return new Error(`${prefix}: connection refused by ${serverOrigin(context.serverUrl)} (${code})`, { cause: error });
-	const detail = findDeepestMessage(error) ?? "unknown network error";
-	return new Error(`${prefix}: ${detail}${code ? ` (${code})` : ""}`, { cause: error });
+	if (code === "ECONNREFUSED") return new Error(`${prefix}: connection refused by ${serverOrigin(context.serverUrl)} (${code})`, { cause });
+	const detail = findDeepestMessage(cause) ?? "unknown network error";
+	return new Error(`${prefix}: ${detail}${code ? ` (${code})` : ""}`, { cause });
 }
-function isAbortError(error) {
+function isAbortError$1(error) {
 	return error instanceof Error && error.name === "AbortError";
 }
-function findErrorCode(error, seen = /* @__PURE__ */ new Set()) {
-	if (!isErrorLike(error) || seen.has(error)) return void 0;
-	seen.add(error);
-	if (typeof error.code === "string") return error.code;
-	const causeCode = findErrorCode(error.cause, seen);
+function findErrorCode(cause, seen = /* @__PURE__ */ new Set()) {
+	const link = errorChainLinkSchema.safeParse(cause);
+	if (!link.success || seen.has(cause)) return void 0;
+	seen.add(cause);
+	const code = z.string().safeParse(link.data.code);
+	if (code.success) return code.data;
+	const causeCode = findErrorCode(link.data.cause, seen);
 	if (causeCode) return causeCode;
-	if (Array.isArray(error.errors)) for (const nested of error.errors) {
-		const nestedCode = findErrorCode(nested, seen);
+	const nested = nestedErrorsSchema.safeParse(link.data.errors);
+	if (nested.success) for (const nestedError of nested.data) {
+		const nestedCode = findErrorCode(nestedError, seen);
 		if (nestedCode) return nestedCode;
 	}
 }
-function findDeepestMessage(error, seen = /* @__PURE__ */ new Set()) {
-	if (!isErrorLike(error) || seen.has(error)) return void 0;
-	seen.add(error);
-	const causeMessage = findDeepestMessage(error.cause, seen);
+function findDeepestMessage(cause, seen = /* @__PURE__ */ new Set()) {
+	const link = errorChainLinkSchema.safeParse(cause);
+	if (!link.success || seen.has(cause)) return void 0;
+	seen.add(cause);
+	const causeMessage = findDeepestMessage(link.data.cause, seen);
 	if (causeMessage) return causeMessage;
-	if (Array.isArray(error.errors)) for (const nested of error.errors) {
-		const nestedMessage = findDeepestMessage(nested, seen);
+	const nested = nestedErrorsSchema.safeParse(link.data.errors);
+	if (nested.success) for (const nestedError of nested.data) {
+		const nestedMessage = findDeepestMessage(nestedError, seen);
 		if (nestedMessage) return nestedMessage;
 	}
-	return typeof error.message === "string" && error.message.length > 0 ? error.message : void 0;
-}
-function isErrorLike(value) {
-	return typeof value === "object" && value !== null;
+	return z.string().min(1).safeParse(link.data.message).data;
 }
 function serverOrigin(serverUrl) {
 	try {
@@ -342,33 +636,52 @@ const TOP_LEVEL_SCHEMA_WARNING = "qgrid server-enforced structured output requir
 const PENDING_TOOL_RESULTS_WARNING = "[qgrid] tool results did not match any pending qgrid run; sending request without runContext";
 //#endregion
 //#region src/utils.ts
+const createRunOutputSchema = z.object({ requestLogId: z.number() });
+const appendStepOutputSchema = z.object({ stepId: z.number() });
+const finishRunOutputSchema = z.object({ ok: z.boolean() });
 async function createRun(serverUrl, body) {
-	return (await fetch(`${serverUrl}/api/qgrid/createRun`, {
+	const res = await fetch(`${serverUrl}/api/qgrid/createRun`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({ input: body })
-	})).json();
+	});
+	return createRunOutputSchema.parse(await res.json());
 }
 async function appendStep(serverUrl, body) {
-	return (await fetch(`${serverUrl}/api/qgrid/appendStep`, {
+	const res = await fetch(`${serverUrl}/api/qgrid/appendStep`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({ input: body })
-	})).json();
+	});
+	return appendStepOutputSchema.parse(await res.json());
 }
 async function finishRun(serverUrl, body) {
-	return (await fetch(`${serverUrl}/api/qgrid/finishRun`, {
+	const res = await fetch(`${serverUrl}/api/qgrid/finishRun`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({ input: body })
-	})).json();
+	});
+	return finishRunOutputSchema.parse(await res.json());
 }
+/**
+* Decodes an AI SDK payload (tool input, tool output, tool error) into request-log text. JSON
+* cannot encode every JavaScript value (cycles, BigInt, bare undefined); those fall back to String().
+*/
+const loggedPayloadText = z.unknown().transform((payload) => {
+	try {
+		const json = JSON.stringify(payload);
+		return json === void 0 ? String(payload) : json;
+	} catch {
+		return String(payload);
+	}
+});
+/** Like loggedPayloadText, but keeps strings verbatim (tool arguments that are already JSON text). */
+const toolPayloadText = z.union([z.string(), loggedPayloadText]);
 function toQgridTool(tool) {
-	const source = tool;
 	return {
 		name: tool.name,
 		description: tool.description,
-		inputSchema: source.inputSchema ?? source.parameters ?? {}
+		inputSchema: tool.inputSchema
 	};
 }
 function extractToolResultsFromHistory(messages) {
@@ -377,13 +690,13 @@ function extractToolResultsFromHistory(messages) {
 	for (const msg of messages) if (msg.role === "assistant") {
 		for (const part of msg.content) if ("type" in part && part.type === "tool-call") calls.set(part.toolCallId, {
 			toolName: part.toolName,
-			args: typeof part.input === "string" ? part.input : JSON.stringify(part.input)
+			args: toolPayloadText.parse(part.input)
 		});
 	} else if (msg.role === "tool") {
 		for (const part of msg.content) if ("type" in part && part.type === "tool-result") {
 			const id = "toolCallId" in part ? part.toolCallId : "";
 			const output = part.output;
-			const text = "value" in output ? typeof output.value === "string" ? output.value : JSON.stringify(output.value) : JSON.stringify(output);
+			const text = "value" in output ? toolPayloadText.parse(output.value) : JSON.stringify(output);
 			results.set(id, text);
 		}
 	}
@@ -446,7 +759,7 @@ function extractPromptAndHistory(messages, options = {}) {
 		droppedImageCount += extracted.droppedImageCount;
 		return extracted;
 	};
-	for (const msg of messages) if (msg.role === "system") system = extractPromptParts(msg.content, false).text;
+	for (const msg of messages) if (msg.role === "system") system = msg.content;
 	else nonSystem.push(msg);
 	if (nonSystem.length === 0) return {
 		prompt: "",
@@ -479,7 +792,7 @@ function extractPromptAndHistory(messages, options = {}) {
 				}]
 			});
 		} else if (msg.role === "assistant") {
-			for (const part of msg.content) if ("text" in part && typeof part.text === "string") history.push({
+			for (const part of msg.content) if ("text" in part) history.push({
 				type: "message",
 				role: "assistant",
 				content: [{
@@ -490,14 +803,14 @@ function extractPromptAndHistory(messages, options = {}) {
 			else if ("toolName" in part && part.type === "tool-call") history.push({
 				type: "function_call",
 				name: part.toolName,
-				arguments: typeof part.input === "string" ? part.input : JSON.stringify(part.input),
+				arguments: toolPayloadText.parse(part.input),
 				call_id: part.toolCallId
 			});
 			else if (isImagePart(part)) droppedImageCount++;
 		} else if (msg.role === "tool") {
 			for (const part of msg.content) if ("toolName" in part && part.type === "tool-result") {
 				const output = part.output;
-				const text = "value" in output ? typeof output.value === "string" ? output.value : JSON.stringify(output.value) : JSON.stringify(output);
+				const text = "value" in output ? toolPayloadText.parse(output.value) : JSON.stringify(output);
 				history.push({
 					type: "function_call_output",
 					call_id: ("toolCallId" in part ? part.toolCallId : "") ?? "",
@@ -506,30 +819,22 @@ function extractPromptAndHistory(messages, options = {}) {
 			}
 		}
 	}
-	return {
+	const result = {
 		prompt,
 		system,
 		history,
 		imageUrls,
-		droppedImageCount,
-		...input ? { input } : {}
+		droppedImageCount
 	};
+	if (input) result.input = input;
+	return result;
 }
 function extractPromptParts(content, includeImages) {
-	if (typeof content === "string") return {
-		text: content,
-		parts: [{
-			type: "input_text",
-			text: content
-		}],
-		imageUrls: [],
-		droppedImageCount: 0
-	};
 	const parts = [];
 	const texts = [];
 	const imageUrls = [];
 	let droppedImageCount = 0;
-	for (const part of content) if ("text" in part && typeof part.text === "string") {
+	for (const part of content) if ("text" in part) {
 		parts.push({
 			type: "input_text",
 			text: part.text
@@ -567,18 +872,13 @@ function inputPartsFromPromptParts(parts) {
 	});
 }
 function isImagePart(part) {
-	if (!part || typeof part !== "object") return false;
-	const record = part;
-	return record.type === "image" || record.type === "file" && typeof record.mediaType === "string" && record.mediaType.toLowerCase().startsWith("image/");
+	return part.type === "file" && part.mediaType.toLowerCase().startsWith("image/");
 }
 function imageUrl(part) {
-	const record = part;
-	const mediaType = typeof record.mediaType === "string" && record.mediaType !== "image/*" ? record.mediaType : "image/png";
-	const data = record.data ?? record.image;
+	const mediaType = part.mediaType === "image/*" ? "image/png" : part.mediaType;
+	const { data } = part;
 	if (data instanceof URL) return /^https?:$/i.test(data.protocol) ? data.toString() : void 0;
 	if (data instanceof Uint8Array) return `data:${mediaType};base64,${bytesToBase64(data)}`;
-	if (data instanceof ArrayBuffer) return `data:${mediaType};base64,${bytesToBase64(new Uint8Array(data))}`;
-	if (typeof data !== "string") return void 0;
 	if (/^(https?:|data:)/i.test(data)) return data;
 	return /^[a-z][a-z0-9+.-]*:/i.test(data) ? void 0 : `data:${mediaType};base64,${data}`;
 }
@@ -600,73 +900,63 @@ function assertImageInputFitsJsonTransport(imageUrls) {
 	}
 	if (totalDataUrlChars > MAX_IMAGE_INPUT_DATA_URL_CHARS) throw new Error(`qgrid: image inputs are too large for JSON transport (${totalDataUrlChars} total chars). Compress or resize them before passing them to qgrid, for example as WebP/JPEG under ${MAX_IMAGE_INPUT_DATA_URL_CHARS_LABEL} total base64 data-url chars.`);
 }
-function safeStringify(value) {
-	try {
-		const json = JSON.stringify(value);
-		return json === void 0 ? String(value) : json;
-	} catch {
-		return String(value);
-	}
-}
-function getRecord(value) {
-	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
-}
 function extractTextContent(content) {
-	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return content;
 	const parts = [];
-	if (Array.isArray(content)) {
-		for (const part of content) if (part && typeof part === "object" && "type" in part) {
-			if (part.type === "text" && "text" in part && typeof part.text === "string") parts.push(part.text);
-		}
-	}
+	for (const part of content) if (part.type === "text") parts.push(part.text);
 	return parts.join("\n");
 }
-function getErrorMessage(value) {
-	if (value instanceof Error) return String(value);
-	if (value === void 0 || value === null) return "unknown error";
-	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+const primitiveErrorSchema = z.union([
+	z.string(),
+	z.number(),
+	z.nan(),
+	z.boolean(),
+	z.bigint()
+]);
+/** Formats an error cause (thrown value, abort reason, AI SDK error field) for a request log. */
+function getErrorMessage(cause) {
+	if (cause instanceof Error) return String(cause);
+	if (cause === void 0 || cause === null) return "unknown error";
+	const primitive = primitiveErrorSchema.safeParse(cause);
+	if (primitive.success) return String(primitive.data);
 	try {
-		return JSON.stringify(value) ?? "unknown error";
+		return JSON.stringify(cause) ?? "unknown error";
 	} catch {
 		return "unknown error";
 	}
 }
 function extractUserPrompt(prompt, messages) {
-	if (typeof prompt === "string") return prompt;
-	const messageList = Array.isArray(messages) ? messages : Array.isArray(prompt) ? prompt : [];
+	if (prompt !== void 0 && !Array.isArray(prompt)) return prompt;
+	const messageList = messages ?? prompt ?? [];
 	for (let i = messageList.length - 1; i >= 0; i--) {
-		const msg = getRecord(messageList[i]);
+		const msg = messageList[i];
 		if (msg?.role === "user") return extractTextContent(msg.content);
 	}
 	return "";
 }
 function extractSystemPrompt(system) {
-	if (typeof system === "string") return system;
-	if (system && typeof system === "object" && "content" in system) {
-		const content = system.content;
-		if (typeof content === "string") return content;
-	}
+	if (system === void 0 || Array.isArray(system)) return void 0;
+	return system instanceof Object ? system.content : system;
 }
 function serializeHistory(messages) {
-	if (!Array.isArray(messages) || messages.length === 0) return void 0;
-	const sliced = getRecord(messages[messages.length - 1])?.role === "user" ? messages.slice(0, -1) : messages;
+	if (!messages || messages.length === 0) return void 0;
+	const sliced = messages.at(-1)?.role === "user" ? messages.slice(0, -1) : messages;
 	const history = [];
 	for (const msg of sliced) {
-		const record = getRecord(msg);
-		if (record?.role !== "user" && record?.role !== "assistant") continue;
-		const text = extractTextContent(record.content);
+		if (msg.role !== "user" && msg.role !== "assistant") continue;
+		const text = extractTextContent(msg.content);
 		if (text.length === 0) continue;
 		history.push({
 			type: "message",
-			role: record.role,
+			role: msg.role,
 			content: [{
-				type: record.role === "user" ? "input_text" : "output_text",
+				type: msg.role === "user" ? "input_text" : "output_text",
 				text
 			}]
 		});
 	}
 	if (history.length === 0) return void 0;
-	return safeStringify(history);
+	return JSON.stringify(history);
 }
 //#endregion
 //#region src/image-model.ts
@@ -680,10 +970,198 @@ function imageInputUrl(file) {
 		"image/jpeg",
 		"image/webp"
 	].includes(file.mediaType)) throw new Error("qgrid.image: reference images must be PNG, JPEG, or WebP");
-	const data = typeof file.data === "string" ? file.data : bytesToBase64(file.data);
+	const data = file.data instanceof Uint8Array ? bytesToBase64(file.data) : file.data;
 	return `data:${file.mediaType};base64,${data}`;
 }
+/** Server-side Fastify body limit (`sonamu.config.ts` `bodyLimit`). Larger bodies get a 413. */
+const QGRID_MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024;
+function resolveMediaConfig(config) {
+	return {
+		serverUrl: config?.serverUrl ?? process.env.QGRID_URL ?? "http://localhost:44900",
+		projectName: config?.projectName ?? process.env.QGRID_PROJECT_NAME
+	};
+}
+const GROK_MODEL_ID = /^grok\/[A-Za-z0-9._-]+$/;
+function assertGrokModelId(modelId, label) {
+	if (!GROK_MODEL_ID.test(modelId)) throw new Error(`${label}: unsupported model ${modelId}; expected grok/<id>`);
+}
+function formatMiB(bytes) {
+	return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
+}
+/**
+* Server `MEDIA_MAX_INLINE_BYTES` (qgrid.types.ts): decoded inline audio, each inline image, and all
+* inline images of one request together. Derived from the 10 MiB body limit: base64 grows bytes by
+* 4/3, so 7 MiB decoded is about 9.3 MiB encoded, leaving room for the rest of the JSON body.
+*/
+const QGRID_MAX_INLINE_MEDIA_BYTES = 7 * 1024 * 1024;
+function base64DecodedBytes(data) {
+	const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+	return Math.floor(data.length * 3 / 4) - padding;
+}
+/**
+* Rejects inline media above the server's decoded-size cap before transport. Accepts base64
+* strings and data URLs; https URLs cost nothing because xAI fetches them.
+*/
+function assertInlineMediaFits(items, label) {
+	let total = 0;
+	for (const item of items) {
+		if (item === void 0 || /^https:\/\//i.test(item)) continue;
+		const comma = item.startsWith("data:") ? item.indexOf(",") : -1;
+		total += base64DecodedBytes(comma >= 0 ? item.slice(comma + 1) : item);
+	}
+	if (total > 7340032) throw new Error(`${label}: inline media is ${formatMiB(total)}, above the qgrid server limit of ${formatMiB(QGRID_MAX_INLINE_MEDIA_BYTES)} per request; compress it or pass an https URL where supported.`);
+}
+/**
+* Serializes a Sonamu `params` body and rejects it before transport when it would exceed the
+* server body limit, so callers get a clear error instead of an opaque 413.
+*/
+function serializeMediaBody(params, label) {
+	const body = JSON.stringify({ params });
+	const bytes = new TextEncoder().encode(body).byteLength;
+	if (bytes > 10485760) throw new Error(`${label}: request body is ${formatMiB(bytes)}, above the qgrid server limit of ${formatMiB(QGRID_MAX_REQUEST_BODY_BYTES)}; compress inline media or pass an https URL where supported.`);
+	return body;
+}
+const ERROR_BODY_PREVIEW_CHARS = 2e3;
+function isAbortError(cause) {
+	return cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError");
+}
+/**
+* Rethrows `cause` when it is an abort. When `signal` fired, its own reason is thrown so callers
+* that compare reasons (the video poll deadline) can tell which abort it was.
+*/
+function rethrowAbort(cause, signal) {
+	if (signal?.aborted) throw signal.reason ?? cause;
+	if (isAbortError(cause)) throw cause;
+}
+/** Non-2xx response from a qgrid media endpoint. */
+var QgridMediaHttpError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "QgridMediaHttpError";
+		this.status = status;
+	}
+};
+/** POSTs one Sonamu media endpoint and validates the JSON response with `schema`. */
+async function postMediaEndpoint(args) {
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(args.headers ?? {})) if (value !== void 0) headers.set(key, value);
+	headers.set("Content-Type", "application/json");
+	const init = {
+		method: "POST",
+		headers,
+		body: args.body
+	};
+	if (args.signal) init.signal = args.signal;
+	let response;
+	try {
+		response = await fetch(`${args.serverUrl}/api/qgrid/${args.endpoint}`, init);
+	} catch (error) {
+		rethrowAbort(error, args.signal);
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`${args.label}: ${args.endpoint} transport failed: ${detail}`, { cause: error });
+	}
+	if (!response.ok) {
+		const text = await response.text().catch((cause) => {
+			rethrowAbort(cause, args.signal);
+			return "";
+		});
+		if (response.status === 413) throw new QgridMediaHttpError(`${args.label}: the qgrid server rejected the request as too large (413); inline media is limited to ${formatMiB(QGRID_MAX_INLINE_MEDIA_BYTES)} decoded per request. ${text.slice(0, ERROR_BODY_PREVIEW_CHARS)}`, 413);
+		throw new QgridMediaHttpError(`qgrid ${args.endpoint} ${response.status}: ${text.slice(0, ERROR_BODY_PREVIEW_CHARS)}`, response.status);
+	}
+	const json = await response.json().catch((cause) => {
+		rethrowAbort(cause, args.signal);
+	});
+	const parsed = args.schema.safeParse(json);
+	if (!parsed.success) throw new Error(`${args.label}: unexpected ${args.endpoint} response; update the qgrid server and SDK together (${formatIssues(parsed.error)})`);
+	return {
+		data: parsed.data,
+		headers: Object.fromEntries(response.headers)
+	};
+}
+function formatIssues(error) {
+	return error.issues.map((issue) => `${issue.path.map(String).join(".") || "(root)"}: ${issue.message}`).join("; ");
+}
+const grokQgridOptionsSchema = z.object({
+	tokenName: z.string().refine((value) => /^grok\/.+/.test(value.trim()), { message: "tokenName must be a non-empty Grok token name with the grok/ prefix" }).optional(),
+	logger: z.boolean({ message: "logger must be a boolean" }).optional()
+});
+/** Any non-null, non-array object; field validation happens in the option schemas. */
+const providerOptionsObjectSchema = z.looseObject({});
+function parseGrokQgridOptions(raw, label) {
+	if (raw === void 0) return {};
+	if (!providerOptionsObjectSchema.safeParse(raw).success) throw new Error(`${label}: providerOptions.qgrid must be an object`);
+	const parsed = grokQgridOptionsSchema.safeParse(raw);
+	if (!parsed.success) throw new Error(`${label}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+	const request = {};
+	if (parsed.data.tokenName !== void 0) request.tokenName = parsed.data.tokenName;
+	if (parsed.data.logger === false) request.logger = false;
+	return request;
+}
+/**
+* Validates `providerOptions.xai` against `schema` and warns about every set key outside
+* `honored`. Malformed values throw; documented-but-unsupported keys become warnings.
+*/
+function parseXaiMediaOptions(raw, schema, honored, label) {
+	if (raw === void 0) return {
+		options: void 0,
+		warnings: []
+	};
+	const record = providerOptionsObjectSchema.safeParse(raw);
+	if (!record.success) throw new Error(`${label}: providerOptions.xai must be an object`);
+	const parsed = schema.safeParse(raw);
+	if (!parsed.success) throw new Error(`${label}: invalid providerOptions.xai: ${formatIssues(parsed.error)}`);
+	const warnings = [];
+	for (const [key, value] of Object.entries(record.data)) {
+		if (value === void 0 || value === null || honored.has(key)) continue;
+		warnings.push({
+			type: "unsupported",
+			feature: `providerOptions.xai.${key}`,
+			details: `qgrid does not support providerOptions.xai.${key} for this model; it was ignored.`
+		});
+	}
+	return {
+		options: parsed.data,
+		warnings
+	};
+}
+const IMAGE_REF_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp"
+];
+/** An AI SDK file as the server's image reference: an https URL or a base64 image data URL. */
+function toImageRef(file, label) {
+	if (file.type === "url") return toImageRefUrl(file.url, label);
+	const mediaType = file.mediaType.toLowerCase();
+	if (!IMAGE_REF_MEDIA_TYPES.includes(mediaType)) throw new Error(`${label}: reference images must be PNG, JPEG, or WebP`);
+	return `data:${mediaType};base64,${file.data instanceof Uint8Array ? bytesToBase64(file.data) : file.data}`;
+}
+/** Accepts an https URL or a base64 PNG/JPEG/WebP data URL string. */
+function toImageRefUrl(url, label) {
+	if (/^https:\/\//i.test(url)) return url;
+	if (/^data:image\/(png|jpeg|webp);base64,/i.test(url)) return url;
+	throw new Error(`${label}: image references must be https URLs or PNG/JPEG/WebP data URLs`);
+}
+const OPENAI_IMAGE_TOKEN_NAME_MESSAGE = "tokenName must be a non-empty OpenAI token name with the openai/ prefix";
+/** `providerOptions.qgrid` for `qgrid.image("openai/gpt-image-2")`; issues keep this field order. */
+const openAIImageQgridOptionsSchema = z.object({
+	tokenName: z.string({ message: OPENAI_IMAGE_TOKEN_NAME_MESSAGE }).refine((value) => /^openai\/.+/.test(value.trim()), { message: OPENAI_IMAGE_TOKEN_NAME_MESSAGE }).optional(),
+	logger: z.boolean({ message: "logger must be a boolean" }).optional(),
+	outputFormat: z.literal("png", { message: "the subscription Images endpoint supports PNG output only" }).optional(),
+	quality: z.enum([
+		"low",
+		"medium",
+		"high"
+	], { message: "quality must be low, medium, or high" }).optional(),
+	background: z.enum([
+		"auto",
+		"opaque",
+		"transparent"
+	], { message: "background must be auto, opaque, or transparent" }).optional()
+});
 function createQgridImage(modelId, config) {
+	if (modelId.startsWith("grok/")) return createGrokImage(modelId, config);
 	if (modelId !== "openai/gpt-image-2") throw new Error(`qgrid.image: unsupported image model ${modelId}`);
 	const serverUrl = config?.serverUrl ?? process.env.QGRID_URL ?? "http://localhost:44900";
 	const projectName = config?.projectName ?? process.env.QGRID_PROJECT_NAME;
@@ -697,20 +1175,9 @@ function createQgridImage(modelId, config) {
 			if (options.n !== 1) throw new Error("qgrid.image: only one image per call is supported; omit maxImagesPerCall so AI SDK can batch n images");
 			if (!options.prompt?.trim()) throw new Error("qgrid.image: a non-empty text prompt is required");
 			if ((options.files?.length ?? 0) > 5) throw new Error("qgrid.image: at most five reference images are supported");
-			const qgridOptions = options.providerOptions.qgrid ?? {};
-			if (qgridOptions.tokenName !== void 0 && (typeof qgridOptions.tokenName !== "string" || !/^openai\/.+/.test(qgridOptions.tokenName.trim()))) throw new Error("qgrid.image: tokenName must be a non-empty OpenAI token name with the openai/ prefix");
-			if (qgridOptions.logger !== void 0 && typeof qgridOptions.logger !== "boolean") throw new Error("qgrid.image: logger must be a boolean");
-			if (qgridOptions.outputFormat !== void 0 && qgridOptions.outputFormat !== "png") throw new Error("qgrid.image: the subscription Images endpoint supports PNG output only");
-			if (qgridOptions.quality !== void 0 && ![
-				"low",
-				"medium",
-				"high"
-			].includes(qgridOptions.quality)) throw new Error("qgrid.image: quality must be low, medium, or high");
-			if (qgridOptions.background !== void 0 && ![
-				"auto",
-				"opaque",
-				"transparent"
-			].includes(qgridOptions.background)) throw new Error("qgrid.image: background must be auto, opaque, or transparent");
+			const parsedQgridOptions = openAIImageQgridOptionsSchema.safeParse(options.providerOptions.qgrid ?? {});
+			if (!parsedQgridOptions.success) throw new Error(`qgrid.image: ${parsedQgridOptions.error.issues[0]?.message}`);
+			const qgridOptions = parsedQgridOptions.data;
 			if (options.size !== void 0 && !/^[1-9]\d*x[1-9]\d*$/.test(options.size)) throw new Error("qgrid.image: size must be positive integer WIDTHxHEIGHT");
 			const imageUrls = (options.files ?? []).map(imageInputUrl);
 			assertImageInputFitsJsonTransport(imageUrls);
@@ -728,7 +1195,7 @@ function createQgridImage(modelId, config) {
 				feature,
 				details: "The subscription Images endpoint does not support this setting. Describe the desired result in the prompt."
 			});
-			for (const feature of [...options.size !== void 0 ? ["size"] : [], ...qgridOptions.quality !== void 0 ? ["providerOptions.qgrid.quality"] : []]) warnings.push({
+			for (const feature of [...options.size === void 0 ? [] : ["size"], ...qgridOptions.quality === void 0 ? [] : ["providerOptions.qgrid.quality"]]) warnings.push({
 				type: "compatibility",
 				feature,
 				details: "This is a hint only. The subscription backend may choose a different size or quality; inspect the returned generation metadata."
@@ -737,53 +1204,753 @@ function createQgridImage(modelId, config) {
 			const headers = new Headers();
 			for (const [key, value] of Object.entries(options.headers ?? {})) if (value !== void 0) headers.set(key, value);
 			headers.set("Content-Type", "application/json");
+			const imageGenerationOptions = {};
+			if (options.size !== void 0) imageGenerationOptions.size = options.size;
+			if (qgridOptions.quality !== void 0) imageGenerationOptions.quality = qgridOptions.quality;
+			if (qgridOptions.background !== void 0) imageGenerationOptions.background = qgridOptions.background;
+			if (qgridOptions.outputFormat !== void 0) imageGenerationOptions.outputFormat = qgridOptions.outputFormat;
+			const args = {
+				prompt: options.prompt,
+				model: modelId,
+				imageGeneration: true,
+				imageGenerationOptions
+			};
+			if (imageUrls.length) args.input = input;
+			if (projectName) args.projectName = projectName;
+			if (qgridOptions.tokenName !== void 0) args.tokenName = qgridOptions.tokenName;
+			if (qgridOptions.logger === false) args.logger = false;
 			const response = await qgridFetch(`${serverUrl}/api/qgrid/query`, {
 				method: "POST",
 				headers,
 				signal: options.abortSignal,
-				body: JSON.stringify({ args: {
-					prompt: options.prompt,
-					model: modelId,
-					imageGeneration: true,
-					imageGenerationOptions: {
-						...options.size !== void 0 ? { size: options.size } : {},
-						...qgridOptions.quality !== void 0 ? { quality: qgridOptions.quality } : {},
-						...qgridOptions.background !== void 0 ? { background: qgridOptions.background } : {},
-						...qgridOptions.outputFormat !== void 0 ? { outputFormat: qgridOptions.outputFormat } : {}
-					},
-					...imageUrls.length ? { input } : {},
-					...projectName ? { projectName } : {},
-					...qgridOptions.tokenName !== void 0 ? { tokenName: qgridOptions.tokenName } : {},
-					...qgridOptions.logger === false ? { logger: false } : {}
-				} })
+				body: JSON.stringify({ args })
 			}, {
 				operation: "query",
 				serverUrl
 			});
 			if (!response.ok) throw new Error(`qgrid ${response.status}: ${await response.text().catch(() => "")}`);
-			const data = await response.json();
+			const data = queryOutputSchema.parse(await response.json());
 			const images = data.content?.filter((item) => item.type === "image") ?? [];
 			const image = images[0];
 			if (images.length !== 1 || !image?.data || image.generation?.route !== "codex-images") throw new Error("qgrid.image: expected one image from the direct subscription Images route; update the qgrid server and SDK together");
 			const usage = image.generation.usage;
-			return {
+			const imageMetadata = {};
+			if (data.requestLogId !== void 0) imageMetadata.requestLogId = data.requestLogId;
+			imageMetadata.generation = image.generation;
+			if (image.revisedPrompt !== null && image.revisedPrompt !== void 0) imageMetadata.revisedPrompt = image.revisedPrompt;
+			const result = {
 				images: [image.data],
 				warnings,
 				response: {
 					timestamp,
-					modelId: image.generation.model ?? data.model,
+					modelId: image.generation.model ?? data.model ?? modelId,
 					headers: Object.fromEntries(response.headers)
 				},
-				...usage ? { usage: {
-					inputTokens: usage.input_tokens,
-					outputTokens: usage.output_tokens,
-					totalTokens: usage.total_tokens
-				} } : {},
-				providerMetadata: { qgrid: { images: [{
-					...data.requestLogId !== void 0 ? { requestLogId: data.requestLogId } : {},
-					generation: image.generation,
-					...image.revisedPrompt !== null && image.revisedPrompt !== void 0 ? { revisedPrompt: image.revisedPrompt } : {}
-				}] } }
+				providerMetadata: { qgrid: { images: [imageMetadata] } }
+			};
+			if (usage) result.usage = {
+				inputTokens: usage.input_tokens,
+				outputTokens: usage.output_tokens,
+				totalTokens: usage.total_tokens
+			};
+			return result;
+		}
+	};
+}
+const GROK_MAX_IMAGES_PER_CALL = 3;
+/** `providerOptions.xai` for Grok images, field-for-field from `@ai-sdk/xai` `xaiImageModelOptions`. */
+const xaiImageOptionsSchema = z.object({
+	aspect_ratio: z.string().optional(),
+	output_format: z.string().optional(),
+	sync_mode: z.boolean().optional(),
+	resolution: z.enum([
+		"1k",
+		"1.5k",
+		"2k"
+	]).optional(),
+	quality: z.enum([
+		"low",
+		"medium",
+		"high",
+		"auto"
+	]).optional(),
+	user: z.string().optional()
+});
+const XAI_IMAGE_HONORED = /* @__PURE__ */ new Set([
+	"aspect_ratio",
+	"output_format",
+	"resolution",
+	"quality"
+]);
+const GROK_OUTPUT_FORMATS = [
+	"png",
+	"jpeg",
+	"webp"
+];
+function isGrokOutputFormat(value) {
+	return GROK_OUTPUT_FORMATS.some((format) => format === value);
+}
+const generateImagesOutputSchema = z.object({
+	requestLogId: z.number().optional(),
+	model: z.string(),
+	tokenName: z.string(),
+	images: z.array(z.object({
+		b64: z.string(),
+		mimeType: z.string(),
+		revisedPrompt: z.string().optional()
+	})),
+	usage: z.object({
+		imageCount: z.number(),
+		costInUsdTicks: z.number().optional()
+	}),
+	costUsd: z.number().optional(),
+	costSource: z.enum(["provider", "pricing_table"]).optional()
+});
+function createGrokImage(modelId, config) {
+	const label = "qgrid.image";
+	assertGrokModelId(modelId, label);
+	const { serverUrl, projectName } = resolveMediaConfig(config);
+	return {
+		specificationVersion: "v3",
+		provider: QGRID_PROVIDER_NAME,
+		modelId,
+		maxImagesPerCall: GROK_MAX_IMAGES_PER_CALL,
+		async doGenerate(options) {
+			if (!options.prompt?.trim()) throw new Error(`${label}: a non-empty text prompt is required`);
+			if (!Number.isInteger(options.n) || options.n < 1 || options.n > GROK_MAX_IMAGES_PER_CALL) throw new Error(`${label}: Grok returns 1 to ${GROK_MAX_IMAGES_PER_CALL} images per call; omit maxImagesPerCall so AI SDK can batch`);
+			const files = options.files ?? [];
+			if (files.length > 5) throw new Error(`${label}: at most five reference images are supported`);
+			const qgridOptions = parseGrokQgridOptions(options.providerOptions.qgrid, label);
+			const xai = parseXaiMediaOptions(options.providerOptions.xai, xaiImageOptionsSchema, XAI_IMAGE_HONORED, label);
+			const outputFormat = xai.options?.output_format;
+			if (outputFormat !== void 0 && !isGrokOutputFormat(outputFormat)) throw new Error(`${label}: providerOptions.xai.output_format must be png, jpeg, or webp`);
+			const warnings = [];
+			if (options.size !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "size",
+				details: "This model does not support the `size` option. Use `aspectRatio` instead."
+			});
+			if (options.seed !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "seed"
+			});
+			if (options.mask !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "mask"
+			});
+			warnings.push(...xai.warnings);
+			const referenceImages = files.map((file) => toImageRef(file, label));
+			assertInlineMediaFits(referenceImages, label);
+			const aspectRatio = options.aspectRatio ?? xai.options?.aspect_ratio;
+			const params = {
+				model: modelId,
+				prompt: options.prompt,
+				n: options.n
+			};
+			if (aspectRatio !== void 0) params.aspectRatio = aspectRatio;
+			if (xai.options?.resolution !== void 0) params.resolution = xai.options.resolution;
+			if (xai.options?.quality !== void 0) params.quality = xai.options.quality;
+			if (outputFormat !== void 0) params.outputFormat = outputFormat;
+			if (referenceImages.length) params.referenceImages = referenceImages;
+			if (projectName) params.projectName = projectName;
+			const body = serializeMediaBody({
+				...params,
+				...qgridOptions
+			}, label);
+			const timestamp = /* @__PURE__ */ new Date();
+			const { data, headers } = await postMediaEndpoint({
+				serverUrl,
+				endpoint: "generateImages",
+				body,
+				schema: generateImagesOutputSchema,
+				label,
+				signal: options.abortSignal,
+				headers: options.headers
+			});
+			if (data.images.length === 0) throw new Error(`${label}: the Grok backend returned no images`);
+			const costInUsdTicks = data.usage.costInUsdTicks;
+			const callCost = {};
+			if (data.costUsd !== void 0) callCost.costUsd = data.costUsd;
+			if (data.costSource !== void 0) callCost.costSource = data.costSource;
+			const xaiImages = data.images.map((image, index) => {
+				const entry = {};
+				if (image.revisedPrompt) entry.revisedPrompt = image.revisedPrompt;
+				if (index === 0 && costInUsdTicks !== void 0) entry.costInUsdTicks = costInUsdTicks;
+				return entry;
+			});
+			const xaiCallCost = {};
+			if (costInUsdTicks !== void 0) xaiCallCost.costInUsdTicks = costInUsdTicks;
+			const qgridImages = data.images.map((image, index) => {
+				const entry = {
+					mediaType: image.mimeType,
+					tokenName: data.tokenName
+				};
+				if (data.requestLogId !== void 0) entry.requestLogId = data.requestLogId;
+				return index === 0 ? {
+					...entry,
+					...callCost
+				} : entry;
+			});
+			const qgridCallInfo = {};
+			if (data.requestLogId !== void 0) qgridCallInfo.requestLogId = data.requestLogId;
+			qgridCallInfo.tokenName = data.tokenName;
+			return {
+				images: data.images.map((image) => image.b64),
+				warnings,
+				response: {
+					timestamp,
+					modelId: data.model,
+					headers
+				},
+				providerMetadata: {
+					xai: {
+						images: xaiImages,
+						...xaiCallCost
+					},
+					qgrid: {
+						images: qgridImages,
+						...qgridCallInfo,
+						...callCost
+					}
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/speech-model.ts
+const LABEL$2 = "qgrid.speech";
+const MAX_TEXT_CHARS = 15e3;
+/** Codecs of `@ai-sdk/xai` `XaiSpeechCodec`, equal to the qgrid server's `format` enum. */
+const SPEECH_FORMATS = [
+	"mp3",
+	"wav",
+	"pcm",
+	"mulaw",
+	"alaw"
+];
+function isSpeechFormat(value) {
+	return SPEECH_FORMATS.some((format) => format === value);
+}
+/**
+* `providerOptions.xai` for Grok speech, field-for-field from `@ai-sdk/xai`
+* `xaiSpeechModelOptionsSchema`. The qgrid server takes none of them; every set key warns.
+*/
+const xaiSpeechOptionsSchema = z.object({
+	sampleRate: z.union([
+		z.literal(8e3),
+		z.literal(16e3),
+		z.literal(22050),
+		z.literal(24e3),
+		z.literal(44100),
+		z.literal(48e3)
+	]).nullish(),
+	bitRate: z.union([
+		z.literal(32e3),
+		z.literal(64e3),
+		z.literal(96e3),
+		z.literal(128e3),
+		z.literal(192e3)
+	]).nullish(),
+	optimizeStreamingLatency: z.union([
+		z.literal(0),
+		z.literal(1),
+		z.literal(2)
+	]).nullish(),
+	textNormalization: z.boolean().nullish(),
+	withTimestamps: z.boolean().nullish(),
+	replace: z.record(z.string(), z.string()).nullish()
+});
+const speakOutputSchema = z.object({
+	audio: z.string(),
+	mimeType: z.string(),
+	tokenName: z.string(),
+	requestLogId: z.number().optional()
+});
+function base64ToBytes(data) {
+	if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(data, "base64"));
+	const binary = atob(data);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+/**
+* Grok text-to-speech through `POST /api/qgrid/speak`. `voice`, `language` and `outputFormat`
+* map to the server's `voice`, `language` and `format`; when omitted the server applies
+* `ara` / `en` / `mp3` (the only combination verified live). The model id only labels the log.
+*/
+function createQgridSpeech(modelId, config) {
+	assertGrokModelId(modelId, LABEL$2);
+	const { serverUrl, projectName } = resolveMediaConfig(config);
+	return {
+		specificationVersion: "v3",
+		provider: QGRID_PROVIDER_NAME,
+		modelId,
+		async doGenerate(options) {
+			if (!options.text.trim()) throw new Error(`${LABEL$2}: text must not be empty`);
+			if (options.text.length > MAX_TEXT_CHARS) throw new Error(`${LABEL$2}: text is limited to ${MAX_TEXT_CHARS} characters`);
+			const qgridOptions = parseGrokQgridOptions(options.providerOptions?.qgrid, LABEL$2);
+			const xai = parseXaiMediaOptions(options.providerOptions?.xai, xaiSpeechOptionsSchema, /* @__PURE__ */ new Set(), LABEL$2);
+			const warnings = [];
+			let format;
+			if (options.outputFormat !== void 0) if (isSpeechFormat(options.outputFormat)) format = options.outputFormat;
+			else {
+				format = "mp3";
+				warnings.push({
+					type: "unsupported",
+					feature: "outputFormat",
+					details: `Unsupported output format: ${options.outputFormat}. Using mp3 instead.`
+				});
+			}
+			if (options.instructions !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "instructions"
+			});
+			if (options.speed !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "speed"
+			});
+			warnings.push(...xai.warnings);
+			const requestParams = {
+				model: modelId,
+				text: options.text
+			};
+			if (options.voice !== void 0) requestParams.voice = options.voice;
+			if (options.language !== void 0) requestParams.language = options.language;
+			if (format !== void 0) requestParams.format = format;
+			if (projectName) requestParams.projectName = projectName;
+			const params = {
+				...requestParams,
+				...qgridOptions
+			};
+			const body = serializeMediaBody(params, LABEL$2);
+			const timestamp = /* @__PURE__ */ new Date();
+			const { data, headers } = await postMediaEndpoint({
+				serverUrl,
+				endpoint: "speak",
+				body,
+				schema: speakOutputSchema,
+				label: LABEL$2,
+				signal: options.abortSignal,
+				headers: options.headers
+			});
+			const qgridMetadata = {
+				mediaType: data.mimeType,
+				tokenName: data.tokenName
+			};
+			if (data.requestLogId !== void 0) qgridMetadata.requestLogId = data.requestLogId;
+			return {
+				audio: base64ToBytes(data.audio),
+				warnings,
+				request: { body: params },
+				response: {
+					timestamp,
+					modelId,
+					headers
+				},
+				providerMetadata: { qgrid: qgridMetadata }
+			};
+		}
+	};
+}
+//#endregion
+//#region src/transcription-model.ts
+const LABEL$1 = "qgrid.transcription";
+const AUDIO_MEDIA_TYPE = /^audio\/[A-Za-z0-9.+-]+$/;
+/**
+* `providerOptions.xai` for Grok transcription, field-for-field from `@ai-sdk/xai`
+* `xaiTranscriptionModelOptionsSchema`. Only `language` reaches the qgrid server.
+*/
+const xaiTranscriptionOptionsSchema = z.object({
+	audioFormat: z.enum([
+		"pcm",
+		"mulaw",
+		"alaw",
+		"opus"
+	]).nullish(),
+	sampleRate: z.union([
+		z.literal(8e3),
+		z.literal(16e3),
+		z.literal(22050),
+		z.literal(24e3),
+		z.literal(44100),
+		z.literal(48e3)
+	]).nullish(),
+	language: z.string().min(1).max(16).nullish(),
+	format: z.boolean().nullish(),
+	multichannel: z.boolean().nullish(),
+	channels: z.number().int().min(2).max(8).nullish(),
+	diarize: z.boolean().nullish(),
+	keyterm: z.union([z.string(), z.array(z.string())]).nullish(),
+	fillerWords: z.boolean().nullish(),
+	vadThreshold: z.number().min(0).max(1).optional(),
+	streaming: z.object({}).loose().optional()
+});
+const XAI_TRANSCRIPTION_HONORED = /* @__PURE__ */ new Set(["language"]);
+const transcribeOutputSchema = z.object({
+	text: z.string(),
+	language: z.string().optional(),
+	durationSec: z.number().optional(),
+	model: z.string(),
+	tokenName: z.string(),
+	requestLogId: z.number().optional()
+});
+function normalizeMediaType(mediaType) {
+	const bare = mediaType.split(";")[0].trim().toLowerCase();
+	if (!AUDIO_MEDIA_TYPE.test(bare)) throw new Error(`${LABEL$1}: mediaType must be audio/*, got "${mediaType}"`);
+	return bare;
+}
+function createQgridTranscription(modelId, config) {
+	assertGrokModelId(modelId, LABEL$1);
+	const { serverUrl, projectName } = resolveMediaConfig(config);
+	return {
+		specificationVersion: "v3",
+		provider: QGRID_PROVIDER_NAME,
+		modelId,
+		async doGenerate(options) {
+			const mediaType = normalizeMediaType(options.mediaType);
+			const audio = options.audio instanceof Uint8Array ? bytesToBase64(options.audio) : options.audio;
+			if (audio.length === 0) throw new Error(`${LABEL$1}: audio is empty`);
+			assertInlineMediaFits([audio], LABEL$1);
+			const qgridOptions = parseGrokQgridOptions(options.providerOptions?.qgrid, LABEL$1);
+			const xai = parseXaiMediaOptions(options.providerOptions?.xai, xaiTranscriptionOptionsSchema, XAI_TRANSCRIPTION_HONORED, LABEL$1);
+			const warnings = [...xai.warnings];
+			const language = xai.options?.language ?? void 0;
+			const params = {
+				model: modelId,
+				audio,
+				mediaType
+			};
+			if (language !== void 0) params.language = language;
+			if (projectName) params.projectName = projectName;
+			const body = serializeMediaBody({
+				...params,
+				...qgridOptions
+			}, LABEL$1);
+			const timestamp = /* @__PURE__ */ new Date();
+			const { data, headers } = await postMediaEndpoint({
+				serverUrl,
+				endpoint: "transcribe",
+				body,
+				schema: transcribeOutputSchema,
+				label: LABEL$1,
+				signal: options.abortSignal,
+				headers: options.headers
+			});
+			const qgridMetadata = { tokenName: data.tokenName };
+			if (data.requestLogId !== void 0) qgridMetadata.requestLogId = data.requestLogId;
+			return {
+				text: data.text,
+				segments: [],
+				language: data.language,
+				durationInSeconds: data.durationSec,
+				warnings,
+				response: {
+					timestamp,
+					modelId: data.model,
+					headers
+				},
+				providerMetadata: { qgrid: qgridMetadata }
+			};
+		}
+	};
+}
+//#endregion
+//#region src/video-model.ts
+const LABEL = "qgrid.video";
+const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+const MAX_REFERENCE_IMAGES = 5;
+const LAST_FRAME_MODEL = "grok/grok-imagine-video-1.5";
+const RESOLUTION_MAP = /* @__PURE__ */ new Map([
+	["1920x1080", "1080p"],
+	["1280x720", "720p"],
+	["854x480", "480p"],
+	["640x480", "480p"]
+]);
+/**
+* `providerOptions.xai` for Grok video. Field names follow `@ai-sdk/xai` `xaiVideoModelOptions`;
+* `lastFrame` is a qgrid extension because AI SDK v3 video calls have no `frameImages`.
+* Edit / extend modes need a source video URL the qgrid server does not accept, so they throw.
+*/
+const xaiVideoOptionsSchema = z.looseObject({
+	mode: z.enum([
+		"edit-video",
+		"extend-video",
+		"reference-to-video"
+	]).optional(),
+	videoUrl: z.string().min(1).optional(),
+	referenceImageUrls: z.array(z.string().min(1)).min(1).max(7).optional(),
+	referenceVoiceIds: z.array(z.string().min(1)).max(3).optional(),
+	keyframes: z.array(z.unknown()).optional(),
+	storageOptions: z.unknown().optional(),
+	user: z.string().optional(),
+	pollIntervalMs: z.number().positive().nullish(),
+	pollTimeoutMs: z.number().positive().nullish(),
+	resolution: z.enum([
+		"480p",
+		"720p",
+		"1080p"
+	]).nullish(),
+	lastFrame: z.string().min(1).optional()
+});
+const XAI_VIDEO_HONORED = /* @__PURE__ */ new Set([
+	"mode",
+	"referenceImageUrls",
+	"resolution",
+	"lastFrame",
+	"pollIntervalMs",
+	"pollTimeoutMs"
+]);
+const videoStartOutputSchema = z.object({
+	jobHandle: z.string(),
+	model: z.string(),
+	requestLogId: z.number().optional()
+});
+const videoStatusOutputSchema = z.object({
+	status: z.enum([
+		"pending",
+		"done",
+		"failed"
+	]),
+	url: z.string().optional(),
+	mimeType: z.literal("video/mp4"),
+	durationSec: z.number().optional(),
+	costInUsdTicks: z.number().optional(),
+	costUsd: z.number().optional(),
+	error: z.string().optional(),
+	requestLogId: z.number().optional()
+});
+/**
+* Raised when the poll budget runs out. The job keeps running on xAI; pass `jobHandle` to
+* `resumeQgridVideo` (with the same `projectName`) to keep waiting.
+*/
+var QgridVideoTimeoutError = class extends Error {
+	jobHandle;
+	constructor(jobHandle, timeoutMs) {
+		super(`${LABEL}: video job ${jobHandle} did not finish within ${timeoutMs} ms; resume it with resumeQgridVideo("${jobHandle}")`);
+		this.name = "QgridVideoTimeoutError";
+		this.jobHandle = jobHandle;
+	}
+};
+/** The upstream job finished as failed (including content-policy blocks). */
+var QgridVideoGenerationError = class extends Error {
+	jobHandle;
+	constructor(jobHandle, detail) {
+		super(`${LABEL}: video generation failed${detail ? `: ${detail}` : "."}`);
+		this.name = "QgridVideoGenerationError";
+		this.jobHandle = jobHandle;
+	}
+};
+function abortedError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason ?? abortedError());
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason ?? abortedError());
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function isTransientPollError(cause) {
+	if (cause instanceof QgridMediaHttpError) return cause.status === 429 || cause.status >= 500;
+	return cause instanceof Error && /transport failed/.test(cause.message);
+}
+function pollDeadline(caller, ms) {
+	const controller = new AbortController();
+	const onCallerAbort = () => controller.abort(caller?.reason ?? abortedError());
+	if (caller?.aborted) onCallerAbort();
+	else caller?.addEventListener("abort", onCallerAbort, { once: true });
+	const deadlineReason = new DOMException("The video poll budget elapsed.", "TimeoutError");
+	const timer = setTimeout(() => controller.abort(deadlineReason), Math.max(0, ms));
+	return {
+		signal: controller.signal,
+		expired: (cause) => controller.signal.reason === deadlineReason && cause === deadlineReason,
+		dispose: () => {
+			clearTimeout(timer);
+			caller?.removeEventListener("abort", onCallerAbort);
+		}
+	};
+}
+async function pollVideo(jobHandle, modelId, config, options, extraMetadata) {
+	const interval = options.pollIntervalMs ?? 5e3;
+	const timeout = options.pollTimeoutMs ?? 3e5;
+	const statusParams = { jobHandle };
+	if (config.projectName) statusParams.projectName = config.projectName;
+	const body = serializeMediaBody(statusParams, LABEL);
+	const deadline = pollDeadline(options.abortSignal, timeout);
+	try {
+		return await pollUntilDone(jobHandle, modelId, config, options, extraMetadata, {
+			body,
+			interval,
+			timeout,
+			signal: deadline.signal
+		});
+	} catch (error) {
+		if (deadline.expired(error)) throw new QgridVideoTimeoutError(jobHandle, timeout);
+		throw error;
+	} finally {
+		deadline.dispose();
+	}
+}
+async function pollUntilDone(jobHandle, modelId, config, options, extraMetadata, poll) {
+	const { body, interval, timeout, signal } = poll;
+	const deadline = Date.now() + timeout;
+	let failures = 0;
+	for (;;) {
+		signal.throwIfAborted();
+		let polled;
+		try {
+			polled = await postMediaEndpoint({
+				serverUrl: config.serverUrl,
+				endpoint: "videoStatus",
+				body,
+				schema: videoStatusOutputSchema,
+				label: LABEL,
+				signal,
+				headers: options.headers
+			});
+			failures = 0;
+		} catch (error) {
+			if (!isTransientPollError(error) || ++failures >= MAX_CONSECUTIVE_POLL_FAILURES) throw error;
+		}
+		if (polled) {
+			const status = polled.data;
+			if (status.status === "failed") throw new QgridVideoGenerationError(jobHandle, status.error);
+			if (status.status === "done") {
+				if (!status.url) throw new QgridVideoGenerationError(jobHandle, "completed without a video URL");
+				const requestLogId = status.requestLogId ?? extraMetadata.requestLogId;
+				const xaiMetadata = { videoUrl: status.url };
+				if (status.durationSec !== void 0) xaiMetadata.duration = status.durationSec;
+				if (status.costInUsdTicks !== void 0) xaiMetadata.costInUsdTicks = status.costInUsdTicks;
+				const qgridMetadata = { jobHandle };
+				if (requestLogId !== void 0) qgridMetadata.requestLogId = requestLogId;
+				if (status.costUsd !== void 0) qgridMetadata.costUsd = status.costUsd;
+				return {
+					videos: [{
+						type: "url",
+						url: status.url,
+						mediaType: "video/mp4"
+					}],
+					providerMetadata: {
+						xai: xaiMetadata,
+						qgrid: qgridMetadata
+					},
+					response: {
+						timestamp: /* @__PURE__ */ new Date(),
+						modelId,
+						headers: polled.headers
+					}
+				};
+			}
+		}
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) throw new QgridVideoTimeoutError(jobHandle, timeout);
+		await sleep(Math.min(interval, remaining), signal);
+	}
+}
+/**
+* Keeps polling a video job started by `qgrid.video(...)`, for example after a
+* `QgridVideoTimeoutError`. `config.projectName` must equal the one used to start the job.
+* AI SDK v3 video models expose only `doGenerate` (no `doStart` / `doStatus`), so resuming is
+* a qgrid helper rather than an `experimental_generateVideo` option.
+*/
+function resumeQgridVideo(jobHandle, options = {}) {
+	const config = resolveMediaConfig(options);
+	return pollVideo(jobHandle, options.modelId ?? "grok/video", config, options, {});
+}
+function createQgridVideo(modelId, config) {
+	assertGrokModelId(modelId, LABEL);
+	const resolved = resolveMediaConfig(config);
+	return {
+		specificationVersion: "v3",
+		provider: QGRID_PROVIDER_NAME,
+		modelId,
+		maxVideosPerCall: 1,
+		async doGenerate(options) {
+			if (options.n !== 1) throw new Error(`${LABEL}: one video per call; omit maxVideosPerCall so AI SDK can batch`);
+			if (!options.prompt?.trim()) throw new Error(`${LABEL}: a non-empty text prompt is required`);
+			if (options.duration !== void 0 && (!Number.isInteger(options.duration) || options.duration < 1 || options.duration > 15)) throw new Error(`${LABEL}: duration must be an integer from 1 to 15 seconds`);
+			const qgridOptions = parseGrokQgridOptions(options.providerOptions.qgrid, LABEL);
+			const xai = parseXaiMediaOptions(options.providerOptions.xai, xaiVideoOptionsSchema, XAI_VIDEO_HONORED, LABEL);
+			const xaiOptions = xai.options;
+			if (xaiOptions?.mode === "edit-video" || xaiOptions?.mode === "extend-video" || xaiOptions?.videoUrl !== void 0) throw new Error(`${LABEL}: video editing and extension (mode edit-video / extend-video, videoUrl) are not supported by qgrid`);
+			const referenceImages = (xaiOptions?.referenceImageUrls ?? []).map((url) => toImageRefUrl(url, LABEL));
+			if (referenceImages.length > MAX_REFERENCE_IMAGES) throw new Error(`${LABEL}: at most ${MAX_REFERENCE_IMAGES} reference images are supported`);
+			if (xaiOptions?.mode === "reference-to-video" && referenceImages.length === 0) throw new Error(`${LABEL}: reference-to-video needs providerOptions.xai.referenceImageUrls`);
+			const warnings = [...xai.warnings];
+			if (options.fps !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "fps"
+			});
+			if (options.seed !== void 0) warnings.push({
+				type: "unsupported",
+				feature: "seed"
+			});
+			let resolution = xaiOptions?.resolution ?? void 0;
+			if (resolution === void 0 && options.resolution !== void 0) {
+				resolution = RESOLUTION_MAP.get(options.resolution);
+				if (resolution === void 0) warnings.push({
+					type: "unsupported",
+					feature: "resolution",
+					details: `Unrecognized resolution "${options.resolution}". Use providerOptions.xai.resolution with "480p", "720p", or "1080p" instead.`
+				});
+			}
+			let lastFrame;
+			if (xaiOptions?.lastFrame !== void 0) if (modelId === LAST_FRAME_MODEL) lastFrame = toImageRefUrl(xaiOptions.lastFrame, LABEL);
+			else warnings.push({
+				type: "unsupported",
+				feature: "providerOptions.xai.lastFrame",
+				details: `xAI only supports last_frame with "${LAST_FRAME_MODEL}". The last frame was ignored.`
+			});
+			const image = options.image === void 0 ? void 0 : toImageRef(options.image, LABEL);
+			assertInlineMediaFits([
+				image,
+				lastFrame,
+				...referenceImages
+			], LABEL);
+			const params = {
+				model: modelId,
+				prompt: options.prompt
+			};
+			if (options.duration !== void 0) params.duration = options.duration;
+			if (options.aspectRatio !== void 0) params.aspectRatio = options.aspectRatio;
+			if (resolution !== void 0) params.resolution = resolution;
+			if (image !== void 0) params.image = image;
+			if (lastFrame !== void 0) params.lastFrame = lastFrame;
+			if (referenceImages.length) params.referenceImages = referenceImages;
+			if (xaiOptions?.mode !== void 0) params.mode = xaiOptions.mode;
+			if (resolved.projectName) params.projectName = resolved.projectName;
+			const body = serializeMediaBody({
+				...params,
+				...qgridOptions
+			}, LABEL);
+			const started = await postMediaEndpoint({
+				serverUrl: resolved.serverUrl,
+				endpoint: "videoStart",
+				body,
+				schema: videoStartOutputSchema,
+				label: LABEL,
+				signal: options.abortSignal,
+				headers: options.headers
+			});
+			const pollOptions = {};
+			if (xaiOptions?.pollIntervalMs) pollOptions.pollIntervalMs = xaiOptions.pollIntervalMs;
+			if (xaiOptions?.pollTimeoutMs) pollOptions.pollTimeoutMs = xaiOptions.pollTimeoutMs;
+			if (options.abortSignal) pollOptions.abortSignal = options.abortSignal;
+			if (options.headers) pollOptions.headers = options.headers;
+			return {
+				...await pollVideo(started.data.jobHandle, started.data.model, resolved, pollOptions, started.data.requestLogId === void 0 ? {} : { requestLogId: started.data.requestLogId }),
+				warnings
 			};
 		}
 	};
@@ -794,6 +1961,7 @@ const DEFAULT_RUN_KEY = "__qgrid_default_run__";
 const DEFAULT_STALE_RUN_TIMEOUT_MS = 1800 * 1e3;
 const STALE_RUN_GRACE_MS = 5e3;
 const OVERLAPPING_RUN_ERROR = "createQgridLogger received overlapping runs for the same telemetry key. Pass a unique metadata.qgridRunId per AI SDK call or create a fresh logger integration per call.";
+const qgridRunIdSchema = z.string().min(1);
 function isParseableJson(value) {
 	try {
 		JSON.parse(value ?? "");
@@ -837,7 +2005,7 @@ function createQgridLogger(config = {}) {
 	const onLogError = config.onLogError ?? ((e) => console.warn(`[qgrid-logger] ${e.message}`));
 	const runs = /* @__PURE__ */ new Map();
 	const starting = /* @__PURE__ */ new Map();
-	const keyTtl = typeof config.staleRunTimeoutMs === "number" && config.staleRunTimeoutMs > 0 ? config.staleRunTimeoutMs : DEFAULT_STALE_RUN_TIMEOUT_MS;
+	const keyTtl = config.staleRunTimeoutMs !== void 0 && config.staleRunTimeoutMs > 0 ? config.staleRunTimeoutMs : DEFAULT_STALE_RUN_TIMEOUT_MS;
 	const suppressedRuns = timedKeySet();
 	const quarantined = timedKeySet();
 	const finalizeRun = async (runKey, result) => {
@@ -861,7 +2029,7 @@ function createQgridLogger(config = {}) {
 		}).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e)))));
 		run.pendingToolCalls = [];
 		await Promise.allSettled(run.pendingSteps);
-		await finishRun(serverUrl, {
+		const finishInput = {
 			requestLogId: run.requestLogId,
 			status: result.status,
 			response: result.response,
@@ -872,16 +2040,16 @@ function createQgridLogger(config = {}) {
 			totalOutputTokens: result.totalUsage?.outputTokens ?? 0,
 			totalCacheReadTokens: result.totalUsage?.inputTokenDetails?.cacheReadTokens ?? 0,
 			totalCacheCreationTokens: result.totalUsage?.inputTokenDetails?.cacheWriteTokens ?? 0,
-			totalDurationMs: Date.now() - run.startTime,
-			...run.isStructured && result.status === "succeeded" ? { responseJsonOk: isParseableJson(result.response) } : {},
-			...result.errorMessage ? { errorMessage: result.errorMessage } : {}
-		}).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e))));
+			totalDurationMs: Date.now() - run.startTime
+		};
+		if (run.isStructured && result.status === "succeeded") finishInput.responseJsonOk = isParseableJson(result.response);
+		if (result.errorMessage) finishInput.errorMessage = result.errorMessage;
+		await finishRun(serverUrl, finishInput).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e))));
 	};
 	let autoRunIdCounter = 0;
-	const resolveRunKey = (event) => {
-		const qgridRunId = event.metadata?.qgridRunId;
-		if (typeof qgridRunId === "string" && qgridRunId.length > 0) return `qgridRunId:${qgridRunId}`;
-		if (typeof event.functionId === "string" && event.functionId.length > 0) return `functionId:${event.functionId}`;
+	const resolveRunKey = (qgridRunId, functionId) => {
+		if (qgridRunId !== void 0) return `qgridRunId:${qgridRunId}`;
+		if (functionId) return `functionId:${functionId}`;
 		return DEFAULT_RUN_KEY;
 	};
 	return {
@@ -889,7 +2057,7 @@ function createQgridLogger(config = {}) {
 		integrations: [{
 			async onStart(event) {
 				if (!event.metadata?.qgridRunId && !event.functionId && event.metadata) event.metadata.qgridRunId = `auto-${++autoRunIdCounter}`;
-				const runKey = resolveRunKey(event);
+				const runKey = resolveRunKey(qgridRunIdSchema.safeParse(event.metadata?.qgridRunId).data, event.functionId);
 				if (event.model.provider === "qgrid") return;
 				if (quarantined.has(runKey)) {
 					onLogError(/* @__PURE__ */ new Error("createQgridLogger: telemetry key is quarantined after overlap"));
@@ -953,12 +2121,12 @@ function createQgridLogger(config = {}) {
 						return;
 					}
 					let watchdogTimeout = DEFAULT_STALE_RUN_TIMEOUT_MS;
-					if (typeof config.staleRunTimeoutMs === "number") watchdogTimeout = config.staleRunTimeoutMs;
-					else if (typeof event.timeout === "number" && event.timeout > 0) watchdogTimeout = event.timeout + STALE_RUN_GRACE_MS;
-					else {
-						const totalMs = getRecord(event.timeout)?.totalMs;
-						if (typeof totalMs === "number" && totalMs > 0) watchdogTimeout = totalMs + STALE_RUN_GRACE_MS;
-					}
+					const timeout = event.timeout;
+					if (config.staleRunTimeoutMs !== void 0) watchdogTimeout = config.staleRunTimeoutMs;
+					else if (timeout instanceof Object) {
+						const totalMs = timeout.totalMs;
+						if (totalMs !== void 0 && totalMs > 0) watchdogTimeout = totalMs + STALE_RUN_GRACE_MS;
+					} else if (timeout !== void 0 && timeout > 0) watchdogTimeout = timeout + STALE_RUN_GRACE_MS;
 					let watchdog;
 					if (watchdogTimeout > 0) {
 						watchdog = setTimeout(() => {
@@ -1004,7 +2172,7 @@ function createQgridLogger(config = {}) {
 			},
 			onToolCallFinish(event) {
 				if (event.model?.provider === "qgrid") return;
-				const runKey = resolveRunKey(event);
+				const runKey = resolveRunKey(qgridRunIdSchema.safeParse(event.metadata?.qgridRunId).data, event.functionId);
 				if (suppressedRuns.has(runKey) || quarantined.has(runKey)) return;
 				const run = runs.get(runKey);
 				if (!run) return;
@@ -1012,7 +2180,7 @@ function createQgridLogger(config = {}) {
 			},
 			onStepFinish(event) {
 				if (event.model?.provider === "qgrid") return;
-				const runKey = resolveRunKey(event);
+				const runKey = resolveRunKey(qgridRunIdSchema.safeParse(event.metadata?.qgridRunId).data, event.functionId);
 				if (suppressedRuns.has(runKey) || quarantined.has(runKey)) return;
 				const run = runs.get(runKey);
 				if (!run) return;
@@ -1034,9 +2202,9 @@ function createQgridLogger(config = {}) {
 							toolArgs: pending.toolArgs,
 							modelName: pending.modelName,
 							requestedModelName: pending.requestedModelName,
-							toolResult: tr && "output" in tr ? safeStringify(tr.output) : void 0,
+							toolResult: tr && "output" in tr ? loggedPayloadText.parse(tr.output) : void 0,
 							toolDurationMs: run.toolDurations.get(pending.toolCallId),
-							error: te && "error" in te ? safeStringify(te.error) : void 0
+							error: te && "error" in te ? loggedPayloadText.parse(te.error) : void 0
 						}).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e)))));
 						run.toolDurations.delete(pending.toolCallId);
 					} else remainingPending.push(pending);
@@ -1053,7 +2221,7 @@ function createQgridLogger(config = {}) {
 					cacheReadTokens: usage.inputTokenDetails?.cacheReadTokens ?? 0,
 					cacheCreationTokens: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
 					finishReason,
-					reasoningText: typeof reasoningText === "string" && reasoningText.length > 0 ? reasoningText : void 0,
+					reasoningText: reasoningText !== void 0 && reasoningText.length > 0 ? reasoningText : void 0,
 					reasoningTokens: usage.outputTokenDetails?.reasoningTokens
 				}).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e)))));
 				const toolCalls = content.filter((p) => p.type === "tool-call");
@@ -1068,12 +2236,12 @@ function createQgridLogger(config = {}) {
 							toolCallIndex: i,
 							toolCallId: tc.toolCallId,
 							toolName: tc.toolName,
-							toolArgs: safeStringify(tc.input),
+							toolArgs: loggedPayloadText.parse(tc.input),
 							modelName,
 							requestedModelName,
-							toolResult: tr && "output" in tr ? safeStringify(tr.output) : void 0,
+							toolResult: tr && "output" in tr ? loggedPayloadText.parse(tr.output) : void 0,
 							toolDurationMs: run.toolDurations.get(tc.toolCallId),
-							error: te && "error" in te ? safeStringify(te.error) : void 0
+							error: te && "error" in te ? loggedPayloadText.parse(te.error) : void 0
 						}).catch((e) => onLogError(e instanceof Error ? e : new Error(String(e)))));
 						run.toolDurations.delete(tc.toolCallId);
 					} else run.pendingToolCalls.push({
@@ -1081,7 +2249,7 @@ function createQgridLogger(config = {}) {
 						toolCallIndex: i,
 						toolCallId: tc.toolCallId,
 						toolName: tc.toolName,
-						toolArgs: safeStringify(tc.input),
+						toolArgs: loggedPayloadText.parse(tc.input),
 						modelName,
 						requestedModelName
 					});
@@ -1089,7 +2257,7 @@ function createQgridLogger(config = {}) {
 			},
 			async onFinish(event) {
 				if (event.model?.provider === "qgrid") return;
-				const runKey = resolveRunKey(event);
+				const runKey = resolveRunKey(qgridRunIdSchema.safeParse(event.metadata?.qgridRunId).data, event.functionId);
 				if (suppressedRuns.has(runKey)) {
 					suppressedRuns.remove(runKey);
 					return;
@@ -1100,14 +2268,15 @@ function createQgridLogger(config = {}) {
 				const status = event.finishReason === "error" ? "error" : "succeeded";
 				const requestedModelName = fullModelName(event.model?.provider, event.model?.modelId) ?? run.requestedModelName;
 				const modelName = fullModelName(event.model?.provider, event.response?.modelId);
-				await finalizeRun(runKey, {
+				const result = {
 					status,
 					response: event.text,
 					totalUsage: event.totalUsage,
 					modelName,
-					requestedModelName,
-					...status === "error" && "error" in event ? { errorMessage: getErrorMessage(event.error) } : {}
-				});
+					requestedModelName
+				};
+				if (status === "error" && "error" in event) result.errorMessage = getErrorMessage(event.error);
+				await finalizeRun(runKey, result);
 			}
 		}]
 	};
@@ -1117,12 +2286,175 @@ function createQgridLogger(config = {}) {
 const threadCoordStore = /* @__PURE__ */ new Map();
 const CACHE_AFFINITY_NAMESPACE = "qgrid-cache-affinity-v1";
 const MAX_THREAD_COORDS = 1e3;
+function isGrokModel(modelId) {
+	return modelId.startsWith("grok/");
+}
+const IMAGE_SIGNATURES = [
+	{
+		mediaType: "image/png",
+		bytes: [
+			137,
+			80,
+			78,
+			71
+		]
+	},
+	{
+		mediaType: "image/jpeg",
+		bytes: [
+			255,
+			216,
+			255
+		]
+	},
+	{
+		mediaType: "image/gif",
+		bytes: [
+			71,
+			73,
+			70,
+			56
+		]
+	},
+	{
+		mediaType: "image/webp",
+		bytes: [
+			82,
+			73,
+			70,
+			70
+		]
+	}
+];
+function sniffImageMediaType(bytes) {
+	return IMAGE_SIGNATURES.find((signature) => signature.bytes.every((byte, index) => bytes[index] === byte))?.mediaType;
+}
+function grokImageUrl(part) {
+	const mediaType = part.mediaType.toLowerCase();
+	if (!mediaType.startsWith("image/")) return void 0;
+	const { data } = part;
+	if (data instanceof URL) return data.protocol === "https:" || data.protocol === "data:" ? data.href : void 0;
+	if (data instanceof Uint8Array) {
+		const resolved = mediaType === "image/*" ? sniffImageMediaType(data) : mediaType;
+		return resolved ? `data:${resolved};base64,${bytesToBase64(data)}` : void 0;
+	}
+	if (/^(https:|data:)/i.test(data)) return data;
+	if (mediaType === "image/*") return void 0;
+	return `data:${mediaType};base64,${data}`;
+}
+function grokUserParts(content) {
+	const parts = [];
+	for (const part of content) if (part.type === "text") parts.push({
+		type: "text",
+		text: part.text
+	});
+	else if (part.type === "file") {
+		const url = grokImageUrl(part);
+		if (url !== void 0) parts.push({
+			type: "image",
+			url
+		});
+	}
+	return parts;
+}
+function preparePrompt(modelId, messages) {
+	if (!isGrokModel(modelId)) {
+		const { imageUrls, ...prepared } = extractPromptAndHistory(messages, { includeImages: modelId.startsWith("openai/") });
+		assertImageInputFitsJsonTransport(imageUrls);
+		return prepared;
+	}
+	const extracted = extractPromptAndHistory(messages);
+	const userMessages = messages.filter((message) => message.role === "user");
+	const lastMessage = messages.filter((message) => message.role !== "system").at(-1);
+	const promptMessage = lastMessage?.role === "user" ? lastMessage : void 0;
+	const historyUserMessages = promptMessage ? userMessages.slice(0, -1) : userMessages;
+	let keptImageCount = 0;
+	const imageUrls = [];
+	const countImages = (parts) => {
+		for (const part of parts) if (part.type === "image") {
+			keptImageCount++;
+			imageUrls.push(part.url);
+		}
+	};
+	let historyUserIndex = 0;
+	const history = extracted.history.map((item) => {
+		if (!isUserHistoryMessage(item)) return item;
+		const source = historyUserMessages[historyUserIndex++];
+		if (!source) return item;
+		const parts = grokUserParts(source.content);
+		if (!parts.some((part) => part.type === "image")) return item;
+		countImages(parts);
+		return {
+			type: "message",
+			role: "user",
+			content: parts.map((part) => part.type === "text" ? {
+				type: "input_text",
+				text: part.text
+			} : {
+				type: "input_image",
+				image_url: part.url
+			})
+		};
+	});
+	let input;
+	if (promptMessage) {
+		const parts = grokUserParts(promptMessage.content);
+		if (parts.some((part) => part.type === "image")) {
+			countImages(parts);
+			input = parts.map((part) => part.type === "text" ? {
+				type: "text",
+				text: part.text,
+				text_elements: []
+			} : {
+				type: "image",
+				url: part.url
+			});
+		}
+	}
+	assertImageInputFitsJsonTransport(imageUrls);
+	const prepared = {
+		prompt: extracted.prompt,
+		system: extracted.system,
+		history,
+		droppedImageCount: extracted.droppedImageCount - keptImageCount
+	};
+	if (input) prepared.input = input;
+	return prepared;
+}
+function isUserHistoryMessage(item) {
+	return item.type === "message" && item.role === "user";
+}
+const prepareStreamOutputSchema = z.object({ streamId: z.string() });
+const streamDeltaSchema = z.object({ text: z.string() });
+const streamErrorSchema = z.object({ message: z.string() });
+function resolveXaiOptions(modelId, options) {
+	const raw = options.providerOptions?.xai;
+	if (!isGrokModel(modelId)) return raw === void 0 ? { warnings: [] } : { warnings: [{
+		type: "unsupported",
+		feature: "providerOptions.xai",
+		details: `providerOptions.xai applies only to grok/ models and was ignored for ${modelId}.`
+	}] };
+	const mapped = mapXaiProviderOptions(raw, modelId);
+	const { effort, promptCacheKey } = mapped.request;
+	const resolved = { warnings: mapped.warnings.map((warning) => ({
+		type: "unsupported",
+		feature: `providerOptions.xai.${warning.key}`,
+		details: warning.reason
+	})) };
+	if (effort !== void 0) resolved.effort = effort;
+	if (promptCacheKey !== void 0) resolved.promptCacheKey = promptCacheKey;
+	return resolved;
+}
+const xaiResponseMetadataSchema = z.object({ providerMetadata: z.object({ xai: z.object({
+	costInUsdTicks: z.number().optional(),
+	contextWindow: z.number().optional()
+}) }) });
 function serializeObjectResponseFormat(responseFormat) {
 	const rawSchema = responseFormat?.type === "json" ? responseFormat.schema : void 0;
 	if (rawSchema === void 0) return void 0;
 	const schemaType = rawSchema.type;
 	if (schemaType !== "object") {
-		console.warn(`[qgrid] responseFormat.schema top-level type is "${schemaType ?? "unknown"}". ${TOP_LEVEL_SCHEMA_WARNING}`);
+		console.warn(`[qgrid] responseFormat.schema top-level type is "${Array.isArray(schemaType) ? schemaType.join(",") : schemaType ?? "unknown"}". ${TOP_LEVEL_SCHEMA_WARNING}`);
 		return;
 	}
 	return JSON.stringify(rawSchema);
@@ -1146,7 +2478,7 @@ function setThreadCoord(sessionKey, coord) {
 	});
 	if (threadCoordStore.size > MAX_THREAD_COORDS) threadCoordStore.delete(threadCoordStore.keys().next().value);
 }
-function providerWarnings(options, droppedImageCount) {
+function providerWarnings(options, droppedImageCount, xaiWarnings = []) {
 	const warnings = [];
 	if (options.fallbackModels !== void 0) warnings.push({
 		type: "unsupported",
@@ -1156,9 +2488,9 @@ function providerWarnings(options, droppedImageCount) {
 	if (droppedImageCount > 0) warnings.push({
 		type: "unsupported",
 		feature: "image input",
-		details: `${droppedImageCount} image part(s) were ignored. Only user-message images on openai/ models are sent; for image generation or editing, use generateImage with qgrid.image().`
+		details: `${droppedImageCount} image part(s) were ignored. Only user-message images on openai/ and grok/ models are sent; for image generation or editing, use generateImage with qgrid.image().`
 	});
-	return warnings;
+	return [...warnings, ...xaiWarnings];
 }
 async function deriveCacheAffinityKey(modelId, sessionKey) {
 	if (!sessionKey || modelId.startsWith("anthropic/")) return void 0;
@@ -1167,22 +2499,63 @@ async function deriveCacheAffinityKey(modelId, sessionKey) {
 	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 function qgridProviderMetadata(data) {
-	return { qgrid: {
-		...data.requestLogId !== void 0 ? { requestLogId: data.requestLogId } : {},
-		model: data.model,
-		requestedModel: data.requestedModel ?? data.model,
-		modelFallbacks: data.modelFallbacks ?? [],
-		tokenName: data.tokenName ?? null,
-		durationMs: data.durationMs,
-		costUsd: data.costUsd,
-		costSource: data.costSource,
-		cacheCreation5mInputTokens: data.usage.cache_creation_5m_input_tokens ?? null,
-		cacheCreation1hInputTokens: data.usage.cache_creation_1h_input_tokens ?? null
-	} };
+	const xai = xaiResponseMetadataSchema.safeParse(data);
+	const metadata = {};
+	if (xai.success) {
+		const { costInUsdTicks, contextWindow } = xai.data.providerMetadata.xai;
+		const xaiMetadata = {};
+		if (costInUsdTicks !== void 0) xaiMetadata.costInUsdTicks = costInUsdTicks;
+		if (contextWindow !== void 0) xaiMetadata.contextWindow = contextWindow;
+		if (Object.keys(xaiMetadata).length > 0) metadata.xai = xaiMetadata;
+	}
+	const qgridMetadata = {};
+	if (data.requestLogId !== void 0) qgridMetadata.requestLogId = data.requestLogId;
+	qgridMetadata.model = data.model;
+	qgridMetadata.requestedModel = data.requestedModel ?? data.model;
+	qgridMetadata.modelFallbacks = data.modelFallbacks ?? [];
+	qgridMetadata.tokenName = data.tokenName ?? null;
+	qgridMetadata.durationMs = data.durationMs;
+	qgridMetadata.costUsd = data.costUsd;
+	qgridMetadata.costSource = data.costSource;
+	qgridMetadata.cacheCreation5mInputTokens = data.usage.cache_creation_5m_input_tokens ?? null;
+	qgridMetadata.cacheCreation1hInputTokens = data.usage.cache_creation_1h_input_tokens ?? null;
+	metadata.qgrid = qgridMetadata;
+	return metadata;
+}
+/** JSON callers often pass null for "unset"; these options treated null as absent before. */
+function nullAsUnset(schema) {
+	return schema.nullish().transform((value) => value ?? void 0);
 }
+const qgridProviderOptionsSchema = z.looseObject({
+	thinking: z.boolean().optional(),
+	tokenName: z.string().optional(),
+	logger: nullAsUnset(z.boolean()),
+	fallbackModels: nullAsUnset(z.array(z.string())),
+	sessionKey: nullAsUnset(z.string()),
+	effort: nullAsUnset(z.string()),
+	verbosity: nullAsUnset(z.enum([
+		"low",
+		"medium",
+		"high"
+	])),
+	reasoningSummary: nullAsUnset(z.enum([
+		"auto",
+		"concise",
+		"detailed",
+		"none"
+	])),
+	serviceTier: nullAsUnset(z.string()),
+	timeoutMs: z.number().optional()
+});
 function getQgridProviderOptions(options) {
-	const qgridOptions = options.providerOptions?.qgrid ?? {};
-	if ("imageGeneration" in qgridOptions || "imageGenerationOptions" in qgridOptions) throw new Error("qgrid: imageGeneration and imageGenerationOptions were removed from language-model options. Use generateImage with qgrid.image().");
+	const raw = options.providerOptions?.qgrid ?? {};
+	if ("imageGeneration" in raw || "imageGenerationOptions" in raw) throw new Error("qgrid: imageGeneration and imageGenerationOptions were removed from language-model options. Use generateImage with qgrid.image().");
+	const parsed = qgridProviderOptionsSchema.safeParse(raw);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((issue) => `${issue.path.map(String).join(".") || "(root)"}: ${issue.message}`).join("; ");
+		throw new Error(`qgrid: invalid providerOptions.qgrid: ${issues}`);
+	}
+	const qgridOptions = parsed.data;
 	if (qgridOptions.tokenName !== void 0 && qgridOptions.tokenName.trim() === "") throw new Error("qgrid: tokenName must not be empty");
 	return qgridOptions;
 }
@@ -1206,7 +2579,7 @@ function toAiSdkUsage(usage) {
 }
 function qgrid(modelId, config) {
 	const serverUrl = config?.serverUrl ?? process.env.QGRID_URL ?? "http://localhost:44900";
-	const effort = config?.defaultEffort ?? "low";
+	const effort = config?.defaultEffort ?? (isGrokModel(modelId) ? void 0 : "low");
 	const projectName = config?.projectName ?? process.env.QGRID_PROJECT_NAME;
 	const clientRuns = /* @__PURE__ */ new Map();
 	let anonymousClientRunId = 0;
@@ -1250,17 +2623,16 @@ function qgrid(modelId, config) {
 			const tools = options.tools?.filter((t) => t.type === "function");
 			const hasTools = tools && tools.length > 0;
 			const qgridOptions = getQgridProviderOptions(options);
-			const { prompt, system, history, input, imageUrls, droppedImageCount } = extractPromptAndHistory(options.prompt, { includeImages: modelId.startsWith("openai/") });
-			assertImageInputFitsJsonTransport(imageUrls);
-			const effectiveEffort = qgridOptions.thinking === false ? void 0 : qgridOptions.effort ?? effort;
+			const xaiOptions = resolveXaiOptions(modelId, options);
+			const { prompt, system, history, input, droppedImageCount } = preparePrompt(modelId, options.prompt);
+			const effectiveEffort = qgridOptions.thinking === false ? void 0 : qgridOptions.effort ?? xaiOptions.effort ?? effort;
 			const verbosity = qgridOptions.verbosity;
 			const reasoningSummary = qgridOptions.reasoningSummary;
 			const serviceTier = qgridOptions.serviceTier;
 			const timeoutMs = qgridOptions.timeoutMs;
 			const logger = qgridOptions.logger;
 			const tokenName = qgridOptions.tokenName;
-			const sessionKey = qgridOptions.sessionKey;
-			const cacheAffinityKey = await deriveCacheAffinityKey(modelId, sessionKey);
+			const cacheAffinityKey = await deriveCacheAffinityKey(modelId, qgridOptions.sessionKey ?? xaiOptions.promptCacheKey);
 			const jsonSchema = serializeObjectResponseFormat(options.responseFormat);
 			let runContext;
 			let toolResultsPayload;
@@ -1272,33 +2644,35 @@ function qgrid(modelId, config) {
 			const storedCoord = cacheAffinityKey ? getThreadCoord(cacheAffinityKey) : void 0;
 			if (!matchedClientRun && storedCoord) runContext = { threadCoord: storedCoord };
 			const transport = createQgridRequestTransport(modelId, timeoutMs);
-			const data = await qgridFetch(`${serverUrl}/api/qgrid/query`, {
+			const args = {
+				prompt,
+				model: modelId,
+				system,
+				effort: effectiveEffort,
+				thinking: qgridOptions.thinking
+			};
+			if (input) args.input = input;
+			if (verbosity) args.verbosity = verbosity;
+			if (reasoningSummary) args.reasoningSummary = reasoningSummary;
+			if (serviceTier) args.serviceTier = serviceTier;
+			if (timeoutMs !== void 0) args.timeout = timeoutMs;
+			if (hasTools) args.tools = tools.map(toQgridTool);
+			if (jsonSchema) args.jsonSchema = jsonSchema;
+			if (history.length > 0) args.history = JSON.stringify(history);
+			if (projectName) args.projectName = projectName;
+			if (cacheAffinityKey) args.cacheAffinityKey = cacheAffinityKey;
+			if (logger === false) args.logger = false;
+			if (tokenName) args.tokenName = tokenName;
+			if (runContext) args.runContext = runContext;
+			if (toolResultsPayload) args.toolResults = toolResultsPayload;
+			const init = {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ args: {
-					prompt,
-					...input ? { input } : {},
-					model: modelId,
-					system,
-					effort: effectiveEffort,
-					thinking: qgridOptions.thinking,
-					...verbosity ? { verbosity } : {},
-					...reasoningSummary ? { reasoningSummary } : {},
-					...serviceTier ? { serviceTier } : {},
-					...timeoutMs !== void 0 ? { timeout: timeoutMs } : {},
-					...hasTools ? { tools: tools.map(toQgridTool) } : {},
-					...jsonSchema ? { jsonSchema } : {},
-					...history.length > 0 ? { history: JSON.stringify(history) } : {},
-					...projectName ? { projectName } : {},
-					...cacheAffinityKey ? { cacheAffinityKey } : {},
-					...logger === false ? { logger: false } : {},
-					...tokenName ? { tokenName } : {},
-					...runContext ? { runContext } : {},
-					...toolResultsPayload ? { toolResults: toolResultsPayload } : {}
-				} }),
-				signal: options.abortSignal,
-				...transport ? { dispatcher: transport.dispatcher } : {}
-			}, {
+				body: JSON.stringify({ args }),
+				signal: options.abortSignal
+			};
+			if (transport) init.dispatcher = transport.dispatcher;
+			const data = await qgridFetch(`${serverUrl}/api/qgrid/query`, init, {
 				operation: "query",
 				serverUrl,
 				transportTimeoutMs: transport?.timeoutMs
@@ -1307,7 +2681,7 @@ function qgrid(modelId, config) {
 					const text = await res.text().catch(() => "");
 					throw new Error(`qgrid ${res.status}: ${text}`);
 				}
-				return await res.json();
+				return queryOutputSchema.parse(await res.json());
 			}).finally(() => closeQgridRequestTransport(transport));
 			const content = [];
 			let finishReason = {
@@ -1334,13 +2708,13 @@ function qgrid(modelId, config) {
 				text: data.text
 			});
 			if (matchedClientRun) clientRuns.delete(matchedClientRun.key);
-			if (finishReason.unified === "tool-calls") rememberClientRun(data.runContext, content.filter((c) => c.type === "tool-call").map((c) => c.toolCallId));
+			if (finishReason.unified === "tool-calls") rememberClientRun(data.runContext, content.flatMap((c) => c.type === "tool-call" ? [c.toolCallId] : []));
 			if (cacheAffinityKey && data.runContext?.threadCoord) setThreadCoord(cacheAffinityKey, data.runContext.threadCoord);
 			return {
 				content,
 				finishReason,
 				usage: toAiSdkUsage(data.usage),
-				warnings: providerWarnings(qgridOptions, droppedImageCount),
+				warnings: providerWarnings(qgridOptions, droppedImageCount, xaiOptions.warnings),
 				providerMetadata: qgridProviderMetadata(data),
 				response: { modelId: data.model }
 			};
@@ -1349,17 +2723,16 @@ function qgrid(modelId, config) {
 			const tools = options.tools?.filter((t) => t.type === "function");
 			const hasTools = tools && tools.length > 0;
 			const qgridOptions = getQgridProviderOptions(options);
-			const effectiveEffort = qgridOptions.thinking === false ? void 0 : qgridOptions.effort ?? effort;
+			const xaiOptions = resolveXaiOptions(modelId, options);
+			const effectiveEffort = qgridOptions.thinking === false ? void 0 : qgridOptions.effort ?? xaiOptions.effort ?? effort;
 			const verbosity = qgridOptions.verbosity;
 			const reasoningSummary = qgridOptions.reasoningSummary;
 			const serviceTier = qgridOptions.serviceTier;
 			const timeoutMs = qgridOptions.timeoutMs;
 			const logger = qgridOptions.logger;
 			const tokenName = qgridOptions.tokenName;
-			const { prompt, system, history, input, imageUrls, droppedImageCount } = extractPromptAndHistory(options.prompt, { includeImages: modelId.startsWith("openai/") });
-			assertImageInputFitsJsonTransport(imageUrls);
-			const sessionKey = qgridOptions.sessionKey;
-			const cacheAffinityKey = await deriveCacheAffinityKey(modelId, sessionKey);
+			const { prompt, system, history, input, droppedImageCount } = preparePrompt(modelId, options.prompt);
+			const cacheAffinityKey = await deriveCacheAffinityKey(modelId, qgridOptions.sessionKey ?? xaiOptions.promptCacheKey);
 			const jsonSchema = serializeObjectResponseFormat(options.responseFormat);
 			let runContext;
 			let toolResultsPayload;
@@ -1372,37 +2745,38 @@ function qgrid(modelId, config) {
 			if (!matchedClientRun && storedCoord) runContext = { threadCoord: storedCoord };
 			const abortController = new AbortController();
 			const signal = options.abortSignal ? AbortSignal.any([options.abortSignal, abortController.signal]) : abortController.signal;
+			const args = {
+				prompt,
+				model: modelId,
+				system,
+				effort: effectiveEffort,
+				thinking: qgridOptions.thinking
+			};
+			if (input) args.input = input;
+			if (verbosity) args.verbosity = verbosity;
+			if (reasoningSummary) args.reasoningSummary = reasoningSummary;
+			if (serviceTier) args.serviceTier = serviceTier;
+			if (timeoutMs !== void 0) args.timeout = timeoutMs;
+			if (hasTools) args.tools = tools.map(toQgridTool);
+			if (jsonSchema) args.jsonSchema = jsonSchema;
+			if (history.length > 0) args.history = JSON.stringify(history);
+			if (projectName) args.projectName = projectName;
+			if (cacheAffinityKey) args.cacheAffinityKey = cacheAffinityKey;
+			if (logger === false) args.logger = false;
+			if (tokenName) args.tokenName = tokenName;
+			if (runContext) args.runContext = runContext;
+			if (toolResultsPayload) args.toolResults = toolResultsPayload;
 			const prepRes = await fetch(`${serverUrl}/api/qgrid/prepareStream`, {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify({ args: {
-					prompt,
-					...input ? { input } : {},
-					model: modelId,
-					system,
-					effort: effectiveEffort,
-					thinking: qgridOptions.thinking,
-					...verbosity ? { verbosity } : {},
-					...reasoningSummary ? { reasoningSummary } : {},
-					...serviceTier ? { serviceTier } : {},
-					...timeoutMs !== void 0 ? { timeout: timeoutMs } : {},
-					...hasTools ? { tools: tools.map(toQgridTool) } : {},
-					...jsonSchema ? { jsonSchema } : {},
-					...history.length > 0 ? { history: JSON.stringify(history) } : {},
-					...projectName ? { projectName } : {},
-					...cacheAffinityKey ? { cacheAffinityKey } : {},
-					...logger === false ? { logger: false } : {},
-					...tokenName ? { tokenName } : {},
-					...runContext ? { runContext } : {},
-					...toolResultsPayload ? { toolResults: toolResultsPayload } : {}
-				} }),
+				body: JSON.stringify({ args }),
 				signal
 			});
 			if (!prepRes.ok) {
 				const text = await prepRes.text().catch(() => "");
 				throw new Error(`qgrid prepareStream ${prepRes.status}: ${text}`);
 			}
-			const { streamId } = await prepRes.json();
+			const { streamId } = prepareStreamOutputSchema.parse(await prepRes.json());
 			const streamRes = await fetch(`${serverUrl}/api/qgrid/queryStream?streamId=${streamId}`, { signal });
 			if (!streamRes.ok || !streamRes.body) {
 				const text = await streamRes.text().catch(() => "");
@@ -1428,14 +2802,14 @@ function qgrid(modelId, config) {
 				try {
 					controller.enqueue({
 						type: "stream-start",
-						warnings: providerWarnings(qgridOptions, droppedImageCount)
+						warnings: providerWarnings(qgridOptions, droppedImageCount, xaiOptions.warnings)
 					});
 					let streamCompleted = false;
 					for await (const event of parseSSE(streamRes.body, signal)) {
 						if (cancelled) return;
 						signal.throwIfAborted();
 						if (event.type === "delta") {
-							const raw = event.data.text;
+							const raw = streamDeltaSchema.parse(event.data).text;
 							const text = envelopeParser ? envelopeParser.push(raw) : raw;
 							if (text !== "") {
 								if (!textStarted) {
@@ -1460,7 +2834,7 @@ function qgrid(modelId, config) {
 								});
 								textStarted = false;
 							}
-							const done = event.data;
+							const done = queryOutputSchema.parse(event.data);
 							if (matchedClientRun) clientRuns.delete(matchedClientRun.key);
 							if (done.finishReason === "tool-calls") rememberClientRun(done.runContext, (done.content ?? []).filter((c) => c.type === "tool-call").map((c) => c.toolCallId));
 							if (cacheAffinityKey && done.runContext?.threadCoord) setThreadCoord(cacheAffinityKey, done.runContext.threadCoord);
@@ -1524,7 +2898,8 @@ function qgrid(modelId, config) {
 							return;
 						} else if (event.type === "error") {
 							streamCompleted = true;
-							controller.error(new Error(event.data.message));
+							const streamError = streamErrorSchema.safeParse(event.data);
+							controller.error(new Error(streamError.success ? streamError.data.message : JSON.stringify(event.data)));
 							return;
 						}
 					}
@@ -1541,5 +2916,8 @@ function qgrid(modelId, config) {
 	};
 }
 qgrid.image = createQgridImage;
+qgrid.video = createQgridVideo;
+qgrid.transcription = createQgridTranscription;
+qgrid.speech = createQgridSpeech;
 //#endregion
-export { createQgridLogger, qgrid as default, qgrid };
+export { QGRID_MAX_REQUEST_BODY_BYTES, QgridMediaHttpError, QgridVideoGenerationError, QgridVideoTimeoutError, QgridXaiOptionsError, createQgridLogger, qgrid as default, qgrid, resumeQgridVideo };