@alvin0/ai-agent-sdk-provider-http 0.1.3 → 0.1.4

package/dist/index.js

@@ -12,6 +12,7 @@ const HTTP_PROVIDER_ERROR_CODES = Object.freeze({
 	HEADER_INVALID: "HTTP_HEADER_INVALID",
 	HEADER_RESERVED: "HTTP_HEADER_RESERVED",
 	HEADER_COLLISION: "HTTP_HEADER_COLLISION",
+	QUERY_INVALID: "HTTP_QUERY_INVALID",
 	WIRE_BODY_INVALID: "HTTP_WIRE_BODY_INVALID",
 	WIRE_BODY_TOO_LARGE: "HTTP_WIRE_BODY_TOO_LARGE",
 	STREAM_MEDIA_TYPE_INVALID: "HTTP_STREAM_MEDIA_TYPE_INVALID",
@@ -225,6 +226,11 @@ const DEFAULT_TRANSPORT_HEADERS = Object.freeze({
 	accept: "text/event-stream"
 });
 const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+* Connection-level names `fetch` itself forbids or that would corrupt the
+* request no matter which layer sets them. Never overridable, by design
+* (decision 12): this is the one category ordinary layering cannot reach.
+*/
 const FORBIDDEN_TRANSPORT_NAMES = /* @__PURE__ */ new Set([
 	"connection",
 	"content-length",
@@ -236,9 +242,6 @@ const FORBIDDEN_TRANSPORT_NAMES = /* @__PURE__ */ new Set([
 	"transfer-encoding",
 	"upgrade"
 ]);
-const TRANSPORT_OWNED_NAMES = /* @__PURE__ */ new Set(["accept", "content-type"]);
-const SDK_OWNED_NAMES = /* @__PURE__ */ new Set(["user-agent"]);
-const SDK_OWNED_PREFIXES = ["x-ai-agent-sdk-"];
 const SENSITIVE_NAME = /authorization|api[-_]?key|token|secret|cookie|account[-_]?id|signature/i;
 /** Conservative fallback used in addition to exact authentication provenance. */
 function isSensitiveHeaderName(name) {
@@ -262,20 +265,30 @@ function captureHeaderLayer(input) {
 		headers: Object.freeze(output)
 	});
 }
-/** Validate five case-insensitive ownership layers and return one detached snapshot. */
+/**
+* Merge case-insensitive header layers in precedence order and return one
+* detached snapshot.
+*
+* A later layer in `layers` wins over an earlier one for the same name — the
+* caller's array order IS the precedence order (transport, sdk-attribution,
+* wire-protocol, endpoint, auth, per decision 12: the user's own
+* configuration always outranks what the SDK sets for itself). Only two
+* things stay hard-blocked regardless of position: a connection-level name
+* `fetch` itself forbids ({@link FORBIDDEN_TRANSPORT_NAMES}, plus `sec-*` /
+* `proxy-*`), and a credential-shaped name arriving from any layer other
+* than `'auth'` — not because it cannot be overridden, but so the SDK always
+* knows which headers to redact in logs.
+*/
 function mergeHeaderLayers(layers) {
 	const output = Object.create(null);
-	const owners = /* @__PURE__ */ new Map();
 	const sensitive = /* @__PURE__ */ new Set();
 	for (const raw of layers) {
 		const input = captureHeaderLayer(raw);
 		for (const [name, value] of Object.entries(input.headers)) {
-			const first = owners.get(name);
-			if (first !== void 0) throw headerError(`Header ownership collision between ${first} and ${input.layer}`, "HEADER_COLLISION");
 			validateHeaderOwnership(name, input.layer);
-			owners.set(name, input.layer);
 			output[name] = value;
 			if (input.layer === "auth") sensitive.add(name);
+			else sensitive.delete(name);
 		}
 	}
 	return Object.freeze({
@@ -294,9 +307,6 @@ function validateHeaderShape(name, value) {
 }
 function validateHeaderOwnership(name, layer) {
 	if (FORBIDDEN_TRANSPORT_NAMES.has(name) || name.startsWith("sec-") || name.startsWith("proxy-")) throw headerError("Header name is reserved by the transport", "HEADER_RESERVED");
-	if (TRANSPORT_OWNED_NAMES.has(name) && layer !== "transport") throw headerError("Header name is owned by the transport layer", "HEADER_RESERVED");
-	if (SDK_OWNED_NAMES.has(name) && layer !== "sdk-attribution") throw headerError("Header name is owned by SDK attribution", "HEADER_RESERVED");
-	if (SDK_OWNED_PREFIXES.some((prefix) => name.startsWith(prefix)) && layer !== "sdk-attribution") throw headerError("Header prefix is owned by SDK attribution", "HEADER_RESERVED");
 	if (isSensitiveHeaderName(name) && layer !== "auth") throw headerError("Credential headers must be supplied by auth", "HEADER_RESERVED");
 }
 function headerError(message, key) {
@@ -557,6 +567,19 @@ function redactHeaders(headers, sensitiveHeaderNames = []) {
 	const provenance = new Set(sensitiveHeaderNames.map((name) => name.toLowerCase()));
 	return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, provenance.has(name.toLowerCase()) || isSensitiveHeaderName(name) ? "[REDACTED]" : value]));
 }
+/** Replace credential-bearing query-string values, by name, before logging a URL. */
+function redactQueryUrl(url, sensitiveParamNames = []) {
+	if (sensitiveParamNames.length === 0) return url;
+	const provenance = new Set(sensitiveParamNames.map((name) => name.toLowerCase()));
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return url;
+	}
+	for (const name of [...parsed.searchParams.keys()]) if (provenance.has(name.toLowerCase())) parsed.searchParams.set(name, "[REDACTED]");
+	return parsed.href;
+}
 /** Local correlation id for a diagnostic record, without requiring a crypto global. */
 function requestLogId() {
 	return globalThis.crypto?.randomUUID?.() ?? `request-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
@@ -821,17 +844,18 @@ async function* withTransportSession(input, use) {
 		const url = endpoint.href;
 		const origin = endpoint.origin;
 		const headers = connection.headers;
+		const logId = requestLogId();
 		try {
 			const loggerSignal = AbortSignal.any([signal, AbortSignal.timeout(limits.requestLoggerTimeoutMs)]);
 			await raceWithSignal(Promise.resolve(input.observeRequest?.({
 				schemaVersion: 1,
 				type: "provider-request",
-				id: requestLogId(),
+				id: logId,
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				provider,
 				model,
 				method: "POST",
-				url,
+				url: redactQueryUrl(url, connection.sensitiveQueryParamNames),
 				headers: redactHeaders(headers, connection.sensitiveHeaderNames),
 				body: preparedBody.value,
 				bodyBytes: preparedBody.bytes
@@ -883,6 +907,7 @@ async function* withTransportSession(input, use) {
 				url,
 				origin,
 				signal,
+				requestLogId: logId,
 				accept: input.accept,
 				limits,
 				...providerRequestId === void 0 ? {} : { providerRequestId },
@@ -996,7 +1021,10 @@ function applyModelContextPolicy(info, policy, configured, providerOverride) {
 		standardPriceInputTokens
 	})) if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) throw new TypeError(`${name} must be a positive safe integer`);
 	if (maxContextWindow !== void 0 && (contextWindow !== void 0 && contextWindow > maxContextWindow || defaultContextWindow !== void 0 && defaultContextWindow > maxContextWindow)) throw new RangeError("contextWindow exceeds maxContextWindow");
-	if (contextWindow === void 0) return info;
+	if (contextWindow === void 0) {
+		const { context: _partial, ...withoutContext } = info;
+		return withoutContext;
+	}
 	return {
 		...info,
 		context: {
@@ -1023,26 +1051,34 @@ function catalogModelInfo(provider, model) {
 		id: model.id,
 		name: model.name ?? model.id,
 		...model.description === void 0 ? {} : { description: model.description },
-		inputModalities: model.inputModalities ?? ["text"],
+		...model.inputModalities === void 0 ? {} : { inputModalities: model.inputModalities },
 		...model.outputModalities === void 0 ? {} : { outputModalities: model.outputModalities },
 		...model.nativeTools === void 0 ? {} : { nativeTools: model.nativeTools }
 	};
 }
-/** Resolve exact metadata from an advisory catalog without opening a connection. */
+/**
+* Resolve exact metadata from an advisory catalog without opening a connection.
+*
+* `defaultMaxTokens`/`defaultContextWindow` are the ROUTE's own configured
+* fallbacks (an adapter's `defaultMaxTokens`/`defaultContextWindow` options),
+* not an invented number — omit them and, absent a model-level value too, the
+* field is left off `ResolvedModelInfo` entirely so the registry's own
+* RuntimeDefaults/SDK-constant tier can fill it instead of this adapter guessing.
+*/
 function resolvedCatalogModelInfo(provider, modelId, models, defaultMaxTokens, defaultContextWindow) {
 	const configured = models.find((entry) => entry.id === modelId);
+	const resolvedMaxTokens = configured?.defaultMaxTokens ?? configured?.maxTokens ?? defaultMaxTokens;
 	return applyModelContextPolicy({
 		...configured === void 0 ? {
 			provider,
 			id: modelId,
-			name: modelId,
-			inputModalities: ["text"]
+			name: modelId
 		} : catalogModelInfo(provider, configured),
-		context: { contextWindow: configured?.contextWindow ?? defaultContextWindow },
-		defaultMaxTokens: configured?.defaultMaxTokens ?? configured?.maxTokens ?? defaultMaxTokens,
+		...resolvedMaxTokens === void 0 ? {} : { defaultMaxTokens: resolvedMaxTokens },
 		...configured?.maxTokens === void 0 ? {} : { maxOutputTokens: configured.maxTokens },
 		...configured?.reasoning === void 0 ? {} : { reasoning: configured.reasoning },
-		...configured?.outputModalities === void 0 ? {} : { outputModalities: configured.outputModalities }
+		...configured?.outputModalities === void 0 ? {} : { outputModalities: configured.outputModalities },
+		...defaultContextWindow === void 0 ? {} : { context: { defaultContextWindow } }
 	}, void 0, configured);
 }
 
@@ -1093,6 +1129,19 @@ function resolveSseLimits(connection) {
 		maxEventChars: positiveInteger(connection.maxSseEventChars ?? 1048576, "maxSseEventChars")
 	});
 }
+/**
+* Mirror every decoded SSE event into `sink` on the way through, unchanged.
+*
+* `sink` grows only as fast as `parseSseBounded` already lets it — bounded by
+* the SAME `maxEvents`/`maxEventChars` this generator's caller resolved — so
+* this adds no bound of its own and no risk of it drifting from the real one.
+*/
+async function* tapSseEvents(events, sink) {
+	for await (const event of events) {
+		sink.push(event);
+		yield event;
+	}
+}
 /** Base for every HTTP provider adapter in this package. */
 var HttpModelAdapter = class extends ModelAdapter {
 	/**
@@ -1114,6 +1163,15 @@ var HttpModelAdapter = class extends ModelAdapter {
 	*/
 	observeRequest(_record) {}
 	/**
+	* Observe the exact, header-redacted wire response once a stream ends.
+	*
+	* The default is a no-op so library users do not silently persist model
+	* output. Fired best-effort from a `finally`, after the consumer has
+	* already seen every chunk — a slow or failing sink here can neither delay
+	* nor break the real call.
+	*/
+	observeResponse(_record) {}
+	/**
 	* Map a non-2xx response to a stable code. Override only to add codes this
 	* provider reports that the shared mapping cannot infer from the status.
 	*/
@@ -1130,12 +1188,12 @@ var HttpModelAdapter = class extends ModelAdapter {
 		return this.captureConnection(await this.connect(provider, signal)).models.map((model) => catalogModelInfo(provider, model));
 	}
 	async resolveModel(provider, model, signal) {
-		const connection = this.captureConnection(await this.connect(provider, signal));
+		const connection = this.captureConnection(await this.connect(provider, signal, void 0, model));
 		return this.decorateModel(this.modelInfoFor(connection, provider, model), connection);
 	}
 	async prepareCall(provider, model, signal, context) {
 		context?.declareProviderAttemptAccounting?.();
-		const connection = this.captureConnection(await this.connect(provider, signal, context));
+		const connection = this.captureConnection(await this.connect(provider, signal, context, model));
 		const info = this.decorateModel(this.modelInfoFor(connection, provider, model), connection);
 		const wireBody = {};
 		return {
@@ -1155,7 +1213,7 @@ var HttpModelAdapter = class extends ModelAdapter {
 	/** Resolve a connection first, for the un-prepared entry point. */
 	async *runResolving(options, context) {
 		context?.declareProviderAttemptAccounting?.();
-		const connection = this.captureConnection(await this.connect(options.provider, options.signal, context));
+		const connection = this.captureConnection(await this.connect(options.provider, options.signal, context, options.model));
 		const info = this.decorateModel(this.modelInfoFor(connection, options.provider, options.model), connection);
 		yield* this.run(options, connection, info, context, {});
 	}
@@ -1181,13 +1239,16 @@ var HttpModelAdapter = class extends ModelAdapter {
 	*/
 	async *run(options, connection, model, context, wireBodyCache = {}) {
 		context?.declareProviderAttemptAccounting?.();
-		if (options.messages.some((message) => contentHasImage(message.content)) && model.inputModalities?.includes("image") !== true) throw new ModelError(`${this.displayName} model "${options.model}" does not accept image input`, MODEL_ERROR_CODES.UNSUPPORTED_CONTENT);
-		if (options.messages.some((message) => contentHasDocument(message.content)) && model.inputModalities?.includes("document") !== true) throw new ModelError(`${this.displayName} model "${options.model}" does not accept document input`, MODEL_ERROR_CODES.UNSUPPORTED_CONTENT);
+		if (options.messages.some((message) => contentHasImage(message.content)) && model.inputModalities !== void 0 && !model.inputModalities.includes("image")) throw new ModelError(`${this.displayName} model "${options.model}" does not accept image input`, MODEL_ERROR_CODES.UNSUPPORTED_CONTENT);
+		if (options.messages.some((message) => contentHasDocument(message.content)) && model.inputModalities !== void 0 && !model.inputModalities.includes("document")) throw new ModelError(`${this.displayName} model "${options.model}" does not accept document input`, MODEL_ERROR_CODES.UNSUPPORTED_CONTENT);
+		const resolvedMaxTokens = options.maxTokens ?? model.defaultMaxTokens ?? connection.defaultMaxTokens;
 		const request = {
 			options,
 			model,
 			connection,
-			maxTokens: options.maxTokens ?? model.defaultMaxTokens ?? connection.defaultMaxTokens
+			...resolvedMaxTokens === void 0 ? {} : { maxTokens: resolvedMaxTokens },
+			...context?.agentId === void 0 ? {} : { agentId: context.agentId },
+			...context?.providerOptions?.body === void 0 ? {} : { providerOptionsBody: context.providerOptions.body }
 		};
 		const sseLimits = resolveSseLimits(connection);
 		const adapter = this;
@@ -1234,39 +1295,61 @@ var HttpModelAdapter = class extends ModelAdapter {
 		const declaredLength = response.headers.get("content-length");
 		if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > maxResponseBytes) throw new ModelError(`${this.displayName} response exceeds the ${maxResponseBytes}-byte limit`, MODEL_ERROR_CODES.TRANSPORT);
 		const idleDeadline = createStreamIdleDeadline(request.connection.streamIdleTimeoutMs, this.displayName, 3e4);
-		const events = parseSseBounded(boundedResponseBody(response.body, maxResponseBytes, session.limits.maxResponseChunks, this.displayName, session.signal), idleDeadline.activity, 3e4, {
+		const rawFrames = [];
+		const events = tapSseEvents(parseSseBounded(boundedResponseBody(response.body, maxResponseBytes, session.limits.maxResponseChunks, this.displayName, session.signal), idleDeadline.activity, 3e4, {
 			maxEvents: sse.maxEvents,
 			maxEventChars: sse.maxEventChars
-		});
+		}), rawFrames);
 		const translated = requireTerminalFinish(this.translate(events, request), this.displayName);
-		for await (const chunk of idleDeadline.guard(translated)) {
-			if (chunk.type === "usage-progress") {
-				session.reportUsage(chunk.usage, false);
-				const validated = validateUsageCounters(chunk.usage, true);
-				if (Object.keys(validated.reported).length > 0) yield {
-					type: "usage-progress",
-					usage: validated.reported,
-					...session.attemptId === void 0 ? {} : { attemptId: session.attemptId }
-				};
-				continue;
-			}
-			if (chunk.type === "usage") {
-				session.reportUsage(chunk.usage);
-				const validated = validateUsageCounters(chunk.usage, true);
-				if (!validated.complete) continue;
-				yield {
-					type: "usage",
-					usage: validated.reported
-				};
-				continue;
-			}
-			if (chunk.type === "finish") {
-				const status = chunk.reason.kind === "aborted" ? "aborted" : chunk.reason.kind === "error" ? "error" : "success";
-				session.reportOutcome(status, chunk.reason.kind === "error" || chunk.reason.kind === "aborted" ? chunk.reason.failure : void 0);
+		try {
+			for await (const chunk of idleDeadline.guard(translated)) {
+				if (chunk.type === "usage-progress") {
+					session.reportUsage(chunk.usage, false);
+					const validated = validateUsageCounters(chunk.usage, true);
+					if (Object.keys(validated.reported).length > 0) yield {
+						type: "usage-progress",
+						usage: validated.reported,
+						...session.attemptId === void 0 ? {} : { attemptId: session.attemptId }
+					};
+					continue;
+				}
+				if (chunk.type === "usage") {
+					session.reportUsage(chunk.usage);
+					const validated = validateUsageCounters(chunk.usage, true);
+					if (!validated.complete) continue;
+					yield {
+						type: "usage",
+						usage: validated.reported
+					};
+					continue;
+				}
+				if (chunk.type === "finish") {
+					const status = chunk.reason.kind === "aborted" ? "aborted" : chunk.reason.kind === "error" ? "error" : "success";
+					session.reportOutcome(status, chunk.reason.kind === "error" || chunk.reason.kind === "aborted" ? chunk.reason.failure : void 0);
+				}
+				yield chunk;
 			}
-			yield chunk;
+		} finally {
+			this.emitResponseLog(request, session, rawFrames);
 		}
 	}
+	/** Best-effort delivery of one response record; see `observeResponse`'s doc comment. */
+	async emitResponseLog(request, session, frames) {
+		try {
+			await this.observeResponse({
+				schemaVersion: 1,
+				type: "provider-response",
+				id: session.requestLogId,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				provider: request.options.provider,
+				model: request.options.model,
+				status: session.response.status,
+				headers: redactHeaders(Object.fromEntries(session.response.headers.entries())),
+				...session.providerRequestId === void 0 ? {} : { providerRequestId: session.providerRequestId },
+				frames
+			});
+		} catch {}
+	}
 	async prepareWireBody(request, signal) {
 		signal.throwIfAborted();
 		const value = await raceWithSignal(Promise.resolve(this.buildBody(request)), signal);
@@ -1552,8 +1635,70 @@ function observeModelCatalogOperation(context, provider, origin, task) {
 	}, task);
 }
 
+//#endregion
+//#region src/common/request-path.ts
+/** Fold extra query parameters onto a request path, resolving a function form first. */
+function appendQuery(path, query) {
+	const resolved = typeof query === "function" ? query() : query;
+	if (resolved === void 0) return path;
+	const params = new URLSearchParams(resolved).toString();
+	if (params.length === 0) return path;
+	return `${path}${path.includes("?") ? "&" : "?"}${params}`;
+}
+
+//#endregion
+//#region src/common/body-merge.ts
+/**
+* Deep-merge `override` onto a serialized request body.
+*
+* The user's value always wins, including over a field the SDK itself set
+* (`model`, `max_tokens`, `reasoning`, `stream`, …) — decision 12. A `null`
+* value deletes the key outright, the escape hatch for removing an SDK-set
+* field without reaching for `transformRequest`. Two plain objects at the same
+* key merge recursively; anything else (an array, a primitive, a plain object
+* merging onto a non-object) replaces the base value wholesale — merging an
+* array element-wise would silently reorder or interleave items the caller
+* never asked to touch.
+*/
+function mergeRequestBody(base, override) {
+	const target = isPlainObject(base) ? { ...base } : {};
+	for (const [key, value] of Object.entries(override)) {
+		if (value === null) {
+			delete target[key];
+			continue;
+		}
+		const existing = target[key];
+		target[key] = isPlainObject(value) && isPlainObject(existing) ? mergeRequestBody(existing, value) : value;
+	}
+	return target;
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
 //#endregion
 //#region src/configurable/http-provider.ts
+/** Normalize a single scheme or an array of schemes into an array. */
+function authSchemesOf(auth) {
+	return Array.isArray(auth) ? auth : [auth];
+}
+/** Union several name/value records, case-insensitively, failing fast on a name two entries both set. */
+function unionByName(entries, kind) {
+	const output = {};
+	const owners = /* @__PURE__ */ new Map();
+	entries.forEach((entry, index) => {
+		for (const [name, value] of Object.entries(entry)) {
+			const lower = name.toLowerCase();
+			const first = owners.get(lower);
+			if (first !== void 0 && first !== index) throw new AgentSdkError(`Two auth schemes both produced the \`${lower}\` ${kind}`, HTTP_PROVIDER_ERROR_CODES.HEADER_COLLISION);
+			owners.set(lower, index);
+			output[name] = value;
+		}
+	});
+	return output;
+}
 const DEFAULT_CATALOG_TTL_MS = 3e5;
 const DEFAULT_CATALOG_STALE_TTL_MS = 0;
 const DEFAULT_CATALOG_FAILURE_BACKOFF_MS = 5e3;
@@ -1589,10 +1734,12 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 			catalogFailureBackoffMs: nonNegativeFinite(options.catalogFailureBackoffMs ?? DEFAULT_CATALOG_FAILURE_BACKOFF_MS, "catalogFailureBackoffMs"),
 			maxCatalogModels,
 			maxCatalogBytes,
-			auth: Object.freeze({ ...options.auth }),
+			auth: Object.freeze(authSchemesOf(options.auth).map((scheme) => Object.freeze({ ...scheme }))),
 			...models === void 0 ? {} : { models },
 			...options.headers === void 0 || typeof options.headers === "function" ? {} : { headers: Object.freeze({ ...options.headers }) },
-			...options.baseHeaders === void 0 ? {} : { baseHeaders: Object.freeze({ ...options.baseHeaders }) }
+			...options.baseHeaders === void 0 ? {} : { baseHeaders: Object.freeze({ ...options.baseHeaders }) },
+			...options.query === void 0 || typeof options.query === "function" ? {} : { query: Object.freeze({ ...options.query }) },
+			...options.body === void 0 ? {} : { body: Object.freeze({ ...options.body }) }
 		});
 		this.displayName = options.displayName;
 		this.dialect = resolveDialect(options.protocol, options.dialect);
@@ -1609,7 +1756,7 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 	resolveModel(provider, model, signal) {
 		if (!this.hasStaticCatalog()) return super.resolveModel(provider, model, signal);
 		signal?.throwIfAborted();
-		return Promise.resolve(this.decorateModel(resolvedCatalogModelInfo(provider, model, this.options.models ?? [], this.options.defaultMaxTokens ?? 8192, this.options.defaultContextWindow ?? 128e3)));
+		return Promise.resolve(this.decorateModel(resolvedCatalogModelInfo(provider, model, this.options.models ?? [], this.options.defaultMaxTokens, this.options.defaultContextWindow)));
 	}
 	async modelCatalog(provider, options = {}) {
 		if (this.hasStaticCatalog()) {
@@ -1638,26 +1785,70 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 	staticModels(provider) {
 		return Object.freeze((this.options.models ?? []).map((model) => Object.freeze(catalogModelInfo(provider, model))));
 	}
-	/** Resolve the authentication headers for one operation. */
-	async authHeaders(provider, signal, context) {
-		const auth = this.options.auth;
+	/** Resolve one scheme for one operation, as either a header or a query param. */
+	async authSchemeResolved(auth, provider, signal, context) {
 		switch (auth.kind) {
-			case "none": return { headers: {} };
-			case "bearer": return { headers: { authorization: `Bearer ${await observeCredentialOperation(context, provider, "resolve", () => credential(auth.token, this.displayName, auth.label ?? "the `auth.token` option", signal, context))}` } };
+			case "none": return {
+				headers: {},
+				query: {}
+			};
+			case "bearer": return {
+				headers: { authorization: `Bearer ${await observeCredentialOperation(context, provider, "resolve", () => credential(auth.token, this.displayName, auth.label ?? "the `auth.token` option", signal, context))}` },
+				query: {}
+			};
 			case "header": {
 				const value = await observeCredentialOperation(context, provider, "resolve", () => credential(auth.value, this.displayName, auth.label ?? `the \`${auth.name}\` credential`, signal, context));
-				return { headers: { [auth.name]: value } };
+				return {
+					headers: { [auth.name]: value },
+					query: {}
+				};
+			}
+			case "query": {
+				const value = await observeCredentialOperation(context, provider, "resolve", () => credential(auth.value, this.displayName, auth.label ?? `the \`${auth.name}\` query credential`, signal, context));
+				return {
+					headers: {},
+					query: { [auth.name]: value }
+				};
 			}
-			case "dynamic": return { headers: await observeCredentialOperation(context, provider, "resolve", async () => await auth.resolve(signal, context, provider)) };
-			default: return { headers: {} };
+			case "dynamic": return {
+				headers: await observeCredentialOperation(context, provider, "resolve", async () => await auth.resolve(signal, context, provider)),
+				query: {}
+			};
+			default: return {
+				headers: {},
+				query: {}
+			};
 		}
 	}
-	async connect(provider, signal, context) {
+	/**
+	* Resolve every configured scheme in parallel and union their headers and
+	* query params.
+	*
+	* Two schemes producing the same header name (or the same query param name)
+	* fail fast, before the merged result ever reaches {@link mergeHeaderLayers}
+	* — a collision here is a configuration mistake (the same credential
+	* declared twice, or two schemes racing for `authorization`), not something
+	* a later-layer-wins policy should paper over.
+	*/
+	async authHeaders(provider, signal, context) {
+		const schemes = authSchemesOf(this.options.auth);
+		const resolved = await Promise.all(schemes.map((scheme) => this.authSchemeResolved(scheme, provider, signal, context)));
+		return {
+			headers: unionByName(resolved.map((entry) => entry.headers), "header"),
+			query: unionByName(resolved.map((entry) => entry.query), "query param")
+		};
+	}
+	async connect(provider, signal, context, model) {
 		const timeoutMs = positiveFinite(this.options.requestTimeoutMs ?? 6e5, "requestTimeoutMs");
 		const timeout = AbortSignal.timeout(timeoutMs);
 		const operationSignal = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
 		const baseUrl = this.options.baseUrl.replace(/\/+$/, "");
-		const extra = typeof this.options.headers === "function" ? this.options.headers() : this.options.headers ?? {};
+		const extra = typeof this.options.headers === "function" ? this.options.headers({
+			provider,
+			...context?.agentId === void 0 ? {} : { agentId: context.agentId },
+			...operationSignal === void 0 ? {} : { signal: operationSignal }
+		}) : this.options.headers ?? {};
+		const modelEntry = model === void 0 ? void 0 : this.options.models?.find((candidate) => candidate.id === model);
 		const publicLayers = [
 			captureHeaderLayer({
 				layer: "transport",
@@ -1674,6 +1865,14 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 			captureHeaderLayer({
 				layer: "endpoint",
 				headers: extra
+			}),
+			captureHeaderLayer({
+				layer: "endpoint",
+				headers: modelEntry?.headers ?? {}
+			}),
+			captureHeaderLayer({
+				layer: "endpoint",
+				headers: context?.providerOptions?.headers ?? {}
 			})
 		];
 		mergeHeaderLayers(publicLayers);
@@ -1687,6 +1886,10 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 			baseUrl,
 			headers,
 			sensitiveHeaderNames: merged.sensitiveHeaderNames,
+			...Object.keys(auth.query).length === 0 ? {} : {
+				queryOverrides: auth.query,
+				sensitiveQueryParamNames: Object.freeze(Object.keys(auth.query))
+			},
 			streamIdleTimeoutMs: this.options.streamIdleTimeoutMs ?? 3e5,
 			requestTimeoutMs: this.options.requestTimeoutMs ?? 6e5,
 			maxRequestBytes: this.options.maxRequestBytes ?? 33554432,
@@ -1700,8 +1903,8 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 			...this.options.requestLoggerTimeoutMs === void 0 ? {} : { requestLoggerTimeoutMs: this.options.requestLoggerTimeoutMs },
 			retryPolicy: this.retry,
 			models: this.options.models ?? await this.resolveCatalog(provider, baseUrl, headers, operationSignal, context),
-			defaultMaxTokens: this.options.defaultMaxTokens ?? 8192,
-			defaultContextWindow: this.options.defaultContextWindow ?? 128e3
+			...this.options.defaultMaxTokens === void 0 ? {} : { defaultMaxTokens: this.options.defaultMaxTokens },
+			...this.options.defaultContextWindow === void 0 ? {} : { defaultContextWindow: this.options.defaultContextWindow }
 		};
 	}
 	/** Run the discovery hook, memoized, tolerating failure. */
@@ -1744,14 +1947,29 @@ var ConfiguredHttpAdapter = class extends HttpModelAdapter {
 	observeRequest(record) {
 		return this.options.requestLogger?.(record);
 	}
+	observeResponse(record) {
+		return this.options.responseLogger?.(record);
+	}
 	providerErrorCode(status, detail) {
 		return this.options.errorCode?.(status, detail) ?? super.providerErrorCode(status, detail);
 	}
 	endpointPath(request) {
-		return this.options.protocol.endpointPath(request, this.dialect);
+		const base = this.options.path ?? this.options.protocol.endpointPath(request, this.dialect);
+		const withRouteQuery = appendQuery(base, this.options.query);
+		return request.connection.queryOverrides === void 0 ? withRouteQuery : appendQuery(withRouteQuery, request.connection.queryOverrides);
 	}
 	buildBody(request) {
-		return this.options.protocol.serialize(request, this.dialect);
+		const serialized = this.options.protocol.serialize(request, this.dialect);
+		const withRouteBody = this.options.body === void 0 ? serialized : mergeRequestBody(serialized, this.options.body);
+		const modelBody = this.options.models?.find((candidate) => candidate.id === request.model.id)?.body;
+		const withModelBody = modelBody === void 0 ? withRouteBody : mergeRequestBody(withRouteBody, modelBody);
+		const merged = request.providerOptionsBody === void 0 ? withModelBody : mergeRequestBody(withModelBody, request.providerOptionsBody);
+		return this.options.transformRequest === void 0 ? merged : this.options.transformRequest(merged, {
+			provider: request.options.provider,
+			model: request.model.id,
+			...request.agentId === void 0 ? {} : { agentId: request.agentId },
+			...request.options.signal === void 0 ? {} : { signal: request.options.signal }
+		});
 	}
 	translate(events, request) {
 		return this.options.protocol.translate(events, request, this.displayName);
@@ -1813,6 +2031,97 @@ function createHttpProvider(options) {
 	return new ConfiguredHttpAdapter(options);
 }
 
+//#endregion
+//#region src/configurable/field-fallback.ts
+/**
+* Fall back to a build of the SAME adapter without an optional wire field,
+* permanently, the first time a dispatch is rejected in a way that names it.
+*
+* Exists for opportunistic fields this SDK adds when a caller opts in — a
+* caching hint, for instance — that the OFFICIAL vendor accepts but a
+* compatible gateway behind the same adapter option may not. Decision 7
+* (this workspace's redesign plan) rules out guessing which gateways support
+* such a field ahead of time; this is the alternative that costs nothing
+* when the field IS understood and self-heals, once, the one time it is
+* not — rather than failing every call to that gateway forever.
+*
+* @module ai-agent-sdk/providers/configurable/field-fallback
+*/
+/**
+* Delegates to `withField` until a dispatch fails in a way
+* `isFieldRejection` recognizes, then delegates to `withoutField` for the
+* rest of this instance's lifetime — including the call that just failed,
+* retried transparently so the caller never sees the rejection.
+*
+* Metadata methods (`resolveModel`, `listModels`, `modelCatalog`,
+* `providerInfo`, `providerRetryPolicy`) always read from `withField`: the
+* two builds differ only in the one wire field this wraps, never in what
+* models or capabilities the route reports.
+*/
+var FieldFallbackAdapter = class extends ModelAdapter {
+	#withField;
+	#withoutField;
+	#isFieldRejection;
+	#disabled = false;
+	constructor(withField, withoutField, options) {
+		super();
+		this.#withField = withField;
+		this.#withoutField = withoutField;
+		this.#isFieldRejection = options.isFieldRejection;
+	}
+	providerInfo(provider) {
+		return this.#withField.providerInfo(provider);
+	}
+	providerRetryPolicy(provider) {
+		return this.#withField.providerRetryPolicy(provider);
+	}
+	listModels(provider, signal) {
+		return this.#withField.listModels(provider, signal);
+	}
+	modelCatalog(provider, options = {}) {
+		return this.#withField.modelCatalog(provider, options);
+	}
+	resolveModel(provider, model, signal) {
+		return this.#withField.resolveModel(provider, model, signal);
+	}
+	async prepareCall(provider, model, signal, context) {
+		if (this.#disabled) return this.#withoutField.prepareCall(provider, model, signal, context);
+		const prepared = await this.#withField.prepareCall(provider, model, signal, context);
+		return {
+			model: prepared.model,
+			stream: (options, invocation) => this.#dispatch((o, c) => prepared.stream(o, c), () => this.#withoutField.prepareCall(provider, model, signal, context).then((fallback) => (o, c) => fallback.stream(o, c)), options, invocation)
+		};
+	}
+	stream(options, context) {
+		if (this.#disabled) return this.#withoutField.stream(options, context);
+		return this.#dispatch((o, c) => this.#withField.stream(o, c), () => Promise.resolve((o, c) => this.#withoutField.stream(o, c)), options, context);
+	}
+	/**
+	* Run one dispatch, and on a recognized field rejection, disable the field
+	* permanently and re-dispatch through `fallback` — transparently, before
+	* the caller has seen anything but the fallback's own output.
+	*
+	* Safe because a field rejection is always a non-2xx response the shared
+	* HTTP chain throws BEFORE any chunk streams (`withTransportSession` in
+	* `provider-http`'s transport layer): nothing from the failed attempt ever
+	* reaches this generator's consumer, so retrying from scratch never
+	* duplicates output.
+	*/
+	async *#dispatch(primary, prepareFallback, options, context) {
+		if (this.#disabled) {
+			yield* (await prepareFallback())(options, context);
+			return;
+		}
+		try {
+			yield* primary(options, context);
+		} catch (error) {
+			if (!this.#isFieldRejection(error)) throw error;
+			this.#disabled = true;
+			yield* (await prepareFallback())(options, context);
+		}
+	}
+};
+
 //#endregion
 //#region src/common/wire-body.ts
 const WIRE_BODY_LIMITS = Object.freeze({
@@ -1866,17 +2175,25 @@ function createRuntimeHttpProvider(options) {
 	const describeModel = optionalCapturedMethod(source, "describeModel");
 	const errorCode = optionalCapturedMethod(source, "errorCode");
 	const requestLogger = optionalCapturedMethod(source, "requestLogger");
+	const responseLogger = optionalCapturedMethod(source, "responseLogger");
+	const transformRequest = optionalCapturedMethod(source, "transformRequest");
 	const headers = captureHeaders(source);
+	const query = captureQuery(source);
+	const path = capturePath(source);
 	const legacy = {
 		displayName,
 		protocol,
 		baseUrl: baseUrl.href,
 		auth,
 		...copyOptional(source, "allowInsecureHttp"),
+		...path === void 0 ? {} : { path },
 		...copyJsonOptional(source, "models", "models"),
 		...copyJsonOptional(source, "dialect", "dialect"),
 		...fetch === void 0 ? {} : { fetch },
 		...headers === void 0 ? {} : { headers },
+		...query === void 0 ? {} : { query },
+		...copyJsonOptional(source, "body", "body"),
+		...transformRequest === void 0 ? {} : { transformRequest },
 		...copyOptional(source, "catalogTtlMs"),
 		...copyOptional(source, "catalogStaleTtlMs"),
 		...copyOptional(source, "catalogFailureBackoffMs"),
@@ -1898,6 +2215,7 @@ function createRuntimeHttpProvider(options) {
 		...errorCode === void 0 ? {} : { errorCode },
 		...copyHeaderOptional(source, "baseHeaders", "transport"),
 		...requestLogger === void 0 ? {} : { requestLogger },
+		...responseLogger === void 0 ? {} : { responseLogger },
 		...discover === void 0 ? {} : { discoverModels: async (context) => discover({
 			provider: context.provider ?? "",
 			baseUrl: new URL(context.baseUrl),
@@ -1937,6 +2255,10 @@ function captureRuntimeProtocol(value) {
 	}
 }
 function captureRuntimeAuth(value, baseUrl) {
+	if (Array.isArray(value)) return value.map((entry) => captureRuntimeAuthScheme(entry, baseUrl));
+	return captureRuntimeAuthScheme(value, baseUrl);
+}
+function captureRuntimeAuthScheme(value, baseUrl) {
 	const source = plainObject(value, "runtime HTTP auth");
 	const kind = ownData(source, "kind");
 	if (kind === "none") return Object.freeze({ kind });
@@ -1954,6 +2276,15 @@ function captureRuntimeAuth(value, baseUrl) {
 			...copyOptional(source, "label")
 		});
 	}
+	if (kind === "query") {
+		const name = boundedIdentifier(ownData(source, "name"), 256, "auth query param name");
+		return Object.freeze({
+			kind,
+			name,
+			value: captureCredential(ownData(source, "value")),
+			...copyOptional(source, "label")
+		});
+	}
 	if (kind === "dynamic") {
 		const resolve = capturedMethod(source, "resolve");
 		return Object.freeze({
@@ -2001,8 +2332,29 @@ function captureHeaders(source) {
 	const value = ownData(source, "headers", false);
 	if (value === void 0) return void 0;
 	if (typeof value !== "function") return snapshotHeaders(value, "endpoint");
+	const captured = (ctx) => Reflect.apply(value, source, [ctx]);
+	return (ctx) => snapshotHeaders(captured(ctx), "endpoint");
+}
+function capturePath(source) {
+	const value = ownData(source, "path", false);
+	return value === void 0 ? void 0 : boundedIdentifier(value, 2048, "path");
+}
+function captureQuery(source) {
+	const value = ownData(source, "query", false);
+	if (value === void 0) return void 0;
+	if (typeof value !== "function") return snapshotQuery(value);
 	const captured = (...args) => Reflect.apply(value, source, args);
-	return () => snapshotHeaders(captured(), "endpoint");
+	return () => snapshotQuery(captured());
+}
+function snapshotQuery(value) {
+	const snapshot = snapshotJsonObject({ query: value }, HTTP_RUNTIME_OPTION_LIMITS).query;
+	if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) throw new AgentSdkError("Runtime HTTP query must be a record", HTTP_PROVIDER_ERROR_CODES.QUERY_INVALID);
+	const output = {};
+	for (const [key, entry] of Object.entries(snapshot)) {
+		if (typeof entry !== "string") throw new AgentSdkError("Runtime HTTP query values must be strings", HTTP_PROVIDER_ERROR_CODES.QUERY_INVALID);
+		output[key] = entry;
+	}
+	return Object.freeze(output);
 }
 function snapshotHeaders(value, layer) {
 	return mergeHeaderLayers([{
@@ -2066,7 +2418,7 @@ function endpointHeaders(headers, defaults = {}) {
 		layer: "endpoint",
 		headers: value
 	}]).headers;
-	if (typeof headers === "function") return () => capture(headers());
+	if (typeof headers === "function") return (ctx) => capture(headers(ctx));
 	const fixed = capture(headers ?? {});
 	return () => fixed;
 }
@@ -2273,5 +2625,5 @@ function parseJsonBody(text, displayName) {
 }
 
 //#endregion
-export { DEFAULT_MAX_ERROR_BODY_BYTES, DEFAULT_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_MAX_RESPONSE_CHUNKS, DEFAULT_REQUEST_LOGGER_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, HTTP_PROTOCOL_API_VERSION, HTTP_PROVIDER_ERROR_CODES, HttpModelAdapter, JSON_MEDIA_TYPES, applyModelContextPolicy, captureTransportConnection, createHttpProvider, createModelContextPolicy, createRuntimeHttpProvider, defineWireProtocol, embeddingCatalogModelInfo, endpointHeaders, httpErrorCode, isJsonMediaType, observeCredentialOperation, observeModelCatalogOperation, parseErrorBody, parseSse, redactHeaders, requestIdFrom, resolveDialect, resolveTransportLimits, resolvedEmbeddingCatalogModelInfo, retryAfterMs, transportJson };
+export { DEFAULT_MAX_ERROR_BODY_BYTES, DEFAULT_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_MAX_RESPONSE_CHUNKS, DEFAULT_REQUEST_LOGGER_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, FieldFallbackAdapter, HTTP_PROTOCOL_API_VERSION, HTTP_PROVIDER_ERROR_CODES, HttpModelAdapter, JSON_MEDIA_TYPES, applyModelContextPolicy, captureTransportConnection, createHttpProvider, createModelContextPolicy, createRuntimeHttpProvider, defineWireProtocol, embeddingCatalogModelInfo, endpointHeaders, httpErrorCode, isJsonMediaType, observeCredentialOperation, observeModelCatalogOperation, parseErrorBody, parseSse, redactHeaders, requestIdFrom, resolveDialect, resolveTransportLimits, resolvedEmbeddingCatalogModelInfo, retryAfterMs, transportJson };
 //# sourceMappingURL=index.js.map