@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/llm-pi-ai/lib/index.js

@@ -1,14 +1,17 @@
 import { launchEnvironmentOf } from "../../launch-environment/lib/index.js";
-import { CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertUsableApiKey, attributionHeaders, contentHasImage, isContextWindowExceededError, isQuotaExceededError, normalizeApiKey, resolveRetryPolicy } from "../../llm/lib/index.js";
+import { CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertUsableApiKey, attributionHeaders, contentHasImage, isContextWindowExceededError, isQuotaExceededError, normalizeApiKey, offloadRequestImagesWithPolicy, requestImageHandleText, resolveRetryPolicy } from "../../llm/lib/index.js";
 import { deepEqualJson, installSettingsSection, settingsNamespace } from "../../settings/lib/index.js";
 import { createModels, createProvider, getSupportedThinkingLevels, isContextOverflow } from "@earendil-works/pi-ai";
 import { MAX_TIMER_DELAY_MS, idleWatchdog, timeoutOf } from "../../timeout/lib/index.js";
-import { builtinProviders, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
 import z from "../../schemastery/lib/index.mjs";
-import { credentialRef } from "../../credentials/lib/index.js";
+import { credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName } from "../../credentials/lib/index.js";
+import { builtinProviders, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
 import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { homedir } from "node:os";
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
 //#region lib/types/replay.js
 /**
 * Durable pi-ai replay metadata and assistant-history reconstruction.
@@ -241,1269 +244,1700 @@ function toPiAssistant(message, onDegrade) {
 	}
 }
 //#endregion
-//#region lib/types/context.js
+//#region lib/types/catalog.js
 /**
-* Harness request-history conversion into pi-ai's Context vocabulary.
+* Materialization of one provider route's model catalog. The installed pi-ai
+* catalog supplies defaults keyed by model id, and a profile's own model
+* entries override them field by field, so a route naming a catalog provider
+* stays configuration-free while a route pi-ai has never heard of is fully
+* describable from `settings.yaml`.
 *
-* @module nomix-llm-pi-ai/context
+* Every pi-ai `Model` field the harness cannot default is required here rather
+* than at request time: an unserviceable route fails while its configuration is
+* being resolved, which is the earliest point that can name the offending key.
+*
+* @module nomix-llm-pi-ai/catalog
 */
-/** Join the text blocks of a harness message. */
-function flattenText(message) {
-	return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
-}
-/** Flatten text recursively inside one tool result. */
-function toolResultText(blocks) {
-	return blocks.map((block) => block.type === "text" ? block.text : block.type === "tool-result" ? toolResultText(block.content) : "").join("");
-}
-async function userContent(blocks, attachments) {
-	const content = [];
-	for (const block of blocks) switch (block.type) {
-		case "text":
-			if (block.text.length > 0) content.push({
-				type: "text",
-				text: block.text
-			});
-			break;
-		case "image": {
-			const stored = await attachments.readImage(block.attachment);
-			content.push({
-				type: "image",
-				data: Buffer.from(stored.data).toString("base64"),
-				mimeType: stored.ref.mediaType
-			});
-			break;
-		}
-		case "tool-result":
-			{
-				const nested = await userContent(block.content, attachments);
-				if (typeof nested === "string") {
-					if (nested.length > 0) content.push({
-						type: "text",
-						text: nested
-					});
-				} else content.push(...nested);
-			}
-			break;
-		default: break;
-	}
-	if (content.every((block) => block.type === "text")) return content.map((block) => block.text).join("");
-	return content;
-}
-function toolsOf(options) {
-	return options.tools?.map((tool) => ({
-		name: tool.name,
-		description: tool.description,
-		parameters: tool.parameters
-	}));
+/**
+* Pricing for a model the installed catalog does not describe. The harness
+* never reads pi-ai's cost metadata — `replay.ts` zeroes it and no consumer
+* reports spend — so this is the absence of a fact, not a configurable rate.
+*/
+const NO_COST = {
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0
+};
+/** Every request modality a profile may declare. */
+const MODALITIES = Object.keys({
+	text: true,
+	image: true
+});
+/**
+* One entry's modality list, or `undefined` when it states no answer. Absent
+* and empty mean the same thing — `[]` describes a model that accepts nothing
+* and could serve no request — which is what makes an entry naming a catalog
+* model without declaring modalities keep the catalog's, since the config
+* schema materializes `[]` for an absent array.
+* @param configured - the list a `models` or `modelOverrides` entry supplied.
+* @returns the declared modalities, or `undefined` to ask the next level.
+*/
+function declaredInput(configured) {
+	return configured === void 0 || configured.length === 0 ? void 0 : [...configured];
 }
-/** Assemble the request-level pi-ai context envelope shared by both conversion paths. */
-function piContext(options, messages) {
-	const tools = toolsOf(options);
-	return {
-		...options.system !== void 0 ? { systemPrompt: options.system } : {},
-		messages,
-		...tools !== void 0 && tools.length > 0 ? { tools } : {}
-	};
+/** Every pi-ai thinking level a profile may declare, in escalation order. */
+const THINKING_LEVELS = Object.keys({
+	off: true,
+	minimal: true,
+	low: true,
+	medium: true,
+	high: true,
+	xhigh: true,
+	max: true
+});
+/** Reasoning-dispatch wire formats a profile may name, most-reached first. */
+const SUPPORTED_THINKING_FORMATS = Object.keys({
+	"openai": true,
+	"deepseek": true,
+	"openrouter": true,
+	"together": true,
+	"zai": true,
+	"qwen": true,
+	"chat-template": true,
+	"qwen-chat-template": true,
+	"string-thinking": true,
+	"ant-ling": true
+});
+/** The output-cap field spellings a profile may name. */
+const MAX_TOKENS_FIELDS = Object.keys({
+	max_completion_tokens: true,
+	max_tokens: true
+});
+/** The prompt-cache marker conventions a profile may name. */
+const CACHE_CONTROL_FORMATS = Object.keys({ anthropic: true });
+/** The request-state placeholders a profile may name. */
+const CHAT_TEMPLATE_VARS = Object.keys({
+	"thinking.enabled": true,
+	"thinking.effort": true
+});
+let providerIndex;
+/**
+* Installed catalog providers by id, constructed once. Each entry owns the API
+* implementations for its own models, which is why a catalog route reuses this
+* provider instead of being rebuilt from parts.
+* @returns the catalog provider index.
+*/
+function catalogProviders() {
+	providerIndex ??= new Map(builtinProviders().map((provider) => [provider.id, provider]));
+	return providerIndex;
 }
-function textOnlyContext(options, onReplayDegrade) {
-	const toolNames = /* @__PURE__ */ new Map();
-	const messages = [];
-	for (const message of options.messages) {
-		if (contentHasImage(message.content)) throw new LlmError("pi-ai image conversion requires the durable attachment service", "UNSUPPORTED_CONTENT");
-		if (message.role === "system") {
-			messages.push({
-				role: "user",
-				content: flattenText(message),
-				timestamp: 0
-			});
-			continue;
-		}
-		if (message.role === "assistant") {
-			const assistant = toPiAssistant(message, onReplayDegrade);
-			for (const block of assistant.content) if (block.type === "toolCall") toolNames.set(CallId(block.id), block.name);
-			messages.push(assistant);
-			continue;
-		}
-		const text = flattenText(message);
-		const results = message.content.filter((block) => block.type === "tool-result");
-		if (text.length > 0 || results.length === 0) messages.push({
-			role: "user",
-			content: text,
-			timestamp: 0
-		});
-		for (const result of results) messages.push({
-			role: "toolResult",
-			toolCallId: result.toolCallId,
-			toolName: toolNames.get(result.toolCallId) ?? "unknown",
-			content: [{
-				type: "text",
-				text: toolResultText(result.content) || "(no output)"
-			}],
-			isError: result.isError ?? false,
-			timestamp: 0
-		});
-	}
-	return piContext(options, messages);
+/**
+* The installed catalog provider for one route, when pi-ai ships one.
+* @param provider - provider route key.
+* @returns the catalog provider, or `undefined` for a route pi-ai does not ship.
+*/
+function catalogProvider(provider) {
+	return catalogProviders().get(provider);
 }
-function toPiContext(options, attachments, onReplayDegrade) {
-	return attachments === void 0 ? textOnlyContext(options, onReplayDegrade) : toPiContextWithImages(options, attachments, onReplayDegrade);
+/**
+* Every provider route the installed pi-ai catalog ships.
+* @returns the catalog provider ids.
+*/
+function catalogProviderIds() {
+	return getBuiltinProviders();
 }
-async function toPiContextWithImages(options, attachments, onReplayDegrade) {
-	const toolNames = /* @__PURE__ */ new Map();
-	const messages = [];
-	for (const message of options.messages) {
-		if (message.role === "system") {
-			if (contentHasImage(message.content)) throw new LlmError("pi-ai cannot represent an image in an in-history system message", "UNSUPPORTED_CONTENT");
-			messages.push({
-				role: "user",
-				content: flattenText(message),
-				timestamp: 0
-			});
-			continue;
-		}
-		if (message.role === "assistant") {
-			const assistant = toPiAssistant(message, onReplayDegrade);
-			for (const block of assistant.content) if (block.type === "toolCall") toolNames.set(CallId(block.id), block.name);
-			messages.push(assistant);
-			continue;
-		}
-		const content = await userContent(message.content.filter((block) => block.type !== "tool-result"), attachments);
-		const results = message.content.filter((block) => block.type === "tool-result");
-		if (content.length > 0 || results.length === 0) messages.push({
-			role: "user",
-			content,
-			timestamp: 0
-		});
-		for (const result of results) {
-			const resultContent = await userContent(result.content, attachments);
-			messages.push({
-				role: "toolResult",
-				toolCallId: result.toolCallId,
-				toolName: toolNames.get(result.toolCallId) ?? "unknown",
-				content: typeof resultContent === "string" ? [{
-					type: "text",
-					text: resultContent || "(no output)"
-				}] : resultContent,
-				isError: result.isError ?? false,
-				timestamp: 0
-			});
-		}
-	}
-	return piContext(options, messages);
+/**
+* The installed catalog models for one route, indexed by model id.
+* @param provider - provider route key.
+* @returns catalog models by id; empty for a route pi-ai does not ship.
+*/
+function catalogModels(provider) {
+	if (!catalogProviders().has(provider)) return /* @__PURE__ */ new Map();
+	const models = getBuiltinModels(provider);
+	return new Map(models.map((model) => [model.id, model]));
 }
-//#endregion
-//#region lib/types/stream.js
 /**
-* pi-ai assistant event translation into the Harness streaming protocol.
+* Disposition of every `OpenAICompletionsCompat` field. The `Record` key type
+* is a drift gate: a pi-ai upgrade that adds a field fails compilation here
+* until it is classified, so the offer never silently lags the upstream set.
+*/
+const COMPLETIONS_COMPAT_GATE = {
+	supportsStore: "offer",
+	supportsDeveloperRole: "offer",
+	supportsReasoningEffort: "offer",
+	supportsUsageInStreaming: "offer",
+	maxTokensField: "offer",
+	requiresToolResultName: "offer",
+	requiresAssistantAfterToolResult: "offer",
+	requiresThinkingAsText: "offer",
+	requiresReasoningContentOnAssistantMessages: "offer",
+	thinkingFormat: "offer",
+	chatTemplateKwargs: "offer",
+	supportsStrictMode: "offer",
+	cacheControlFormat: "offer",
+	supportsLongCacheRetention: "offer",
+	openRouterRouting: "withhold",
+	vercelGatewayRouting: "withhold",
+	zaiToolStream: "withhold",
+	supportsOpenAIGrammarTools: "withhold",
+	sendSessionAffinityHeaders: "withhold",
+	deferredToolsMode: "withhold",
+	sessionAffinityFormat: "withhold"
+};
+/** Disposition of every `OpenAIResponsesCompat` field; a drift gate like the one above. */
+const RESPONSES_COMPAT_GATE = {
+	supportsDeveloperRole: "offer",
+	supportsStrictMode: "offer",
+	supportsLongCacheRetention: "offer",
+	sessionAffinityFormat: "withhold",
+	supportsOpenAIGrammarTools: "withhold",
+	supportsToolSearch: "withhold",
+	supportsExplicitPromptCacheMode: "withhold"
+};
+/**
+* The compat gate of every wire protocol a profile may configure.
 *
-* pi-ai tool-call arguments are parsed objects while the Harness keeps their
-* raw JSON representation. pi-ai also reports failures as terminal stream
-* events, which this module maps into Harness finish chunks.
+* Keyed by protocol, but grouped by pi-ai's compat *type*: the three Responses
+* protocols share `OpenAIResponsesCompat`, so a switch settable on one is
+* settable on all three. Keying by protocol alone would refuse
+* `azure-openai-responses` and `openai-codex-responses` the fields their own
+* models declare.
+*/
+const COMPAT_GATES = {
+	"openai-completions": COMPLETIONS_COMPAT_GATE,
+	"openai-responses": RESPONSES_COMPAT_GATE,
+	"azure-openai-responses": RESPONSES_COMPAT_GATE,
+	"openai-codex-responses": RESPONSES_COMPAT_GATE,
+	"anthropic-messages": {
+		supportsEagerToolInputStreaming: "offer",
+		supportsLongCacheRetention: "offer",
+		supportsCacheControlOnTools: "offer",
+		supportsTemperature: "offer",
+		forceAdaptiveThinking: "offer",
+		allowEmptySignature: "offer",
+		supportsStrictTools: "offer",
+		sendSessionAffinityHeaders: "withhold",
+		supportsToolReferences: "withhold"
+	},
+	"bedrock-converse-stream": { supportsStrictMode: "offer" }
+};
+/**
+* The compat gate of one resolved protocol. A `string` lookup rather than a
+* keyed read: a route's `api` is configuration, so it may name a protocol
+* pi-ai gives no compat type — or none at all.
+* @param api - resolved wire protocol.
+* @returns that protocol's field gate, or `undefined` when it takes no compat.
+*/
+function compatGate(api) {
+	return COMPAT_GATES[api];
+}
+/**
+* The compat entries a profile actually set.
 *
-* @module nomix-llm-pi-ai/stream
+* schemastery materializes an absent dict as `{}` — the behavior
+* `reasoningEfforts` works around with a union — so every parsed profile
+* carries a `chatTemplateKwargs` key whether or not anyone wrote one. An empty
+* one states nothing here: it would send no kwargs, which is exactly what
+* leaving the field out does, so absent and empty are the same request and
+* neither may make a route look like it configured a switch. A valueless
+* scalar is the other thing schemastery lets through, and it is refused by
+* {@link assertOfferedCompatFields} before this runs rather than filtered.
+* @param compat - the configured switches, when any.
+* @returns the entries carrying a value, in declaration order.
 */
+function configuredCompatEntries(compat) {
+	return Object.entries(compat ?? {}).flatMap(([field, value]) => {
+		return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0 ? [] : [[field, value]];
+	});
+}
 /**
-* Map pi-ai usage (reasoning folded into output by pi-ai).
-* @param usage - cumulative usage from the terminal pi-ai event.
-* @returns harness counts; cache fields appear only when non-zero (pi-ai reports zeros, not absence).
+* The protocols offering one compat field, in {@link COMPAT_GATES} order.
+* @param field - configured compat field name.
+* @returns the protocols whose compat takes it; empty when none does, which
+*   is either a withheld field or a name no upstream compat type declares.
 */
-function mapUsage(usage) {
-	return {
-		inputTokens: usage.input,
-		outputTokens: usage.output,
-		...usage.cacheRead > 0 ? { cacheReadTokens: usage.cacheRead } : {},
-		...usage.cacheWrite > 0 ? { cacheWriteTokens: usage.cacheWrite } : {}
-	};
+function compatProtocols(field) {
+	return Object.entries(COMPAT_GATES).flatMap(([api, gate]) => gate[field] === "offer" ? [api] : []);
 }
-function classifyPiAiError(message) {
-	if (/\b(?:401|403)\b/.test(message)) return "AUTH";
-	if (isQuotaExceededError(message)) return QUOTA_EXCEEDED_CODE;
-	if (/\b429\b|rate.?limit/i.test(message)) return "RATE_LIMIT";
-	if (/\b400\b|invalid.?request/i.test(message)) return "INVALID_REQUEST";
-	if (/\b5\d\d\b/.test(message)) return "SERVER";
-	if (/\btime(?:d)?\s*out\b|timeout/i.test(message)) return "TIMEOUT";
-	if (/stream ended (?:before|without)\b/i.test(message)) return "TRANSPORT";
-	if (/\b(?:network|connection|socket|fetch)\b|\bECONN[A-Z]+\b/i.test(message) || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(message) || /\bterminated\b|premature close/i.test(message)) return "TRANSPORT";
-	return "PI_AI_ERROR";
+/**
+* The compat fields one protocol offers, for a diagnostic that has to show
+* what was available instead of the name that missed.
+* @param api - wire protocol.
+* @returns the offered field names, or an empty list for a protocol taking no compat.
+*/
+function offeredCompatFields(api) {
+	return Object.entries(compatGate(api) ?? {}).flatMap(([field, disposition]) => disposition === "offer" ? [field] : []);
 }
 /**
-* Map a terminal pi-ai event to the harness finish reason.
-* @param message - the assistant message carried by the `done` or `error` event.
-* @param contextWindow - resolved catalog capacity for usage-based overflow detection.
-* @returns the mapped harness reason. Recognized error text, `stop` usage above
-*   `contextWindow`, and zero-output `length` usage that fills the window map
-*   to `CONTEXT_WINDOW_EXCEEDED`; a `stop` with no content blocks maps to an
-*   `EMPTY_RESPONSE` error.
+* Every offered field name, deduplicated, for the one diagnostic that cannot
+* narrow by protocol: the vocabulary check runs before any protocol resolves,
+* which is what lets it refuse a misspelling on a route whose models would
+* never have reached the protocol that declares the intended field.
+* @returns the offered field names across every protocol, in gate order.
 */
-function mapStopReason(message, contextWindow) {
-	const piAiOverflow = isContextOverflow(message, contextWindow);
-	const harnessOverflow = message.stopReason === "error" && message.errorMessage !== void 0 && isContextWindowExceededError(message.errorMessage);
-	if (piAiOverflow || harnessOverflow) return {
-		kind: "error",
-		failure: {
-			message: message.errorMessage ?? `pi-ai detected context overflow for model "${message.model}"`,
-			code: CONTEXT_WINDOW_EXCEEDED_CODE
-		}
-	};
-	switch (message.stopReason) {
-		case "stop":
-			if (message.content.length === 0) return {
-				kind: "error",
-				failure: {
-					message: `model "${message.model}" returned a completed response with no content`,
-					code: EMPTY_RESPONSE_CODE
-				}
-			};
-			return { kind: "stop" };
-		case "length": return { kind: "max-tokens" };
-		case "toolUse": return { kind: "tool-calls" };
-		case "aborted": return {
-			kind: "aborted",
-			failure: {
-				message: message.errorMessage ?? "pi-ai stream aborted",
-				code: "ABORTED"
-			}
-		};
-		case "error": {
-			const text = message.errorMessage ?? "pi-ai stream error";
-			return {
-				kind: "error",
-				failure: {
-					message: text,
-					code: classifyPiAiError(text)
-				}
-			};
-		}
-	}
+function allOfferedCompatFields() {
+	const fields = /* @__PURE__ */ new Set();
+	for (const api of Object.keys(COMPAT_GATES)) for (const field of offeredCompatFields(api)) fields.add(field);
+	return [...fields];
 }
 /**
-* Translate the pi-ai event stream into StreamChunks. pi-ai never throws
-* mid-stream — failures arrive as `error` events, which become error/aborted
-* `finish` chunks (the harness protocol's other error-delivery style).
-* @param events - one assistant turn's pi-ai event stream.
-* @param contextWindow - resolved catalog capacity for usage-based overflow detection.
-* @returns the harness chunks, ending with `usage` then `finish`; throws
-*   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
+* Reject a compat key no protocol offers. Runs before any protocol is
+* resolved, so a withheld field or a misspelling fails even on a route whose
+* models never reach the protocol that would have taken it — the alternative
+* being the silent drop that let an unreadable switch look applied.
+* @param provider - provider route key, for diagnostics.
+* @param site - the configuration site, for diagnostics.
+* @param compat - the configured switches, when any.
+* @throws Error naming the offending key.
 */
-async function* toStreamChunks(events, contextWindow) {
-	const toolIds = /* @__PURE__ */ new Map();
-	for await (const event of events) switch (event.type) {
-		case "start": break;
-		case "text_start":
-			yield {
-				type: "block-start",
-				index: event.contentIndex,
-				blockType: "text"
-			};
-			break;
-		case "text_delta":
-			yield {
-				type: "text-delta",
-				index: event.contentIndex,
-				text: event.delta
-			};
-			break;
-		case "text_end":
-			yield {
-				type: "block-end",
-				index: event.contentIndex,
-				block: {
-					type: "text",
-					text: event.content
-				}
-			};
-			break;
-		case "thinking_start":
-			yield {
-				type: "block-start",
-				index: event.contentIndex,
-				blockType: "reasoning"
-			};
-			break;
-		case "thinking_delta":
-			yield {
-				type: "reasoning-delta",
-				index: event.contentIndex,
-				text: event.delta
-			};
-			break;
-		case "thinking_end":
-			yield {
-				type: "block-end",
-				index: event.contentIndex,
-				block: {
-					type: "reasoning",
-					text: event.content
-				}
-			};
-			break;
-		case "toolcall_start": {
-			const partial = event.partial.content[event.contentIndex];
-			const id = partial?.type === "toolCall" ? partial.id : "";
-			const name = partial?.type === "toolCall" ? partial.name : "";
-			toolIds.set(event.contentIndex, {
-				id,
-				name
-			});
-			yield {
-				type: "block-start",
-				index: event.contentIndex,
-				blockType: "tool-call"
-			};
-			break;
-		}
-		case "toolcall_delta": {
-			const known = toolIds.get(event.contentIndex);
-			yield {
-				type: "tool-call-delta",
-				index: event.contentIndex,
-				id: CallId(known?.id ?? ""),
-				...known?.name !== void 0 && known.name.length > 0 ? { name: known.name } : {},
-				argumentsDelta: event.delta
-			};
-			break;
+function assertOfferedCompatFields(provider, site, compat) {
+	for (const [field, value] of Object.entries(compat ?? {})) {
+		if (compatProtocols(field).length === 0) {
+			if (Object.values(COMPAT_GATES).some((gate) => gate[field] !== void 0)) invalid(provider, `${site} sets compat "${field}", which is not configurable here: pi-ai's installed catalog sets it for the vendors that need it, so name that provider as the route instead`);
+			invalid(provider, `${site} sets compat "${field}", which no wire protocol declares; the configurable switches are ${allOfferedCompatFields().join(", ")}`);
 		}
-		case "toolcall_end":
-			yield {
-				type: "block-end",
-				index: event.contentIndex,
-				block: {
-					type: "tool-call",
-					id: CallId(event.toolCall.id),
-					name: event.toolCall.name,
-					arguments: JSON.stringify(event.toolCall.arguments)
-				}
-			};
-			break;
-		case "done":
-			yield {
-				type: "usage",
-				usage: mapUsage(event.message.usage)
-			};
-			yield {
-				type: "finish",
-				reason: mapStopReason(event.message, contextWindow),
-				replayState: toPiReplayState(event.message)
-			};
-			return;
-		case "error":
-			yield {
-				type: "usage",
-				usage: mapUsage(event.error.usage)
-			};
-			yield {
-				type: "finish",
-				reason: mapStopReason(event.error, contextWindow)
-			};
-			return;
+		if (value == null) invalid(provider, `${site} sets compat "${field}" with no value; give it one, or remove the key to leave the field to the next layer — the installed catalog entry, then pi-ai's own detection`);
 	}
-	throw new LlmError("pi-ai event stream ended without done/error", "STREAM_CLOSED");
 }
-//#endregion
-//#region lib/types/adapter.js
+/** Report a route the deployment cannot serve, naming the settings key at fault. */
+function invalid(provider, detail) {
+	throw new Error(`llm-pi-ai: provider "${provider}" ${detail}`);
+}
 /**
-* Generic pi-ai-backed implementation of the Harness LLM seam.
-*
-* Each resolution produces one **immutable** snapshot — the profiles plus a
-* `Models` collection holding the `Provider` each route built — and an
-* operation captures a whole snapshot before its first `await`. A
-* configuration change builds a *new* collection rather than mutating the one
-* in use, because `Models.streamSimple()` is lazy: it resolves the provider
-* when the stream is first consumed, which is after the credential await, so a
-* mutated collection would let a request that started under one configuration
-* finish under another — or fail with a provider that no longer exists. This is
-* what makes the seam's per-step call freeze (`llm.prepareCall()`) hold all the
-* way down: switching models mid-reply takes effect on the next step, never
-* inside the one in flight.
+* The one wire protocol a catalog route's shipped models agree on. This is what
+* lets a deployment add a model the installed catalog has not caught up with —
+* a provider's newest release — without restating the protocol its siblings
+* already use. A route whose shipped models disagree (an OpenAI-style catalog
+* spanning Responses and Chat Completions) has no such answer, so a model it
+* does not describe must name its protocol at the route.
+*/
+function sharedCatalogApi(defaults) {
+	const apis = /* @__PURE__ */ new Set();
+	for (const model of defaults.values()) apis.add(model.api);
+	return apis.size === 1 ? [...apis][0] : void 0;
+}
+/**
+* Resolve one model's reasoning capability from its declared efforts.
 *
-* Credentials stay outside that collection. The harness resolves a route's key
-* through its own seam and passes it as the request's `apiKey` option, which
-* pi-ai treats as the highest-priority auth override — so `Models` never holds
-* a credential store and the harness keeps its fail-loud reference semantics.
+* A declared dict translates to pi-ai's `thinkingLevelMap` with every level
+* decided explicitly: declared levels carry their wire spelling, undeclared
+* levels are pinned to `null` (unsupported). Pinning matters because pi-ai's
+* own defaulting is asymmetric — an absent key means "supported" for the five
+* base levels but "unsupported" for `xhigh`/`max` — and a profile author
+* should not need to know that. A declared `off` with no value is the one
+* exception: it stays absent from the map, which pi-ai reads as "supported,
+* send nothing" — the correct dispatch where not thinking is the parameter's
+* absence — while `off` with a value sends that value.
+* @param provider - provider route key, for diagnostics.
+* @param entry - the configured model entry.
+* @param base - the installed catalog entry of the same id, when one exists.
+* @returns the reasoning fields the materialized model carries.
+*/
+function resolveModelReasoning(provider, entry, base) {
+	const efforts = entry.reasoningEfforts;
+	if (efforts === void 0) return { reasoning: base?.reasoning ?? false };
+	if (efforts === false) return { reasoning: false };
+	if (efforts === null || Object.keys(efforts).length === 0) invalid(provider, `model "${entry.id}" has an empty reasoningEfforts; declare the offered levels, set false for a non-reasoning model, or omit the field to keep the installed catalog's capability`);
+	const declared = THINKING_LEVELS.flatMap((level) => {
+		const wire = efforts[level];
+		return wire === void 0 ? [] : [[level, wire]];
+	});
+	for (const [level, wire] of declared) if (wire === null) {
+		if (level !== "off") invalid(provider, `model "${entry.id}" reasoningEfforts.${level} needs the wire value dispatch should send; only "off" may leave it empty`);
+	} else if (wire.length === 0) invalid(provider, `model "${entry.id}" reasoningEfforts.${level} must not be an empty string`);
+	if (!declared.some(([level]) => level !== "off")) invalid(provider, `model "${entry.id}" reasoningEfforts offers no level beyond "off"; declare a thinking level, or set reasoningEfforts to false for a non-reasoning model`);
+	const map = {};
+	for (const level of THINKING_LEVELS) {
+		const wire = efforts[level];
+		if (wire === void 0) map[level] = null;
+		else if (wire !== null) map[level] = wire;
+	}
+	return {
+		reasoning: true,
+		thinkingLevelMap: map
+	};
+}
+/**
+* Resolve one model's compat block from the profile's switches.
 *
-* @module nomix-llm-pi-ai/adapter
+* A model switch wins over the route switch field by field; whatever neither
+* sets keeps the installed entry's value, and a field no layer decides falls
+* through to pi-ai's own detection. A model-level switch its protocol does not
+* take fails resolution — about one named model it can only be a mistake —
+* while a route-level one skips past such models, since a route default must
+* stay settable on a route whose models do not all speak one protocol. Every
+* field reaching here is offered by some protocol; {@link
+* assertOfferedCompatFields} has already refused the rest.
+* @param provider - provider route key, for diagnostics.
+* @param entry - the configured model entry.
+* @param route - the route-level switches, when any.
+* @param base - the installed catalog entry of the same id, when one exists.
+* @param api - the model's resolved wire protocol.
+* @returns a `compat` field to spread into the model, or nothing.
 */
-var __addDisposableResource = function(env, value, async) {
-	if (value !== null && value !== void 0) {
-		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-		var dispose, inner;
-		if (async) {
-			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-			dispose = value[Symbol.asyncDispose];
-		}
-		if (dispose === void 0) {
-			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-			dispose = value[Symbol.dispose];
-			if (async) inner = dispose;
+function resolveModelCompat(provider, entry, route, base, api) {
+	const gate = compatGate(api);
+	const configured = {};
+	for (const [field, value] of configuredCompatEntries(route)) {
+		if (gate?.[field] !== "offer") continue;
+		configured[field] = value;
+	}
+	for (const [field, value] of configuredCompatEntries(entry.compat)) {
+		if (gate?.[field] !== "offer") {
+			const offered = offeredCompatFields(api);
+			invalid(provider, `model "${entry.id}" sets compat "${field}", but its api is "${api}", which does not take it; that switch exists on ${compatProtocols(field).join(", ")}, and "${api}" offers ${offered.length === 0 ? "no configurable compat" : offered.join(", ")}`);
 		}
-		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-		if (inner) dispose = function() {
-			try {
-				inner.call(this);
-			} catch (e) {
-				return Promise.reject(e);
-			}
+		configured[field] = value;
+	}
+	if (Object.keys(configured).length === 0) return {};
+	return { compat: {
+		...base?.api === api ? base.compat : void 0,
+		...configured
+	} };
+}
+/**
+* Materialize one route's catalog by merging the installed catalog defaults
+* under the configured entries. A route with no configured `models` serves the
+* installed catalog unchanged, which is what keeps an existing
+* `providers: { deepseek: { apiKeyEnv: … } }` profile working untouched.
+* @param request - the route-level catalog facts.
+* @returns the materialized models and the explicitly configured request caps.
+*/
+function resolveRouteModels(request) {
+	const { provider } = request;
+	const defaults = catalogModels(provider);
+	const providerBaseUrl = catalogProvider(provider)?.baseUrl;
+	const configured = request.models ?? [];
+	const overrides = request.modelOverrides ?? {};
+	for (const [id, override] of Object.entries(overrides)) {
+		if (id.length === 0) invalid(provider, "has a modelOverrides entry with an empty model id");
+		if (defaults.size === 0) invalid(provider, `sets modelOverrides for "${id}", but the installed catalog does not describe this route; a declared route spells every model out in its models list`);
+		if (configured.length > 0) invalid(provider, `sets modelOverrides for "${id}" beside a models list; models already replaces the served catalog, so declare the fields on its entries`);
+		if (!defaults.has(id)) invalid(provider, `modelOverrides names "${id}", which the installed catalog does not describe`);
+		if ("id" in override) invalid(provider, `modelOverrides entry "${id}" sets "id", which is the dict key`);
+	}
+	const entries = configured.length > 0 ? configured : [...defaults.values()].map((model) => ({
+		id: model.id,
+		...overrides[model.id]
+	}));
+	if (entries.length === 0) invalid(provider, "resolves no models; the installed catalog does not describe this route, so its models must be listed in configuration");
+	const routeApi = sharedCatalogApi(defaults);
+	assertOfferedCompatFields(provider, "route", request.compat);
+	for (const entry of entries) assertOfferedCompatFields(provider, `model "${entry.id}"`, entry.compat);
+	const seen = /* @__PURE__ */ new Set();
+	const configuredMaxTokens = /* @__PURE__ */ new Map();
+	const models = entries.map((entry) => {
+		if (entry.id.length === 0) invalid(provider, "has a model with an empty id");
+		if (seen.has(entry.id)) invalid(provider, `lists model "${entry.id}" more than once`);
+		seen.add(entry.id);
+		const base = defaults.get(entry.id);
+		const api = request.api ?? base?.api ?? routeApi;
+		if (api === void 0) invalid(provider, `model "${entry.id}" needs an api; the installed catalog does not describe it, so set the route's api to the wire protocol its endpoint speaks`);
+		const baseUrl = request.baseURL ?? base?.baseUrl ?? providerBaseUrl;
+		if (baseUrl === void 0) invalid(provider, `model "${entry.id}" needs a baseURL; the installed catalog does not describe this route`);
+		const contextWindow = entry.contextWindow ?? base?.contextWindow ?? request.defaultContextWindow;
+		if (!Number.isInteger(contextWindow) || contextWindow <= 0) invalid(provider, `model "${entry.id}" contextWindow must be a positive integer`);
+		const maxTokens = entry.maxTokens ?? base?.maxTokens ?? request.defaultMaxTokens;
+		if (!Number.isInteger(maxTokens) || maxTokens <= 0) invalid(provider, `model "${entry.id}" maxTokens must be a positive integer`);
+		if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
+		return {
+			...base,
+			id: entry.id,
+			name: entry.name ?? base?.name ?? entry.id,
+			api,
+			provider,
+			baseUrl,
+			input: declaredInput(entry.input) ?? base?.input ?? [...request.defaultInput],
+			cost: base?.cost ?? NO_COST,
+			contextWindow,
+			maxTokens,
+			...resolveModelReasoning(provider, entry, base),
+			...resolveModelCompat(provider, entry, request.compat, base, api)
 		};
-		env.stack.push({
-			value,
-			dispose,
-			async
-		});
-	} else if (async) env.stack.push({ async: true });
-	return value;
-};
-var __disposeResources = (function(SuppressedError) {
-	return function(env) {
-		function fail(e) {
-			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-			env.hasError = true;
-		}
-		var r, s = 0;
-		function next() {
-			while (r = env.stack.pop()) try {
-				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-				if (r.dispose) {
-					var result = r.dispose.call(r.value);
-					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
-						fail(e);
-						return next();
-					});
-				} else s |= 1;
-			} catch (e) {
-				fail(e);
-			}
-			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-			if (env.hasError) throw env.error;
-		}
-		return next();
-	};
-})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
-	var e = new Error(message);
-	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-/** Copy profile stream knobs into pi-ai's common option vocabulary. */
-function profileOptions(profile, reasoning, apiKey) {
-	const enabledReasoning = reasoning === "off" ? void 0 : reasoning;
+	});
+	for (const [field] of configuredCompatEntries(request.compat)) {
+		const takers = compatProtocols(field);
+		if (models.some((model) => takers.includes(model.api))) continue;
+		invalid(provider, `sets compat "${field}", but no model on the route speaks a protocol that takes it; it exists on ${takers.join(", ")}`);
+	}
 	return {
-		...apiKey === void 0 ? {} : { apiKey },
-		...enabledReasoning === void 0 ? {} : { reasoning: enabledReasoning },
-		...profile.thinkingBudgets === void 0 ? {} : { thinkingBudgets: profile.thinkingBudgets },
-		...profile.cacheRetention === void 0 ? {} : { cacheRetention: profile.cacheRetention },
-		...profile.transport === void 0 ? {} : { transport: profile.transport },
-		...profile.timeoutMs === void 0 ? {} : { timeoutMs: profile.timeoutMs },
-		...profile.websocketConnectTimeoutMs === void 0 ? {} : { websocketConnectTimeoutMs: profile.websocketConnectTimeoutMs },
-		maxRetries: 0
+		models,
+		configuredMaxTokens
 	};
 }
+//#endregion
+//#region lib/types/provider.js
 /**
-* The profile default this exact model can actually take, for DESCRIBING it.
-* A configured level the model does not support yields none rather than
-* throwing: `resolveModel` builds the model catalog, and a catalog that fails
-* takes its whole provider out of every picker — so one mis-set profile field
-* would hide every model on the route, including the ones that support the
-* level. The request path still refuses, which is where a bad configuration
-* belongs: describing what a model can do must not fail because a deployment
-* asked it for something it cannot.
-* @param model - the resolved model descriptor.
-* @param effort - the profile's configured level, if any.
-* @returns the level when this model supports it, otherwise undefined.
+* Construction of the pi-ai `Provider` that one configured route registers into
+* the adapter's `Models` collection.
+*
+* Two constructions, one decision: a route the installed catalog ships, whose
+* profile does not override the wire protocol, **reuses that catalog provider**
+* with its models replaced — the catalog provider owns API implementations this
+* package cannot reconstruct (Bedrock loads its Smithy module through a
+* separate entry point), so rebuilding it from parts would silently narrow
+* which providers work. Every other route — one pi-ai has never heard of, or a
+* catalog route pointed at a different protocol — is built by `createProvider`
+* over the protocol table below.
+*
+* Credentials never reach this module's storage: the harness resolves a route's
+* key through `ctx.credentials` before the request enters pi-ai and hands it
+* over as a stream option, which `Models` presents to `resolve()` as the
+* credential key.
+*
+* @module nomix-llm-pi-ai/provider
 */
-function describableReasoningLevel(model, effort) {
-	if (effort === void 0) return void 0;
-	return getSupportedThinkingLevels(model).some((level) => level === effort) ? effort : void 0;
-}
-/** Validate an explicit Harness/profile effort without invoking pi-ai's clamp. */
-function resolveReasoningLevel(model, effort) {
-	if (effort === void 0) return void 0;
-	if (getSupportedThinkingLevels(model).some((level) => level === effort)) return effort;
-	throw new LlmError(`pi-ai provider "${model.provider}" model "${model.id}" does not support reasoning effort "${effort}"`, "UNSUPPORTED_REASONING_EFFORT");
-}
 /**
-* Selectable reasoning efforts for one model, or nothing at all.
+* Wire protocols a configured route may name, mapped to pi-ai's lazily loaded
+* implementations. Each entry is the factory that pi-ai's matching provider
+* factory uses, so a hand-declared route reaches exactly the implementation a
+* catalog route would.
 *
-* A model that carries no reasoning metadata — every hand-declared one, and
-* every catalog model pi-ai marks as non-reasoning — is reported by pi-ai as
-* supporting the single level `off`. Passing that through would offer a control
-* that cannot do what it says: `off` is translated to *omitting* the reasoning
-* option, which for such a model is byte-for-byte the same request as naming no
-* effort — so a provider whose own default is to think would keep thinking with
-* `off` selected. Omitting `reasoning` entirely is the seam's way of saying the
-* capability is unavailable, which leaves the surface offering only the
-* provider's default.
-* @param model - the resolved model descriptor.
-* @param defaultLevel - the profile's configured effort, already validated.
-* @returns the `reasoning` field, or an empty object when none can be offered.
+* The table is deliberately narrow: the protocols a hand-declared route
+* actually reaches for today, each completely describable with a key, an
+* endpoint, and headers. Bedrock signs with SigV4 over AWS credentials and a
+* region, Vertex needs a project, a location, and application-default
+* credentials, Azure needs provider environment plus an api-version, and Codex
+* authenticates through OAuth — none of which this configuration shape can
+* express, so offering them would hand back a provider that cannot
+* authenticate. The remainder are absent for want of a consumer rather than a
+* blocker: each is one line here once a deployment needs it. Catalog routes
+* still reach every protocol through their own provider; only an explicit
+* override is refused.
 */
-function reasoningInfo(model, defaultLevel) {
-	if (!model.reasoning) return {};
-	return { reasoning: {
-		efforts: getSupportedThinkingLevels(model).map((level) => ({
-			id: ReasoningEffortId(level),
-			name: `${level.charAt(0).toUpperCase()}${level.slice(1)}`
-		})),
-		...defaultLevel === void 0 ? {} : { defaultEffort: ReasoningEffortId(defaultLevel) }
-	} };
+const PROTOCOLS = {
+	"openai-completions": openAICompletionsApi,
+	"openai-responses": openAIResponsesApi,
+	"anthropic-messages": anthropicMessagesApi
+};
+/**
+* Every wire protocol a configured route may name, most-reached first. The
+* order is the table's and therefore stable; a configuration surface offering
+* a choice presents the first as its default, which is why the protocol a
+* hand-declared gateway most often speaks — and the one endpoint interrogation
+* can read — leads.
+* @returns the supported protocol identifiers.
+*/
+function supportedProtocols() {
+	return Object.keys(PROTOCOLS);
 }
-/** Merge deployment headers while removing case-insensitive attribution collisions. */
-function requestHeaders(headers) {
-	const attribution = attributionHeaders();
-	const reserved = new Set(Object.keys(attribution).map((name) => name.toLowerCase()));
+/**
+* Api-key auth for a route the harness authenticates itself. `Models` calls
+* this after the adapter has already resolved the route's credential, so a
+* missing key here is not this layer's failure: a named-but-unresolvable
+* reference has already failed the request with `MISSING_CREDENTIAL`, and a
+* route naming no credential at all is deliberately unauthenticated. Reporting
+* it as configured hands the decision to the protocol, which is where the
+* requirement actually lives — pi-ai's OpenAI-compatible implementation, for
+* one, still insists on a key or an `Authorization` header of its own.
+* @param name - display name used as the resolution's status label.
+* @returns the api-key auth for a harness-authenticated route.
+*/
+function harnessApiKeyAuth(name) {
 	return {
-		...Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => !reserved.has(name.toLowerCase()))),
-		...attribution
+		name,
+		resolve: ({ credential }) => Promise.resolve({
+			auth: credential?.key === void 0 ? {} : { apiKey: credential.key },
+			source: name
+		})
 	};
 }
 /**
-* pi-ai-backed multi-provider adapter. Each operation reads the current
-* profiles, so a configuration change reaches the next request without a
-* restart; model descriptors come from the collection those profiles built.
-*/
-var PiAiAdapter = class extends LlmAdapter {
-	config;
-	snapshot;
-	constructor(config) {
-		super();
-		this.config = config;
-	}
-	/**
-	* The snapshot for the current profiles. Resolution memoizes its result, so
-	* an unchanged configuration is recognized by identity; a changed one gets a
-	* brand-new collection, leaving any snapshot an operation already captured
-	* untouched for as long as that operation holds it.
-	*/
-	current() {
-		const profiles = this.config.profiles();
-		if (this.snapshot?.profiles === profiles) return this.snapshot;
-		const models = createModels();
-		for (const profile of profiles.values()) models.setProvider(profile.piProvider);
-		this.snapshot = {
-			profiles,
-			models
-		};
-		return this.snapshot;
-	}
-	/** The profile for one route within one snapshot, or the not-owned failure. */
-	profileOf(snapshot, provider) {
-		const profile = snapshot.profiles.get(provider);
-		if (profile === void 0) throw new LlmError(`pi-ai adapter does not own provider "${provider}"`, "NO_ADAPTER");
-		return profile;
-	}
-	/** The configured descriptor for one exact route/model pair within one snapshot. */
-	modelOf(snapshot, provider, model) {
-		this.profileOf(snapshot, provider);
-		const resolved = snapshot.models.getModel(provider, model);
-		if (resolved === void 0) throw new LlmError(`pi-ai provider "${provider}" has no configured model "${model}"`, "UNKNOWN_MODEL");
-		return resolved;
-	}
-	providerInfo(provider) {
-		return {
-			id: provider,
-			name: this.current().profiles.get(provider)?.displayName ?? provider
-		};
-	}
-	providerRetryPolicy(provider) {
-		return this.current().profiles.get(provider)?.retryPolicy;
-	}
-	listModels(provider) {
-		return Promise.resolve().then(() => {
-			const snapshot = this.current();
-			this.profileOf(snapshot, provider);
-			return snapshot.models.getModels(provider).map((model) => ({
-				provider,
-				id: model.id,
-				name: model.name,
-				inputModalities: [...model.input]
-			}));
-		});
-	}
-	resolveModel(provider, model, _signal) {
-		return Promise.resolve().then(() => {
-			const snapshot = this.current();
-			const profile = this.profileOf(snapshot, provider);
-			const resolvedModel = this.modelOf(snapshot, provider, model);
-			const defaultLevel = describableReasoningLevel(resolvedModel, profile.reasoning);
-			const configuredMaxTokens = profile.configuredMaxTokens.get(model);
-			return {
-				provider,
-				id: model,
-				name: resolvedModel.name,
-				inputModalities: [...resolvedModel.input],
-				context: { contextWindow: resolvedModel.contextWindow },
-				...configuredMaxTokens === void 0 ? {} : { defaultMaxTokens: configuredMaxTokens },
-				...reasoningInfo(resolvedModel, defaultLevel)
-			};
-		});
-	}
-	async *stream(options) {
-		const env_1 = {
-			stack: [],
-			error: void 0,
-			hasError: false
-		};
-		try {
-			if (options.stop !== void 0) throw new LlmError("llm-pi-ai does not support GenerateOptions.stop", "UNSUPPORTED_OPTION");
-			const snapshot = this.current();
-			const profile = this.profileOf(snapshot, options.provider);
-			const model = this.modelOf(snapshot, options.provider, options.model);
-			const reasoning = resolveReasoningLevel(model, options.reasoningEffort ?? profile.reasoning);
-			const apiKey = await this.config.resolveApiKey(options.provider, profile);
-			const consumer = new AbortController();
-			const upstream = options.signal === void 0 ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]);
-			const streamIdleTimeoutMs = profile.streamIdleTimeoutMs;
-			const watchdog = __addDisposableResource(env_1, idleWatchdog(upstream, streamIdleTimeoutMs, "LLM_STREAM_IDLE_TIMEOUT"), false);
-			try {
-				const containsImage = options.messages.some((message) => contentHasImage(message.content));
-				if (containsImage && !model.input.includes("image")) throw new LlmError(`pi-ai model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
-				const attachments = containsImage ? this.config.resolveAttachments?.() : void 0;
-				if (containsImage && attachments === void 0) throw new LlmError("pi-ai image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
-				const onReplayDegrade = (reason) => {
-					this.config.onReplayDegrade?.({
-						provider: options.provider,
-						model: options.model,
-						reason
-					});
-				};
-				const context = attachments === void 0 ? toPiContext(options, void 0, onReplayDegrade) : await toPiContext(options, attachments, onReplayDegrade);
-				const iterator = toStreamChunks(snapshot.models.streamSimple(model, context, {
-					...profileOptions(profile, reasoning, apiKey),
-					...options.temperature === void 0 ? {} : { temperature: options.temperature },
-					...options.maxTokens === void 0 ? {} : { maxTokens: options.maxTokens },
-					...options.sessionId === void 0 ? {} : { sessionId: String(options.sessionId) },
-					signal: watchdog.signal,
-					headers: requestHeaders(profile.headers)
-				}), model.contextWindow)[Symbol.asyncIterator]();
-				let exhausted = false;
-				try {
-					while (true) {
-						const result = await watchdog.next(iterator);
-						const timeout = timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT");
-						if (timeout !== void 0) throw timeout;
-						if (result.done) {
-							exhausted = true;
-							return;
-						}
-						yield result.value;
-					}
-				} finally {
-					if (!exhausted) {
-						consumer.abort("pi-ai stream consumer stopped");
-						try {
-							await iterator.return(void 0);
-						} catch (_abortedSdkTeardown) {}
-					}
-				}
-			} catch (error) {
-				if (timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT") !== void 0) throw new LlmError(`pi-ai stream idle timeout after ${streamIdleTimeoutMs}ms`, "TIMEOUT", { cause: error });
-				if (options.signal?.aborted) throw new LlmError("pi-ai request aborted by caller", "ABORTED", { cause: error });
-				throw error;
-			} finally {
-				consumer.abort("pi-ai stream consumer stopped");
-			}
-		} catch (e_1) {
-			env_1.error = e_1;
-			env_1.hasError = true;
-		} finally {
-			__disposeResources(env_1);
-		}
-	}
-};
-//#endregion
-//#region lib/types/catalog.js
-/**
-* Materialization of one provider route's model catalog. The installed pi-ai
-* catalog supplies defaults keyed by model id, and a profile's own model
-* entries override them field by field, so a route naming a catalog provider
-* stays configuration-free while a route pi-ai has never heard of is fully
-* describable from `settings.yaml`.
+* The auth one route resolves its credential through.
 *
-* Every pi-ai `Model` field the harness cannot default is required here rather
-* than at request time: an unserviceable route fails while its configuration is
-* being resolved, which is the earliest point that can name the offending key.
+* A catalog route keeps the installed provider's own auth, which is what
+* preserves provider-native ambient discovery for a profile naming no
+* credential. That holds even when the profile repoints the protocol: which
+* environment a provider reads is a property of the provider, not of the wire
+* format its models speak.
 *
-* @module nomix-llm-pi-ai/catalog
+* The single addition covers a catalog provider that offers no api-key method
+* at all. pi-ai resolves a request's `apiKey` override only when the provider
+* declares one (`resolveProviderAuth` checks `provider.auth.apiKey` before
+* honouring the override), so an OAuth-only provider — `openai-codex` is the
+* one the installed catalog ships — would refuse a profile's explicit key with
+* `Provider is not configured` before any request went out. Adding the harness
+* method beside the provider's own restores that route. A keyless profile adds
+* nothing and still reports the honest refusal, because this adapter resolves
+* credentials through its own seam and holds no OAuth store to fall back on.
+* @param spec - the resolved route facts.
+* @param catalog - the installed catalog provider, when pi-ai ships one.
+* @returns the auth to construct this route's provider with.
 */
+function routeAuth(spec, catalog) {
+	if (catalog === void 0) return { apiKey: harnessApiKeyAuth(spec.displayName) };
+	if (catalog.auth.apiKey !== void 0 || !spec.namesCredential) return catalog.auth;
+	return {
+		...catalog.auth,
+		apiKey: harnessApiKeyAuth(spec.displayName)
+	};
+}
 /**
-* Pricing for a model the installed catalog does not describe. The harness
-* never reads pi-ai's cost metadata — `replay.ts` zeroes it and no consumer
-* reports spend — so this is the absence of a fact, not a configurable rate.
+* Reuse an installed catalog provider with this route's models and identity.
+* Model dispatch stays with the catalog provider, so its API implementations,
+* compatibility quirks, and ambient credential discovery are preserved exactly.
+* Catalog-owned dynamic refresh is dropped: this route's catalog is the
+* settings document, and a background refresh would contradict it.
 */
-const NO_COST = {
-	input: 0,
-	output: 0,
-	cacheRead: 0,
-	cacheWrite: 0
-};
-/** Every request modality a profile may declare. */
-const MODALITIES = Object.keys({
-	text: true,
-	image: true
-});
+function reuseCatalogProvider(base, spec) {
+	const baseUrl = spec.baseURL ?? base.baseUrl;
+	return {
+		id: spec.provider,
+		name: spec.displayName,
+		...baseUrl === void 0 ? {} : { baseUrl },
+		auth: routeAuth(spec, base),
+		getModels: () => spec.models,
+		stream: (model, context, options) => base.stream(model, context, options),
+		streamSimple: (model, context, options) => base.streamSimple(model, context, options)
+	};
+}
 /**
-* One entry's modality list, or `undefined` when it states no answer. Absent
-* and empty mean the same thing — `[]` describes a model that accepts nothing
-* and could serve no request — which is what makes an entry naming a catalog
-* model without declaring modalities keep the catalog's, since the config
-* schema materializes `[]` for an absent array.
-* @param configured - the list a `models` or `modelOverrides` entry supplied.
-* @returns the declared modalities, or `undefined` to ask the next level.
+* Build the pi-ai provider for one resolved route.
+* @param spec - the resolved route facts.
+* @returns the provider to register in the adapter's `Models` collection.
+* @throws Error when the route names a wire protocol this build cannot serve.
 */
-function declaredInput(configured) {
-	return configured === void 0 || configured.length === 0 ? void 0 : [...configured];
+function buildProvider(spec) {
+	const catalog = catalogProvider(spec.provider);
+	if (catalog !== void 0 && spec.api === void 0) return reuseCatalogProvider(catalog, spec);
+	const factory = spec.api === void 0 ? void 0 : PROTOCOLS[spec.api];
+	if (factory === void 0) throw new Error(`llm-pi-ai: provider "${spec.provider}" names api "${spec.api}", which this build cannot serve; supported protocols are ${supportedProtocols().join(", ")}`);
+	return createProvider({
+		id: spec.provider,
+		name: spec.displayName,
+		...spec.baseURL === void 0 ? {} : { baseUrl: spec.baseURL },
+		auth: routeAuth(spec, catalog),
+		models: spec.models,
+		api: factory()
+	});
 }
-/** Every pi-ai thinking level a profile may declare, in escalation order. */
-const THINKING_LEVELS = Object.keys({
-	off: true,
-	minimal: true,
-	low: true,
-	medium: true,
-	high: true,
-	xhigh: true,
-	max: true
-});
-/** Reasoning-dispatch wire formats a profile may name, most-reached first. */
-const SUPPORTED_THINKING_FORMATS = Object.keys({
-	"openai": true,
-	"deepseek": true,
-	"openrouter": true,
-	"together": true,
-	"zai": true,
-	"qwen": true,
-	"string-thinking": true,
-	"ant-ling": true
-});
-let providerIndex;
+//#endregion
+//#region lib/types/config.js
 /**
-* Installed catalog providers by id, constructed once. Each entry owns the API
-* implementations for its own models, which is why a catalog route reuses this
-* provider instead of being rebuilt from parts.
-* @returns the catalog provider index.
+* Configuration schema and provider-profile validation for the pi-ai adapter.
+* Profiles are a dict keyed by provider route, so the composition base and a
+* user-settings layer merge per provider and the route set is structural.
+*
+* A route key is not required to name an installed pi-ai provider. When it does,
+* that provider's endpoint, protocol, display name, and model catalog are the
+* profile's defaults and the profile overrides them field by field; when it does
+* not, the profile is the whole provider declaration. Resolution therefore ends
+* in a built pi-ai `Provider` per route: everything a request needs is decided
+* once, while the configuration key that made a route unserviceable can still be
+* named in the failure.
+*
+* @module nomix-llm-pi-ai/config
 */
-function catalogProviders() {
-	providerIndex ??= new Map(builtinProviders().map((provider) => [provider.id, provider]));
-	return providerIndex;
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
+/**
+* Default request-level bound on base64-encoded image payload. Every image in
+* history is re-encoded into every request body, so an unbounded conversation
+* eventually exceeds a provider or gateway request-size cap and the session
+* can never complete another request. The 20MiB default admits fifteen 1MiB
+* request versions after base64 expansion and reserves request capacity for
+* system prompts, history, tools, and JSON.
+* Deployments behind stricter gateways lower it per route.
+*/
+const DEFAULT_MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Default total-pixel budget preserves the complete 2048px normalized attachment. */
+const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048;
+/** Default raw encoded-byte cap before inline base64 expansion. */
+const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
+/** Context capacity assumed for a model neither configuration nor the catalog sizes. */
+const DEFAULT_CONTEXT_WINDOW = 262144;
+/** Output capability assumed for a model neither configuration nor the catalog sizes. */
+const DEFAULT_MAX_TOKENS = 32768;
+/**
+* Modalities assumed for a model neither configuration nor the catalog
+* declares. Text is the floor every supported protocol certainly carries, so
+* this is the absence of a declaration rather than a guess at the endpoint:
+* nothing can interrogate a gateway for its modalities, and the two wrong
+* answers do not cost the same. Under-claiming refuses the image before it is
+* attached, naming the model. Over-claiming admits one the provider then
+* rejects mid-turn, after the message is durable, leaving the session
+* repeating a request that cannot succeed.
+*/
+const DEFAULT_INPUT = ["text"];
+const thinkingBudgets = z.object({
+	minimal: z.number(),
+	low: z.number(),
+	medium: z.number(),
+	high: z.number()
+});
+/**
+* One `chat_template_kwargs` value. The `$var` member is pi-ai's placeholder
+* for a value dispatch fills from the request's thinking state, which is what
+* makes a chat-template gateway configurable without restating its template.
+*/
+const chatTemplateKwarg = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.const(null),
+	z.object({
+		$var: z.union(CHAT_TEMPLATE_VARS).required(),
+		omitWhenOff: z.boolean()
+	})
+]);
+const compatProfile = z.object({
+	supportsStore: z.boolean(),
+	supportsDeveloperRole: z.boolean(),
+	supportsReasoningEffort: z.boolean(),
+	supportsUsageInStreaming: z.boolean(),
+	maxTokensField: z.union(MAX_TOKENS_FIELDS),
+	requiresToolResultName: z.boolean(),
+	requiresAssistantAfterToolResult: z.boolean(),
+	requiresThinkingAsText: z.boolean(),
+	requiresReasoningContentOnAssistantMessages: z.boolean(),
+	thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
+	chatTemplateKwargs: z.dict(chatTemplateKwarg),
+	supportsStrictMode: z.boolean(),
+	cacheControlFormat: z.union(CACHE_CONTROL_FORMATS),
+	supportsLongCacheRetention: z.boolean(),
+	supportsEagerToolInputStreaming: z.boolean(),
+	supportsCacheControlOnTools: z.boolean(),
+	supportsTemperature: z.boolean(),
+	forceAdaptiveThinking: z.boolean(),
+	allowEmptySignature: z.boolean(),
+	supportsStrictTools: z.boolean()
+});
+/**
+* Keys are the offered levels, values their wire spellings. A valueless key
+* (`off:`) survives validation because schemastery passes nullable data
+* through before any member schema runs — `z.const(null)` only controls the
+* error for non-null wrong values and what a configuration UI renders.
+* Only resolution decides which levels may leave the value empty, so the
+* diagnostic can name the route and model. The assertion narrows
+* schemastery's `Dict`, which types every literal key as required; dict
+* validation checks only present keys, so the runtime value is a partial record.
+*/
+const reasoningEfforts = z.dict(z.union([z.string(), z.const(null)]), z.union(THINKING_LEVELS));
+/** The fields a `models` entry and a `modelOverrides` value share; only the id's home differs. */
+const modelFields = {
+	name: z.string(),
+	contextWindow: z.number().step(1).min(1),
+	maxTokens: z.number().step(1).min(1),
+	input: z.array(z.union(MODALITIES)),
+	reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
+	compat: compatProfile
+};
+const modelProfile = z.object({
+	id: z.string().required(),
+	...modelFields
+});
+/** A {@link modelProfile} whose id lives in the `modelOverrides` dict key. */
+const modelOverride = z.object(modelFields);
+const profile = z.object({
+	apiKeyEnv: z.string().role("credential-ref"),
+	displayName: z.string(),
+	api: z.union(supportedProtocols()),
+	baseURL: z.string(),
+	models: z.array(modelProfile),
+	modelOverrides: z.dict(modelOverride),
+	compat: compatProfile,
+	defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+	defaultMaxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
+	defaultInput: z.array(z.union(MODALITIES)).default([...DEFAULT_INPUT]),
+	headers: z.dict(z.string()),
+	reasoning: z.union(THINKING_LEVELS),
+	thinkingBudgets,
+	cacheRetention: z.union([
+		"none",
+		"short",
+		"long"
+	]),
+	transport: z.union([
+		"sse",
+		"websocket",
+		"websocket-cached",
+		"auto"
+	]),
+	timeoutMs: z.natural(),
+	websocketConnectTimeoutMs: z.natural(),
+	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+	maxRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_IMAGE_BYTES),
+	requestImagePixelBudget: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET),
+	requestImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_MAX_BYTES),
+	retryPolicy: RetryPolicySchema
+});
+/** Runtime schema for {@link Config}. */
+const Config = z.object({ providers: z.dict(profile).default({}) });
+/**
+* Reject a section this adapter could not serve. Registered as the settings
+* namespace's validator, so an unserviceable profile is refused where it is
+* *written* — `settings.mutate` answers `settings-rejected` with the offending
+* route and model named — instead of being stored and then quietly disabling
+* every route in the namespace. It stays a validator rather than a schema
+* transform because the schema is also the shape a configuration surface
+* renders and the value an absent section resolves to; wrapping it would break
+* both.
+* @param config - the resolved section to check.
+* @throws Error naming the route and model that cannot be served.
+*/
+function assertServiceable(config) {
+	resolveProfiles(config.providers);
+}
+/** Reject removed pre-release profile fields and name their replacements. */
+function rejectRemovedFields(provider, source) {
+	const legacy = source;
+	if ("provider" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets "provider", which moved to the providers dict key`);
+	if ("maxRetries" in legacy || "maxRetryDelayMs" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets maxRetries or maxRetryDelayMs, which were removed; compose agent recovery with nomix-llm-retry`);
+}
+/**
+* Validate profiles and return a detached route-keyed map suitable for
+* per-request reads. This is the one explicit resolve step, so an omitted dict
+* resolves to the empty (dormant) route set here rather than through a hidden
+* fallback, and each route's models and pi-ai provider are materialized once.
+* @param providers - configured provider profiles keyed by route.
+* @returns validated profiles in configuration order.
+*/
+function resolveProfiles(providers) {
+	if (Array.isArray(providers)) throw new Error("llm-pi-ai: providers is now a dict keyed by provider route, not an array of profiles");
+	const entries = Object.entries(providers ?? {});
+	const resolved = /* @__PURE__ */ new Map();
+	for (const [provider, source] of entries) {
+		rejectRemovedFields(provider, source);
+		if (provider.length === 0) throw new Error("llm-pi-ai: provider names must be non-empty");
+		if (source.baseURL !== void 0 && source.baseURL.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty baseURL`);
+		if (source.displayName !== void 0 && source.displayName.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty displayName`);
+		const streamIdleTimeoutMs = source.streamIdleTimeoutMs ?? 3e5;
+		if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`llm-pi-ai: provider "${provider}" streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+		const maxRequestImageBytes = source.maxRequestImageBytes ?? 20971520;
+		if (!Number.isInteger(maxRequestImageBytes) || maxRequestImageBytes <= 0) throw new Error(`llm-pi-ai: provider "${provider}" maxRequestImageBytes must be a positive integer`);
+		const requestImagePixelBudget = source.requestImagePixelBudget ?? 4194304;
+		if (!Number.isSafeInteger(requestImagePixelBudget) || requestImagePixelBudget <= 0) throw new Error(`llm-pi-ai: provider "${provider}" requestImagePixelBudget must be a positive safe integer`);
+		const requestImageMaxBytes = source.requestImageMaxBytes ?? 1048576;
+		if (!Number.isSafeInteger(requestImageMaxBytes) || requestImageMaxBytes <= 0) throw new Error(`llm-pi-ai: provider "${provider}" requestImageMaxBytes must be a positive safe integer`);
+		const defaultInput = [...source.defaultInput ?? DEFAULT_INPUT];
+		if (defaultInput.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" defaultInput must name at least one modality`);
+		const displayName = source.displayName ?? provider;
+		const catalog = resolveRouteModels({
+			provider,
+			...source.api === void 0 ? {} : { api: source.api },
+			...source.baseURL === void 0 ? {} : { baseURL: source.baseURL },
+			...source.models === void 0 ? {} : { models: source.models },
+			...source.modelOverrides === void 0 ? {} : { modelOverrides: source.modelOverrides },
+			...source.compat === void 0 ? {} : { compat: source.compat },
+			defaultInput,
+			defaultContextWindow: source.defaultContextWindow ?? 262144,
+			defaultMaxTokens: source.defaultMaxTokens ?? 32768
+		});
+		const { apiKeyEnv, retryPolicy, models: _models, displayName: _displayName, ...rest } = source;
+		resolved.set(provider, {
+			...rest,
+			provider,
+			displayName,
+			...apiKeyEnv === void 0 ? {} : { apiKeyEnv: credentialRef(apiKeyEnv) },
+			streamIdleTimeoutMs,
+			maxRequestImageBytes,
+			requestImagePixelBudget,
+			requestImageMaxBytes,
+			retryPolicy: resolveRetryPolicy(retryPolicy, `llm-pi-ai: provider "${provider}" retryPolicy`),
+			...rest.headers === void 0 ? {} : { headers: { ...rest.headers } },
+			...rest.thinkingBudgets === void 0 ? {} : { thinkingBudgets: { ...rest.thinkingBudgets } },
+			configuredMaxTokens: catalog.configuredMaxTokens,
+			piProvider: buildProvider({
+				provider,
+				displayName,
+				...source.api === void 0 ? {} : { api: source.api },
+				...source.baseURL === void 0 ? {} : { baseURL: source.baseURL },
+				models: catalog.models,
+				namesCredential: apiKeyEnv !== void 0
+			})
+		});
+	}
+	return resolved;
+}
+//#endregion
+//#region lib/types/context.js
+/**
+* Harness request-history conversion into pi-ai's Context vocabulary.
+*
+* @module nomix-llm-pi-ai/context
+*/
+/** Join the text blocks of a harness message. */
+function flattenText(message) {
+	return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+/** Flatten text recursively inside one tool result. */
+function toolResultText(blocks) {
+	return blocks.map((block) => block.type === "text" ? block.text : block.type === "tool-result" ? toolResultText(block.content) : "").join("");
+}
+/** Reject image roles that pi-ai cannot replay before request-size offloading can replace them. */
+function assertSupportedImageRoles(messages) {
+	for (const message of messages) if (message.role !== "user" && contentHasImage(message.content)) throw new LlmError(`pi-ai cannot represent an image in an in-history ${message.role} message`, "UNSUPPORTED_CONTENT");
+}
+async function userContent(blocks, requestImages) {
+	const content = [];
+	for (const block of blocks) switch (block.type) {
+		case "text":
+			if (block.text.length > 0) content.push({
+				type: "text",
+				text: block.text
+			});
+			break;
+		case "image": {
+			const version = requestImages.get(block.attachment.attachmentId);
+			content.push({
+				type: "text",
+				text: requestImageHandleText(version)
+			});
+			content.push({
+				type: "image",
+				data: Buffer.from(version.data).toString("base64"),
+				mimeType: version.mediaType
+			});
+			break;
+		}
+		case "tool-result":
+			{
+				const nested = await userContent(block.content, requestImages);
+				if (typeof nested === "string") {
+					if (nested.length > 0) content.push({
+						type: "text",
+						text: nested
+					});
+				} else content.push(...nested);
+			}
+			break;
+		default: break;
+	}
+	if (content.every((block) => block.type === "text")) return content.map((block) => block.text).join("");
+	return content;
+}
+function collectImageRefs(blocks, refs) {
+	for (const block of blocks) if (block.type === "image") refs.set(block.attachment.attachmentId, block.attachment);
+	else if (block.type === "tool-result") collectImageRefs(block.content, refs);
+}
+async function prepareRequestImages(messages, attachments, policy, signal) {
+	const refs = /* @__PURE__ */ new Map();
+	for (const message of messages) collectImageRefs(message.content, refs);
+	const orderedRefs = [...refs.values()];
+	const prepared = await Promise.all(orderedRefs.map((ref) => attachments.readImageRequest(ref, policy, signal)));
+	const versions = /* @__PURE__ */ new Map();
+	for (const [index, ref] of orderedRefs.entries()) versions.set(ref.attachmentId, prepared[index]);
+	return versions;
+}
+function toolsOf(options) {
+	return options.tools?.map((tool) => ({
+		name: tool.name,
+		description: tool.description,
+		parameters: tool.parameters
+	}));
+}
+/** Assemble the request-level pi-ai context envelope shared by both conversion paths. */
+function piContext(options, messages) {
+	const tools = toolsOf(options);
+	return {
+		...options.system !== void 0 ? { systemPrompt: options.system } : {},
+		messages,
+		...tools !== void 0 && tools.length > 0 ? { tools } : {}
+	};
+}
+function textOnlyContext(options, onReplayDegrade) {
+	const toolNames = /* @__PURE__ */ new Map();
+	const messages = [];
+	for (const message of options.messages) {
+		if (contentHasImage(message.content)) throw new LlmError("pi-ai image conversion requires the durable attachment service", "UNSUPPORTED_CONTENT");
+		if (message.role === "system") {
+			messages.push({
+				role: "user",
+				content: flattenText(message),
+				timestamp: 0
+			});
+			continue;
+		}
+		if (message.role === "assistant") {
+			const assistant = toPiAssistant(message, onReplayDegrade);
+			for (const block of assistant.content) if (block.type === "toolCall") toolNames.set(CallId(block.id), block.name);
+			messages.push(assistant);
+			continue;
+		}
+		const text = flattenText(message);
+		const results = message.content.filter((block) => block.type === "tool-result");
+		if (text.length > 0 || results.length === 0) messages.push({
+			role: "user",
+			content: text,
+			timestamp: 0
+		});
+		for (const result of results) messages.push({
+			role: "toolResult",
+			toolCallId: result.toolCallId,
+			toolName: toolNames.get(result.toolCallId) ?? "unknown",
+			content: [{
+				type: "text",
+				text: toolResultText(result.content) || "(no output)"
+			}],
+			isError: result.isError ?? false,
+			timestamp: 0
+		});
+	}
+	return piContext(options, messages);
 }
-/**
-* The installed catalog provider for one route, when pi-ai ships one.
-* @param provider - provider route key.
-* @returns the catalog provider, or `undefined` for a route pi-ai does not ship.
-*/
-function catalogProvider(provider) {
-	return catalogProviders().get(provider);
+function toPiContext(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy) {
+	return attachments === void 0 ? textOnlyContext(options, onReplayDegrade) : toPiContextWithImages(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy);
 }
-/**
-* Every provider route the installed pi-ai catalog ships.
-* @returns the catalog provider ids.
-*/
-function catalogProviderIds() {
-	return getBuiltinProviders();
+async function toPiContextWithImages(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy = {
+	maxPixels: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+	maxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES
+}) {
+	assertSupportedImageRoles(options.messages);
+	const requestMessages = offloadRequestImagesWithPolicy(options.messages, {
+		representation: "base64",
+		...maxRequestImageBytes === void 0 ? {} : { maxBytes: maxRequestImageBytes },
+		byteQuantum: 1,
+		byteLength: (ref) => Math.min(ref.bytes, requestImagePolicy.maxBytes)
+	});
+	const requestImages = await prepareRequestImages(requestMessages, attachments, requestImagePolicy, options.signal);
+	const exactMessages = offloadRequestImagesWithPolicy(requestMessages, {
+		representation: "base64",
+		...maxRequestImageBytes === void 0 ? {} : { maxBytes: maxRequestImageBytes },
+		byteQuantum: 1,
+		byteLength: (ref) => requestImages.get(ref.attachmentId).bytes
+	});
+	const toolNames = /* @__PURE__ */ new Map();
+	const messages = [];
+	for (const message of exactMessages) {
+		if (message.role === "system") {
+			messages.push({
+				role: "user",
+				content: flattenText(message),
+				timestamp: 0
+			});
+			continue;
+		}
+		if (message.role === "assistant") {
+			const assistant = toPiAssistant(message, onReplayDegrade);
+			for (const block of assistant.content) if (block.type === "toolCall") toolNames.set(CallId(block.id), block.name);
+			messages.push(assistant);
+			continue;
+		}
+		const content = await userContent(message.content.filter((block) => block.type !== "tool-result"), requestImages);
+		const results = message.content.filter((block) => block.type === "tool-result");
+		if (content.length > 0 || results.length === 0) messages.push({
+			role: "user",
+			content,
+			timestamp: 0
+		});
+		for (const result of results) {
+			const resultContent = await userContent(result.content, requestImages);
+			messages.push({
+				role: "toolResult",
+				toolCallId: result.toolCallId,
+				toolName: toolNames.get(result.toolCallId) ?? "unknown",
+				content: typeof resultContent === "string" ? [{
+					type: "text",
+					text: resultContent || "(no output)"
+				}] : resultContent,
+				isError: result.isError ?? false,
+				timestamp: 0
+			});
+		}
+	}
+	return piContext(options, messages);
 }
+//#endregion
+//#region lib/types/stream.js
 /**
-* Whether the installed catalog provider for one route declares an api-key
-* method — the only authentication this adapter obtains on its own.
+* pi-ai assistant event translation into the Harness streaming protocol.
 *
-* A key is what the harness resolves through its own credential seam and hands
-* pi-ai per request. pi-ai's other method, OAuth, resolves from a *stored*
-* OAuth credential alone: `resolveProviderAuth` has no ambient path for it,
-* this adapter builds its `Models` collection with no credential store, and
-* nothing here runs a login flow. So a provider offering OAuth by itself
-* leaves nothing for this adapter to authenticate with, and the posture such a
-* provider invites — no key configured, credentials discovered by the provider
-* — fails every request with `Provider is not configured`.
-* @param provider - provider route key.
-* @returns whether the catalog provider takes an api key; false for a route
-*   pi-ai does not ship, which the caller answers for separately.
-*/
-function catalogProviderTakesApiKey(provider) {
-	return catalogProvider(provider)?.auth.apiKey !== void 0;
-}
-/**
-* The installed catalog models for one route, indexed by model id.
-* @param provider - provider route key.
-* @returns catalog models by id; empty for a route pi-ai does not ship.
-*/
-function catalogModels(provider) {
-	if (!catalogProviders().has(provider)) return /* @__PURE__ */ new Map();
-	const models = getBuiltinModels(provider);
-	return new Map(models.map((model) => [model.id, model]));
-}
-/** Report a route the deployment cannot serve, naming the settings key at fault. */
-function invalid(provider, detail) {
-	throw new Error(`llm-pi-ai: provider "${provider}" ${detail}`);
-}
-/**
-* The one wire protocol a catalog route's shipped models agree on. This is what
-* lets a deployment add a model the installed catalog has not caught up with —
-* a provider's newest release — without restating the protocol its siblings
-* already use. A route whose shipped models disagree (an OpenAI-style catalog
-* spanning Responses and Chat Completions) has no such answer, so a model it
-* does not describe must name its protocol at the route.
+* pi-ai tool-call arguments are parsed objects while the Harness keeps their
+* raw JSON representation. pi-ai also reports failures as terminal stream
+* events, which this module maps into Harness finish chunks.
+*
+* @module nomix-llm-pi-ai/stream
 */
-function sharedCatalogApi(defaults) {
-	const apis = /* @__PURE__ */ new Set();
-	for (const model of defaults.values()) apis.add(model.api);
-	return apis.size === 1 ? [...apis][0] : void 0;
-}
 /**
-* Resolve one model's reasoning capability from its declared efforts.
-*
-* A declared dict translates to pi-ai's `thinkingLevelMap` with every level
-* decided explicitly: declared levels carry their wire spelling, undeclared
-* levels are pinned to `null` (unsupported). Pinning matters because pi-ai's
-* own defaulting is asymmetric — an absent key means "supported" for the five
-* base levels but "unsupported" for `xhigh`/`max` — and a profile author
-* should not need to know that. A declared `off` with no value is the one
-* exception: it stays absent from the map, which pi-ai reads as "supported,
-* send nothing" — the correct dispatch where not thinking is the parameter's
-* absence — while `off` with a value sends that value.
-* @param provider - provider route key, for diagnostics.
-* @param entry - the configured model entry.
-* @param base - the installed catalog entry of the same id, when one exists.
-* @returns the reasoning fields the materialized model carries.
+* Map pi-ai usage (reasoning folded into output by pi-ai).
+* @param usage - cumulative usage from the terminal pi-ai event.
+* @returns harness counts; cache fields appear only when non-zero (pi-ai reports zeros, not absence).
 */
-function resolveModelReasoning(provider, entry, base) {
-	const efforts = entry.reasoningEfforts;
-	if (efforts === void 0) return { reasoning: base?.reasoning ?? false };
-	if (efforts === false) return { reasoning: false };
-	if (efforts === null || Object.keys(efforts).length === 0) invalid(provider, `model "${entry.id}" has an empty reasoningEfforts; declare the offered levels, set false for a non-reasoning model, or omit the field to keep the installed catalog's capability`);
-	const declared = THINKING_LEVELS.flatMap((level) => {
-		const wire = efforts[level];
-		return wire === void 0 ? [] : [[level, wire]];
-	});
-	for (const [level, wire] of declared) if (wire === null) {
-		if (level !== "off") invalid(provider, `model "${entry.id}" reasoningEfforts.${level} needs the wire value dispatch should send; only "off" may leave it empty`);
-	} else if (wire.length === 0) invalid(provider, `model "${entry.id}" reasoningEfforts.${level} must not be an empty string`);
-	if (!declared.some(([level]) => level !== "off")) invalid(provider, `model "${entry.id}" reasoningEfforts offers no level beyond "off"; declare a thinking level, or set reasoningEfforts to false for a non-reasoning model`);
-	const map = {};
-	for (const level of THINKING_LEVELS) {
-		const wire = efforts[level];
-		if (wire === void 0) map[level] = null;
-		else if (wire !== null) map[level] = wire;
-	}
+function mapUsage(usage) {
 	return {
-		reasoning: true,
-		thinkingLevelMap: map
+		inputTokens: usage.input,
+		outputTokens: usage.output,
+		...usage.cacheRead > 0 ? { cacheReadTokens: usage.cacheRead } : {},
+		...usage.cacheWrite > 0 ? { cacheWriteTokens: usage.cacheWrite } : {}
 	};
 }
+function classifyPiAiError(message) {
+	if (/\b(?:401|403)\b/.test(message)) return "AUTH";
+	if (isQuotaExceededError(message)) return QUOTA_EXCEEDED_CODE;
+	if (/\b429\b|rate.?limit/i.test(message)) return "RATE_LIMIT";
+	if (/\b413\b|failed to buffer the request body:\s*length limit exceeded|payload too large|request body too large/i.test(message)) return "INVALID_REQUEST";
+	if (/\b400\b|invalid.?request/i.test(message)) return "INVALID_REQUEST";
+	if (/\b5\d\d\b/.test(message)) return "SERVER";
+	if (/\btime(?:d)?\s*out\b|timeout/i.test(message)) return "TIMEOUT";
+	if (/stream ended (?:before|without)\b/i.test(message)) return "TRANSPORT";
+	if (/\b(?:network|connection|socket|fetch)\b|\bECONN[A-Z]+\b/i.test(message) || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(message) || /\bterminated\b|premature close/i.test(message)) return "TRANSPORT";
+	return "PI_AI_ERROR";
+}
 /**
-* Resolve one model's compat block from the profile's reasoning switches.
-*
-* A model switch wins over the route switch; whatever neither sets keeps the
-* installed entry's value, and a field no layer decides falls through to
-* pi-ai's baseURL-derived detection. Only an `openai-completions` model takes
-* the switches at all: a model-level switch on any other protocol fails
-* resolution, while a route-level default skips past such models — the same
-* posture as the route-level `reasoning` default, which also must not fail
-* models it does not fit.
-* @param provider - provider route key, for diagnostics.
-* @param entry - the configured model entry.
-* @param route - the route-level switches, when any.
-* @param base - the installed catalog entry of the same id, when one exists.
-* @param api - the model's resolved wire protocol.
-* @returns a `compat` field to spread into the model, or nothing.
+* Map a terminal pi-ai event to the harness finish reason.
+* @param message - the assistant message carried by the `done` or `error` event.
+* @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+* @returns the mapped harness reason. Recognized error text, `stop` usage above
+*   `contextWindow`, and zero-output `length` usage that fills the window map
+*   to `CONTEXT_WINDOW_EXCEEDED`; a `stop` with no content blocks maps to an
+*   `EMPTY_RESPONSE` error.
 */
-function resolveModelCompat(provider, entry, route, base, api) {
-	const thinkingFormat = entry.compat?.thinkingFormat ?? route?.thinkingFormat;
-	const supportsReasoningEffort = entry.compat?.supportsReasoningEffort ?? route?.supportsReasoningEffort;
-	if (thinkingFormat === void 0 && supportsReasoningEffort === void 0) return {};
-	if (api !== "openai-completions") {
-		if (entry.compat?.thinkingFormat !== void 0 || entry.compat?.supportsReasoningEffort !== void 0) invalid(provider, `model "${entry.id}" sets compat reasoning switches, but its api is "${api}"; thinkingFormat and supportsReasoningEffort exist only on openai-completions`);
-		return {};
+function mapStopReason(message, contextWindow) {
+	const piAiOverflow = isContextOverflow(message, contextWindow);
+	const harnessOverflow = message.stopReason === "error" && message.errorMessage !== void 0 && isContextWindowExceededError(message.errorMessage);
+	if (piAiOverflow || harnessOverflow) return {
+		kind: "error",
+		failure: {
+			message: message.errorMessage ?? `pi-ai detected context overflow for model "${message.model}"`,
+			code: CONTEXT_WINDOW_EXCEEDED_CODE
+		}
+	};
+	switch (message.stopReason) {
+		case "stop":
+			if (message.content.length === 0) return {
+				kind: "error",
+				failure: {
+					message: `model "${message.model}" returned a completed response with no content`,
+					code: EMPTY_RESPONSE_CODE
+				}
+			};
+			return { kind: "stop" };
+		case "length": return { kind: "max-tokens" };
+		case "toolUse": return { kind: "tool-calls" };
+		case "aborted": return {
+			kind: "aborted",
+			failure: {
+				message: message.errorMessage ?? "pi-ai stream aborted",
+				code: "ABORTED"
+			}
+		};
+		case "error": {
+			const text = message.errorMessage ?? "pi-ai stream error";
+			return {
+				kind: "error",
+				failure: {
+					message: text,
+					code: classifyPiAiError(text)
+				}
+			};
+		}
 	}
-	return { compat: {
-		...base?.api === api ? base.compat : void 0,
-		...thinkingFormat === void 0 ? {} : { thinkingFormat },
-		...supportsReasoningEffort === void 0 ? {} : { supportsReasoningEffort }
-	} };
 }
 /**
-* Materialize one route's catalog by merging the installed catalog defaults
-* under the configured entries. A route with no configured `models` serves the
-* installed catalog unchanged, which is what keeps an existing
-* `providers: { deepseek: { apiKeyEnv: … } }` profile working untouched.
-* @param request - the route-level catalog facts.
-* @returns the materialized models and the explicitly configured request caps.
+* Translate the pi-ai event stream into StreamChunks. pi-ai never throws
+* mid-stream — failures arrive as `error` events, which become error/aborted
+* `finish` chunks (the harness protocol's other error-delivery style).
+* @param events - one assistant turn's pi-ai event stream.
+* @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+* @returns the harness chunks, ending with `usage` then `finish`; throws
+*   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
 */
-function resolveRouteModels(request) {
-	const { provider } = request;
-	const defaults = catalogModels(provider);
-	const providerBaseUrl = catalogProvider(provider)?.baseUrl;
-	const configured = request.models ?? [];
-	const overrides = request.modelOverrides ?? {};
-	for (const [id, override] of Object.entries(overrides)) {
-		if (id.length === 0) invalid(provider, "has a modelOverrides entry with an empty model id");
-		if (defaults.size === 0) invalid(provider, `sets modelOverrides for "${id}", but the installed catalog does not describe this route; a declared route spells every model out in its models list`);
-		if (configured.length > 0) invalid(provider, `sets modelOverrides for "${id}" beside a models list; models already replaces the served catalog, so declare the fields on its entries`);
-		if (!defaults.has(id)) invalid(provider, `modelOverrides names "${id}", which the installed catalog does not describe`);
-		if ("id" in override) invalid(provider, `modelOverrides entry "${id}" sets "id", which is the dict key`);
+async function* toStreamChunks(events, contextWindow) {
+	const toolIds = /* @__PURE__ */ new Map();
+	for await (const event of events) switch (event.type) {
+		case "start": break;
+		case "text_start":
+			yield {
+				type: "block-start",
+				index: event.contentIndex,
+				blockType: "text"
+			};
+			break;
+		case "text_delta":
+			yield {
+				type: "text-delta",
+				index: event.contentIndex,
+				text: event.delta
+			};
+			break;
+		case "text_end":
+			yield {
+				type: "block-end",
+				index: event.contentIndex,
+				block: {
+					type: "text",
+					text: event.content
+				}
+			};
+			break;
+		case "thinking_start":
+			yield {
+				type: "block-start",
+				index: event.contentIndex,
+				blockType: "reasoning"
+			};
+			break;
+		case "thinking_delta":
+			yield {
+				type: "reasoning-delta",
+				index: event.contentIndex,
+				text: event.delta
+			};
+			break;
+		case "thinking_end":
+			yield {
+				type: "block-end",
+				index: event.contentIndex,
+				block: {
+					type: "reasoning",
+					text: event.content
+				}
+			};
+			break;
+		case "toolcall_start": {
+			const partial = event.partial.content[event.contentIndex];
+			const id = partial?.type === "toolCall" ? partial.id : "";
+			const name = partial?.type === "toolCall" ? partial.name : "";
+			toolIds.set(event.contentIndex, {
+				id,
+				name
+			});
+			yield {
+				type: "block-start",
+				index: event.contentIndex,
+				blockType: "tool-call"
+			};
+			break;
+		}
+		case "toolcall_delta": {
+			const known = toolIds.get(event.contentIndex);
+			yield {
+				type: "tool-call-delta",
+				index: event.contentIndex,
+				id: CallId(known?.id ?? ""),
+				...known?.name !== void 0 && known.name.length > 0 ? { name: known.name } : {},
+				argumentsDelta: event.delta
+			};
+			break;
+		}
+		case "toolcall_end":
+			yield {
+				type: "block-end",
+				index: event.contentIndex,
+				block: {
+					type: "tool-call",
+					id: CallId(event.toolCall.id),
+					name: event.toolCall.name,
+					arguments: JSON.stringify(event.toolCall.arguments)
+				}
+			};
+			break;
+		case "done":
+			yield {
+				type: "usage",
+				usage: mapUsage(event.message.usage)
+			};
+			yield {
+				type: "finish",
+				reason: mapStopReason(event.message, contextWindow),
+				replayState: toPiReplayState(event.message)
+			};
+			return;
+		case "error":
+			yield {
+				type: "usage",
+				usage: mapUsage(event.error.usage)
+			};
+			yield {
+				type: "finish",
+				reason: mapStopReason(event.error, contextWindow)
+			};
+			return;
 	}
-	const entries = configured.length > 0 ? configured : [...defaults.values()].map((model) => ({
-		id: model.id,
-		...overrides[model.id]
-	}));
-	if (entries.length === 0) invalid(provider, "resolves no models; the installed catalog does not describe this route, so its models must be listed in configuration");
-	const routeApi = sharedCatalogApi(defaults);
-	const routeCompatDefined = request.compat?.thinkingFormat !== void 0 || request.compat?.supportsReasoningEffort !== void 0;
-	const seen = /* @__PURE__ */ new Set();
-	const configuredMaxTokens = /* @__PURE__ */ new Map();
-	const models = entries.map((entry) => {
-		if (entry.id.length === 0) invalid(provider, "has a model with an empty id");
-		if (seen.has(entry.id)) invalid(provider, `lists model "${entry.id}" more than once`);
-		seen.add(entry.id);
-		const base = defaults.get(entry.id);
-		const api = request.api ?? base?.api ?? routeApi;
-		if (api === void 0) invalid(provider, `model "${entry.id}" needs an api; the installed catalog does not describe it, so set the route's api to the wire protocol its endpoint speaks`);
-		const baseUrl = request.baseURL ?? base?.baseUrl ?? providerBaseUrl;
-		if (baseUrl === void 0) invalid(provider, `model "${entry.id}" needs a baseURL; the installed catalog does not describe this route`);
-		const contextWindow = entry.contextWindow ?? base?.contextWindow ?? request.defaultContextWindow;
-		if (!Number.isInteger(contextWindow) || contextWindow <= 0) invalid(provider, `model "${entry.id}" contextWindow must be a positive integer`);
-		const maxTokens = entry.maxTokens ?? base?.maxTokens ?? request.defaultMaxTokens;
-		if (!Number.isInteger(maxTokens) || maxTokens <= 0) invalid(provider, `model "${entry.id}" maxTokens must be a positive integer`);
-		if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
-		return {
-			...base,
-			id: entry.id,
-			name: entry.name ?? base?.name ?? entry.id,
-			api,
-			provider,
-			baseUrl,
-			input: declaredInput(entry.input) ?? base?.input ?? [...request.defaultInput],
-			cost: base?.cost ?? NO_COST,
-			contextWindow,
-			maxTokens,
-			...resolveModelReasoning(provider, entry, base),
-			...resolveModelCompat(provider, entry, request.compat, base, api)
-		};
-	});
-	if (routeCompatDefined && !models.some((model) => model.api === "openai-completions")) invalid(provider, "sets compat reasoning switches, but no model on the route speaks openai-completions; thinkingFormat and supportsReasoningEffort exist only on that protocol");
-	return {
-		models,
-		configuredMaxTokens
-	};
+	throw new LlmError("pi-ai event stream ended without done/error", "STREAM_CLOSED");
 }
 //#endregion
-//#region lib/types/provider.js
+//#region lib/types/adapter.js
 /**
-* Construction of the pi-ai `Provider` that one configured route registers into
-* the adapter's `Models` collection.
-*
-* Two constructions, one decision: a route the installed catalog ships, whose
-* profile does not override the wire protocol, **reuses that catalog provider**
-* with its models replaced — the catalog provider owns API implementations this
-* package cannot reconstruct (Bedrock loads its Smithy module through a
-* separate entry point), so rebuilding it from parts would silently narrow
-* which providers work. Every other route — one pi-ai has never heard of, or a
-* catalog route pointed at a different protocol — is built by `createProvider`
-* over the protocol table below.
+* Generic pi-ai-backed implementation of the Harness LLM seam.
 *
-* Credentials never reach this module's storage: the harness resolves a route's
-* key through `ctx.credentials` before the request enters pi-ai and hands it
-* over as a stream option, which `Models` presents to `resolve()` as the
-* credential key.
+* Each resolution produces one **immutable** snapshot — the profiles plus a
+* `Models` collection holding the `Provider` each route built — and an
+* operation captures a whole snapshot before its first `await`. A
+* configuration change builds a *new* collection rather than mutating the one
+* in use, because `Models.streamSimple()` is lazy: it resolves the provider
+* when the stream is first consumed, which is after the credential await, so a
+* mutated collection would let a request that started under one configuration
+* finish under another — or fail with a provider that no longer exists. This is
+* what makes the seam's per-step call freeze (`llm.prepareCall()`) hold all the
+* way down: switching models mid-reply takes effect on the next step, never
+* inside the one in flight.
 *
-* @module nomix-llm-pi-ai/provider
-*/
-/**
-* Wire protocols a configured route may name, mapped to pi-ai's lazily loaded
-* implementations. Each entry is the factory that pi-ai's matching provider
-* factory uses, so a hand-declared route reaches exactly the implementation a
-* catalog route would.
+* A route naming a credential reference still resolves it through the harness
+* seam and passes it as the request's `apiKey` option, which pi-ai treats as
+* the highest-priority auth override — that is what keeps the fail-loud
+* reference semantics. Everything that override does not cover reaches pi-ai
+* through the collection's own auth: the credential store holds the records a
+* login wrote and a refresh rotates, and the auth context answers the ambient
+* questions a provider asks while resolving. Both are stable across snapshots,
+* so a configuration change rebuilds the collection without forgetting who is
+* signed in.
 *
-* The table is deliberately narrow: the protocols a hand-declared route
-* actually reaches for today, each completely describable with a key, an
-* endpoint, and headers. Bedrock signs with SigV4 over AWS credentials and a
-* region, Vertex needs a project, a location, and application-default
-* credentials, Azure needs provider environment plus an api-version, and Codex
-* authenticates through OAuth — none of which this configuration shape can
-* express, so offering them would hand back a provider that cannot
-* authenticate. The remainder are absent for want of a consumer rather than a
-* blocker: each is one line here once a deployment needs it. Catalog routes
-* still reach every protocol through their own provider; only an explicit
-* override is refused.
+* @module nomix-llm-pi-ai/adapter
 */
-const PROTOCOLS = {
-	"openai-completions": openAICompletionsApi,
-	"openai-responses": openAIResponsesApi,
-	"anthropic-messages": anthropicMessagesApi
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
 };
-/**
-* Every wire protocol a configured route may name, most-reached first. The
-* order is the table's and therefore stable; a configuration surface offering
-* a choice presents the first as its default, which is why the protocol a
-* hand-declared gateway most often speaks — and the one endpoint interrogation
-* can read — leads.
-* @returns the supported protocol identifiers.
-*/
-function supportedProtocols() {
-	return Object.keys(PROTOCOLS);
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Copy profile stream knobs into pi-ai's common option vocabulary. */
+function profileOptions(profile, reasoning, apiKey) {
+	const enabledReasoning = reasoning === "off" ? void 0 : reasoning;
+	return {
+		...apiKey === void 0 ? {} : { apiKey },
+		...enabledReasoning === void 0 ? {} : { reasoning: enabledReasoning },
+		...profile.thinkingBudgets === void 0 ? {} : { thinkingBudgets: profile.thinkingBudgets },
+		...profile.cacheRetention === void 0 ? {} : { cacheRetention: profile.cacheRetention },
+		...profile.transport === void 0 ? {} : { transport: profile.transport },
+		...profile.timeoutMs === void 0 ? {} : { timeoutMs: profile.timeoutMs },
+		...profile.websocketConnectTimeoutMs === void 0 ? {} : { websocketConnectTimeoutMs: profile.websocketConnectTimeoutMs },
+		maxRetries: 0
+	};
 }
 /**
-* Api-key auth for a route the harness authenticates itself. `Models` calls
-* this after the adapter has already resolved the route's credential, so a
-* missing key here is not this layer's failure: a named-but-unresolvable
-* reference has already failed the request with `MISSING_CREDENTIAL`, and a
-* route naming no credential at all is deliberately unauthenticated. Reporting
-* it as configured hands the decision to the protocol, which is where the
-* requirement actually lives — pi-ai's OpenAI-compatible implementation, for
-* one, still insists on a key or an `Authorization` header of its own.
-* @param name - display name used as the resolution's status label.
-* @returns the api-key auth for a harness-authenticated route.
+* The profile default this exact model can actually take, for DESCRIBING it.
+* A configured level the model does not support yields none rather than
+* throwing: `resolveModel` builds the model catalog, and a catalog that fails
+* takes its whole provider out of every picker — so one mis-set profile field
+* would hide every model on the route, including the ones that support the
+* level. The request path still refuses, which is where a bad configuration
+* belongs: describing what a model can do must not fail because a deployment
+* asked it for something it cannot.
+* @param model - the resolved model descriptor.
+* @param effort - the profile's configured level, if any.
+* @returns the level when this model supports it, otherwise undefined.
 */
-function harnessApiKeyAuth(name) {
-	return {
-		name,
-		resolve: ({ credential }) => Promise.resolve({
-			auth: credential?.key === void 0 ? {} : { apiKey: credential.key },
-			source: name
-		})
-	};
+function describableReasoningLevel(model, effort) {
+	if (effort === void 0) return void 0;
+	return getSupportedThinkingLevels(model).some((level) => level === effort) ? effort : void 0;
+}
+/** Validate an explicit Harness/profile effort without invoking pi-ai's clamp. */
+function resolveReasoningLevel(model, effort) {
+	if (effort === void 0) return void 0;
+	if (getSupportedThinkingLevels(model).some((level) => level === effort)) return effort;
+	throw new LlmError(`pi-ai provider "${model.provider}" model "${model.id}" does not support reasoning effort "${effort}"`, "UNSUPPORTED_REASONING_EFFORT");
 }
 /**
-* The auth one route resolves its credential through.
-*
-* A catalog route keeps the installed provider's own auth, which is what
-* preserves provider-native ambient discovery for a profile naming no
-* credential. That holds even when the profile repoints the protocol: which
-* environment a provider reads is a property of the provider, not of the wire
-* format its models speak.
+* Selectable reasoning efforts for one model, or nothing at all.
 *
-* The single addition covers a catalog provider that offers no api-key method
-* at all. pi-ai resolves a request's `apiKey` override only when the provider
-* declares one (`resolveProviderAuth` checks `provider.auth.apiKey` before
-* honouring the override), so an OAuth-only provider — `openai-codex` is the
-* one the installed catalog ships — would refuse a profile's explicit key with
-* `Provider is not configured` before any request went out. Adding the harness
-* method beside the provider's own restores that route. A keyless profile adds
-* nothing and still reports the honest refusal, because this adapter resolves
-* credentials through its own seam and holds no OAuth store to fall back on.
-* @param spec - the resolved route facts.
-* @param catalog - the installed catalog provider, when pi-ai ships one.
-* @returns the auth to construct this route's provider with.
+* A model that carries no reasoning metadata — every hand-declared one, and
+* every catalog model pi-ai marks as non-reasoning — is reported by pi-ai as
+* supporting the single level `off`. Passing that through would offer a control
+* that cannot do what it says: `off` is translated to *omitting* the reasoning
+* option, which for such a model is byte-for-byte the same request as naming no
+* effort — so a provider whose own default is to think would keep thinking with
+* `off` selected. Omitting `reasoning` entirely is the seam's way of saying the
+* capability is unavailable, which leaves the surface offering only the
+* provider's default.
+* @param model - the resolved model descriptor.
+* @param defaultLevel - the profile's configured effort, already validated.
+* @returns the `reasoning` field, or an empty object when none can be offered.
 */
-function routeAuth(spec, catalog) {
-	if (catalog === void 0) return { apiKey: harnessApiKeyAuth(spec.displayName) };
-	if (catalog.auth.apiKey !== void 0 || !spec.namesCredential) return catalog.auth;
+function reasoningInfo(model, defaultLevel) {
+	if (!model.reasoning) return {};
+	return { reasoning: {
+		efforts: getSupportedThinkingLevels(model).map((level) => ({
+			id: ReasoningEffortId(level),
+			name: `${level.charAt(0).toUpperCase()}${level.slice(1)}`
+		})),
+		...defaultLevel === void 0 ? {} : { defaultEffort: ReasoningEffortId(defaultLevel) }
+	} };
+}
+/** Merge deployment headers while removing case-insensitive attribution collisions. */
+function requestHeaders(headers) {
+	const attribution = attributionHeaders();
+	const reserved = new Set(Object.keys(attribution).map((name) => name.toLowerCase()));
 	return {
-		...catalog.auth,
-		apiKey: harnessApiKeyAuth(spec.displayName)
+		...Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => !reserved.has(name.toLowerCase()))),
+		...attribution
 	};
 }
 /**
-* Reuse an installed catalog provider with this route's models and identity.
-* Model dispatch stays with the catalog provider, so its API implementations,
-* compatibility quirks, and ambient credential discovery are preserved exactly.
-* Catalog-owned dynamic refresh is dropped: this route's catalog is the
-* settings document, and a background refresh would contradict it.
+* pi-ai-backed multi-provider adapter. Each operation reads the current
+* profiles, so a configuration change reaches the next request without a
+* restart; model descriptors come from the collection those profiles built.
 */
-function reuseCatalogProvider(base, spec) {
-	const baseUrl = spec.baseURL ?? base.baseUrl;
-	return {
-		id: spec.provider,
-		name: spec.displayName,
-		...baseUrl === void 0 ? {} : { baseUrl },
-		auth: routeAuth(spec, base),
-		getModels: () => spec.models,
-		stream: (model, context, options) => base.stream(model, context, options),
-		streamSimple: (model, context, options) => base.streamSimple(model, context, options)
-	};
-}
+var PiAiAdapter = class extends LlmAdapter {
+	config;
+	snapshot;
+	constructor(config) {
+		super();
+		this.config = config;
+	}
+	/**
+	* The snapshot for the current profiles. Resolution memoizes its result, so
+	* an unchanged configuration is recognized by identity; a changed one gets a
+	* brand-new collection, leaving any snapshot an operation already captured
+	* untouched for as long as that operation holds it.
+	*/
+	current() {
+		const profiles = this.config.profiles();
+		if (this.snapshot?.profiles === profiles) return this.snapshot;
+		const models = createModels(this.config.auth);
+		for (const profile of profiles.values()) models.setProvider(profile.piProvider);
+		this.snapshot = {
+			profiles,
+			models
+		};
+		return this.snapshot;
+	}
+	/** The profile for one route within one snapshot, or the not-owned failure. */
+	profileOf(snapshot, provider) {
+		const profile = snapshot.profiles.get(provider);
+		if (profile === void 0) throw new LlmError(`pi-ai adapter does not own provider "${provider}"`, "NO_ADAPTER");
+		return profile;
+	}
+	/** The configured descriptor for one exact route/model pair within one snapshot. */
+	modelOf(snapshot, provider, model) {
+		this.profileOf(snapshot, provider);
+		const resolved = snapshot.models.getModel(provider, model);
+		if (resolved === void 0) throw new LlmError(`pi-ai provider "${provider}" has no configured model "${model}"`, "UNKNOWN_MODEL");
+		return resolved;
+	}
+	providerInfo(provider) {
+		return {
+			id: provider,
+			name: this.current().profiles.get(provider)?.displayName ?? provider
+		};
+	}
+	providerRetryPolicy(provider) {
+		return this.current().profiles.get(provider)?.retryPolicy;
+	}
+	listModels(provider) {
+		return Promise.resolve().then(() => {
+			const snapshot = this.current();
+			this.profileOf(snapshot, provider);
+			return snapshot.models.getModels(provider).map((model) => ({
+				provider,
+				id: model.id,
+				name: model.name,
+				inputModalities: [...model.input]
+			}));
+		});
+	}
+	resolveModel(provider, model, _signal) {
+		return Promise.resolve().then(() => {
+			const snapshot = this.current();
+			return this.modelInfo(snapshot, provider, model);
+		});
+	}
+	modelInfo(snapshot, provider, model) {
+		const profile = this.profileOf(snapshot, provider);
+		const resolvedModel = this.modelOf(snapshot, provider, model);
+		const defaultLevel = describableReasoningLevel(resolvedModel, profile.reasoning);
+		const configuredMaxTokens = profile.configuredMaxTokens.get(model);
+		return {
+			provider,
+			id: model,
+			name: resolvedModel.name,
+			inputModalities: [...resolvedModel.input],
+			context: { contextWindow: resolvedModel.contextWindow },
+			...configuredMaxTokens === void 0 ? {} : { defaultMaxTokens: configuredMaxTokens },
+			...reasoningInfo(resolvedModel, defaultLevel)
+		};
+	}
+	prepareCall(provider, model, _signal) {
+		const snapshot = this.current();
+		return Promise.resolve({
+			model: this.modelInfo(snapshot, provider, model),
+			stream: (options) => this.streamWithSnapshot(options, snapshot)
+		});
+	}
+	stream(options) {
+		return this.streamWithSnapshot(options, this.current());
+	}
+	async *streamWithSnapshot(options, snapshot) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			if (options.stop !== void 0) throw new LlmError("llm-pi-ai does not support GenerateOptions.stop", "UNSUPPORTED_OPTION");
+			const profile = this.profileOf(snapshot, options.provider);
+			const model = this.modelOf(snapshot, options.provider, options.model);
+			const reasoning = resolveReasoningLevel(model, options.reasoningEffort ?? profile.reasoning);
+			const apiKey = await this.config.resolveApiKey(options.provider, profile);
+			const consumer = new AbortController();
+			const upstream = options.signal === void 0 ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]);
+			const streamIdleTimeoutMs = profile.streamIdleTimeoutMs;
+			const watchdog = __addDisposableResource(env_1, idleWatchdog(upstream, streamIdleTimeoutMs, "LLM_STREAM_IDLE_TIMEOUT"), false);
+			try {
+				const containsImage = options.messages.some((message) => contentHasImage(message.content));
+				if (containsImage && !model.input.includes("image")) throw new LlmError(`pi-ai model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
+				const attachments = containsImage ? this.config.resolveAttachments?.() : void 0;
+				if (containsImage && attachments === void 0) throw new LlmError("pi-ai image input requires the durable attachment service", "UNSUPPORTED_CONTENT");
+				const onReplayDegrade = (reason) => {
+					this.config.onReplayDegrade?.({
+						provider: options.provider,
+						model: options.model,
+						reason
+					});
+				};
+				const context = attachments === void 0 ? toPiContext(options, void 0, onReplayDegrade) : await toPiContext({
+					...options,
+					signal: watchdog.signal
+				}, attachments, onReplayDegrade, profile.maxRequestImageBytes, {
+					maxPixels: profile.requestImagePixelBudget,
+					maxBytes: profile.requestImageMaxBytes
+				});
+				const iterator = toStreamChunks(snapshot.models.streamSimple(model, context, {
+					...profileOptions(profile, reasoning, apiKey),
+					...options.temperature === void 0 ? {} : { temperature: options.temperature },
+					...options.maxTokens === void 0 ? {} : { maxTokens: options.maxTokens },
+					...options.sessionId === void 0 ? {} : { sessionId: String(options.sessionId) },
+					signal: watchdog.signal,
+					headers: requestHeaders(profile.headers)
+				}), model.contextWindow)[Symbol.asyncIterator]();
+				let exhausted = false;
+				try {
+					while (true) {
+						const result = await watchdog.next(iterator);
+						const timeout = timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT");
+						if (timeout !== void 0) throw timeout;
+						if (result.done) {
+							exhausted = true;
+							return;
+						}
+						yield result.value;
+					}
+				} finally {
+					if (!exhausted) {
+						consumer.abort("pi-ai stream consumer stopped");
+						try {
+							await iterator.return(void 0);
+						} catch (_abortedSdkTeardown) {}
+					}
+				}
+			} catch (error) {
+				if (timeoutOf(watchdog.signal, "LLM_STREAM_IDLE_TIMEOUT") !== void 0) throw new LlmError(`pi-ai stream idle timeout after ${streamIdleTimeoutMs}ms`, "TIMEOUT", { cause: error });
+				if (options.signal?.aborted) throw new LlmError("pi-ai request aborted by caller", "ABORTED", { cause: error });
+				throw error;
+			} finally {
+				consumer.abort("pi-ai stream consumer stopped");
+			}
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+};
+//#endregion
+//#region lib/types/auth.js
 /**
-* Build the pi-ai provider for one resolved route.
-* @param spec - the resolved route facts.
-* @returns the provider to register in the adapter's `Models` collection.
-* @throws Error when the route names a wire protocol this build cannot serve.
+* The three adapters between pi-ai's auth model and the harness credential
+* plane. Every pi-ai-specific concept stays on this side of them: the harness
+* seams they consume — `ctx.credentials` records and `ctx.authorization` flows —
+* name nothing from this library, so another adapter family can arrive with a
+* different auth model and share the same two seams.
+*
+* @module nomix-llm-pi-ai/auth
 */
-function buildProvider(spec) {
-	const catalog = catalogProvider(spec.provider);
-	if (catalog !== void 0 && spec.api === void 0) return reuseCatalogProvider(catalog, spec);
-	const factory = spec.api === void 0 ? void 0 : PROTOCOLS[spec.api];
-	if (factory === void 0) throw new Error(`llm-pi-ai: provider "${spec.provider}" names api "${spec.api}", which this build cannot serve; supported protocols are ${supportedProtocols().join(", ")}`);
-	return createProvider({
-		id: spec.provider,
-		name: spec.displayName,
-		...spec.baseURL === void 0 ? {} : { baseUrl: spec.baseURL },
-		auth: routeAuth(spec, catalog),
-		models: spec.models,
-		api: factory()
-	});
+/**
+* The record scope every credential this adapter family stores is written
+* under. It is the plugin's registered name, which is what tells a later
+* reader — a configuration UI, or a second adapter family serving the same
+* provider name — that this plugin owns the format inside the record.
+*/
+const RECORD_SCOPE = "llm-pi-ai";
+/**
+* The record address for one pi-ai provider id.
+* @param providerId - pi-ai's own provider id, which is also the harness route key.
+* @returns the scoped credential key this adapter family reads and writes.
+*/
+function recordKeyFor(providerId) {
+	return credentialKey(RECORD_SCOPE, providerId);
 }
-//#endregion
-//#region lib/types/config.js
 /**
-* Configuration schema and provider-profile validation for the pi-ai adapter.
-* Profiles are a dict keyed by provider route, so the composition base and a
-* user-settings layer merge per provider and the route set is structural.
-*
-* A route key is not required to name an installed pi-ai provider. When it does,
-* that provider's endpoint, protocol, display name, and model catalog are the
-* profile's defaults and the profile overrides them field by field; when it does
-* not, the profile is the whole provider declaration. Resolution therefore ends
-* in a built pi-ai `Provider` per route: everything a request needs is decided
-* once, while the configuration key that made a route unserviceable can still be
-* named in the failure.
+* Translate a stored record into the credential pi-ai expects.
 *
-* @module nomix-llm-pi-ai/config
+* An `api-key` record is structural on both sides, so it is rebuilt field by
+* field. A `grant` payload is pi-ai's own OAuth credential, stored verbatim:
+* the seam treats it as opaque JSON precisely so a library that owns a token
+* format keeps owning it, refresh fields and all.
+* @param record - the stored record, or undefined when nothing is stored.
+* @returns the pi-ai credential, or undefined for an absent record.
 */
-/** Default maximum idle interval while an adapter stream read is outstanding. */
-const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
-/** Context capacity assumed for a model neither configuration nor the catalog sizes. */
-const DEFAULT_CONTEXT_WINDOW = 262144;
-/** Output capability assumed for a model neither configuration nor the catalog sizes. */
-const DEFAULT_MAX_TOKENS = 32768;
+function toPiCredential(record) {
+	if (record === void 0) return void 0;
+	if (record.kind === "api-key") return {
+		type: "api_key",
+		...record.key === void 0 ? {} : { key: record.key },
+		...record.env === void 0 ? {} : { env: { ...record.env } }
+	};
+	return record.payload;
+}
 /**
-* Modalities assumed for a model neither configuration nor the catalog
-* declares. Text is the floor every supported protocol certainly carries, so
-* this is the absence of a declaration rather than a guess at the endpoint:
-* nothing can interrogate a gateway for its modalities, and the two wrong
-* answers do not cost the same. Under-claiming refuses the image before it is
-* attached, naming the model. Over-claiming admits one the provider then
-* rejects mid-turn, after the message is durable, leaving the session
-* repeating a request that cannot succeed.
+* Translate a pi-ai credential into the record to store.
+* @param credential - what a login or refresh produced.
+* @returns the record to commit, in the union the credential seam stores.
 */
-const DEFAULT_INPUT = ["text"];
-const thinkingBudgets = z.object({
-	minimal: z.number(),
-	low: z.number(),
-	medium: z.number(),
-	high: z.number()
-});
-const compatProfile = z.object({
-	thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
-	supportsReasoningEffort: z.boolean()
-});
+function toRecord(credential) {
+	if (credential.type === "api_key") return {
+		kind: "api-key",
+		...credential.key === void 0 ? {} : { key: credential.key },
+		...credential.env === void 0 ? {} : { env: { ...credential.env } }
+	};
+	return {
+		kind: "grant",
+		payload: credential
+	};
+}
 /**
-* Keys are the offered levels, values their wire spellings. A valueless key
-* (`off:`) survives validation because schemastery passes nullable data
-* through before any member schema runs — `z.const(null)` only controls the
-* error for non-null wrong values and what a configuration UI renders.
-* Only resolution decides which levels may leave the value empty, so the
-* diagnostic can name the route and model. The assertion narrows
-* schemastery's `Dict`, which types every literal key as required; dict
-* validation checks only present keys, so the runtime value is a partial record.
+* The credential service, or the failure that names what is missing. Reads
+* answer "nothing stored" without a service, because a composition with no
+* credential plane genuinely holds no credential; writes refuse, because a
+* login whose grant silently evaporated would report success and then fail
+* every request.
+* @param ctx - the plugin context.
+* @returns the live service.
+* @throws {LlmError} code `NO_CREDENTIAL_STORE` when none is mounted.
 */
-const reasoningEfforts = z.dict(z.union([z.string(), z.const(null)]), z.union(THINKING_LEVELS));
-/** The fields a `models` entry and a `modelOverrides` value share; only the id's home differs. */
-const modelFields = {
-	name: z.string(),
-	contextWindow: z.number().step(1).min(1),
-	maxTokens: z.number().step(1).min(1),
-	input: z.array(z.union(MODALITIES)),
-	reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
-	compat: compatProfile
-};
-const modelProfile = z.object({
-	id: z.string().required(),
-	...modelFields
-});
-/** A {@link modelProfile} whose id lives in the `modelOverrides` dict key. */
-const modelOverride = z.object(modelFields);
-const profile = z.object({
-	apiKeyEnv: z.string().role("credential-ref"),
-	displayName: z.string(),
-	api: z.union(supportedProtocols()),
-	baseURL: z.string(),
-	models: z.array(modelProfile),
-	modelOverrides: z.dict(modelOverride),
-	compat: compatProfile,
-	defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
-	defaultMaxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
-	defaultInput: z.array(z.union(MODALITIES)).default([...DEFAULT_INPUT]),
-	headers: z.dict(z.string()),
-	reasoning: z.union(THINKING_LEVELS),
-	thinkingBudgets,
-	cacheRetention: z.union([
-		"none",
-		"short",
-		"long"
-	]),
-	transport: z.union([
-		"sse",
-		"websocket",
-		"websocket-cached",
-		"auto"
-	]),
-	timeoutMs: z.natural(),
-	websocketConnectTimeoutMs: z.natural(),
-	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
-	retryPolicy: RetryPolicySchema
-});
-/** Runtime schema for {@link Config}. */
-const Config = z.object({ providers: z.dict(profile).default({}) });
+function writableStore(ctx) {
+	const credentials = ctx.get("credentials");
+	if (credentials === void 0) throw new LlmError("llm-pi-ai: this composition mounts no credentials service, so there is nowhere to store the credential a sign-in produces; mount one (nomix-credentials-local) to sign in", "NO_CREDENTIAL_STORE");
+	return credentials;
+}
 /**
-* Reject a section this adapter could not serve. Registered as the settings
-* namespace's validator, so an unserviceable profile is refused where it is
-* *written* — `settings.mutate` answers `settings-rejected` with the offending
-* route and model named — instead of being stored and then quietly disabling
-* every route in the namespace. It stays a validator rather than a schema
-* transform because the schema is also the shape a configuration surface
-* renders and the value an absent section resolves to; wrapping it would break
-* both.
-* @param config - the resolved section to check.
-* @throws Error naming the route and model that cannot be served.
+* A pi-ai `CredentialStore` over the harness credential records.
+*
+* pi-ai runs OAuth refresh *inside* `modify()`, so this store's exclusion has
+* to cover a network round trip rather than a file rename — which is why the
+* record write path takes a wait limit of its own rather than the short one a
+* local write would need.
+*
+* pi-ai asks this store about every provider in the collection, hand-declared
+* routes included, and a route key is an arbitrary settings dict key while a
+* record id is not. An id outside the record grammar can never have stored a
+* record, so reads answer "nothing stored" and a delete has nothing to remove;
+* only `modify` refuses it, because a write that cannot land must not report
+* that it did.
+* @param ctx - the plugin context carrying the optional `ctx.credentials`.
+* @returns the store to hand `createModels()`.
 */
-function assertServiceable(config) {
-	resolveProfiles(config.providers);
-}
-/** Reject removed pre-release profile fields and name their replacements. */
-function rejectRemovedFields(provider, source) {
-	const legacy = source;
-	if ("provider" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets "provider", which moved to the providers dict key`);
-	if ("maxRetries" in legacy || "maxRetryDelayMs" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets maxRetries or maxRetryDelayMs, which were removed; compose agent recovery with nomix-llm-retry`);
+function credentialStoreFrom(ctx) {
+	return {
+		async read(providerId) {
+			const credentials = ctx.get("credentials");
+			if (credentials === void 0) return void 0;
+			if (!isCredentialKeySegment(providerId)) return void 0;
+			return toPiCredential(await credentials.readRecord(recordKeyFor(providerId)));
+		},
+		async list() {
+			const stored = await ctx.get("credentials")?.listRecords() ?? [];
+			const mine = [];
+			for (const entry of stored) {
+				if (credentialKeyScope(entry.key) !== "llm-pi-ai") continue;
+				mine.push({
+					providerId: credentialKeyId(entry.key),
+					type: entry.kind === "api-key" ? "api_key" : "oauth"
+				});
+			}
+			return mine;
+		},
+		async modify(providerId, mutate) {
+			if (!isCredentialKeySegment(providerId)) throw new LlmError(`llm-pi-ai: provider id "${providerId}" cannot address a stored credential record (a record id is a lowercase hyphenated identifier); authenticate this route through apiKeyEnv instead of a stored credential`, "UNSTORABLE_PROVIDER_ID");
+			return toPiCredential(await writableStore(ctx).modifyRecord(recordKeyFor(providerId), async (current) => {
+				const next = await mutate(toPiCredential(current));
+				return next === void 0 ? void 0 : toRecord(next);
+			}));
+		},
+		async delete(providerId) {
+			if (!isCredentialKeySegment(providerId)) return;
+			await writableStore(ctx).deleteRecord(recordKeyFor(providerId));
+		}
+	};
 }
 /**
-* Validate profiles and return a detached route-keyed map suitable for
-* per-request reads. This is the one explicit resolve step, so an omitted dict
-* resolves to the empty (dormant) route set here rather than through a hidden
-* fallback, and each route's models and pi-ai provider are materialized once.
-* @param providers - configured provider profiles keyed by route.
-* @returns validated profiles in configuration order.
+* A pi-ai `AuthContext` over the harness credential plane and the host
+* filesystem.
+*
+* `env()` answers from the credential seam first, so a value a deployment
+* stored through the harness is found by a provider's own ambient discovery —
+* without this, that discovery reads only the process environment and a stored
+* `AWS_ACCESS_KEY_ID` is invisible to it. `fileExists()` answers about the host
+* process's own filesystem rather than the workspace `ctx.fs` seam, because the
+* paths it is asked about (`~/.aws/credentials`, application-default
+* credentials) are facts about where this process runs, not about the project
+* under edit.
+* @param ctx - the plugin context carrying the optional `ctx.credentials`.
+* @returns the auth context to hand `createModels()`.
 */
-function resolveProfiles(providers) {
-	if (Array.isArray(providers)) throw new Error("llm-pi-ai: providers is now a dict keyed by provider route, not an array of profiles");
-	const entries = Object.entries(providers ?? {});
-	const resolved = /* @__PURE__ */ new Map();
-	for (const [provider, source] of entries) {
-		rejectRemovedFields(provider, source);
-		if (provider.length === 0) throw new Error("llm-pi-ai: provider names must be non-empty");
-		if (source.baseURL !== void 0 && source.baseURL.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty baseURL`);
-		if (source.displayName !== void 0 && source.displayName.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty displayName`);
-		const streamIdleTimeoutMs = source.streamIdleTimeoutMs ?? 3e5;
-		if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`llm-pi-ai: provider "${provider}" streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
-		const defaultInput = [...source.defaultInput ?? DEFAULT_INPUT];
-		if (defaultInput.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" defaultInput must name at least one modality`);
-		const displayName = source.displayName ?? provider;
-		const catalog = resolveRouteModels({
-			provider,
-			...source.api === void 0 ? {} : { api: source.api },
-			...source.baseURL === void 0 ? {} : { baseURL: source.baseURL },
-			...source.models === void 0 ? {} : { models: source.models },
-			...source.modelOverrides === void 0 ? {} : { modelOverrides: source.modelOverrides },
-			...source.compat === void 0 ? {} : { compat: source.compat },
-			defaultInput,
-			defaultContextWindow: source.defaultContextWindow ?? 262144,
-			defaultMaxTokens: source.defaultMaxTokens ?? 32768
-		});
-		const { apiKeyEnv, retryPolicy, models: _models, displayName: _displayName, ...rest } = source;
-		resolved.set(provider, {
-			...rest,
-			provider,
-			displayName,
-			...apiKeyEnv === void 0 ? {} : { apiKeyEnv: credentialRef(apiKeyEnv) },
-			streamIdleTimeoutMs,
-			retryPolicy: resolveRetryPolicy(retryPolicy, `llm-pi-ai: provider "${provider}" retryPolicy`),
-			...rest.headers === void 0 ? {} : { headers: { ...rest.headers } },
-			...rest.thinkingBudgets === void 0 ? {} : { thinkingBudgets: { ...rest.thinkingBudgets } },
-			configuredMaxTokens: catalog.configuredMaxTokens,
-			piProvider: buildProvider({
-				provider,
-				displayName,
-				...source.api === void 0 ? {} : { api: source.api },
-				...source.baseURL === void 0 ? {} : { baseURL: source.baseURL },
-				models: catalog.models,
-				namesCredential: apiKeyEnv !== void 0
-			})
-		});
-	}
-	return resolved;
+function authContextFrom(ctx) {
+	return {
+		async env(name) {
+			if (isCredentialRefName(name)) {
+				const hit = await ctx.get("credentials")?.resolve(credentialRef(name));
+				if (hit !== void 0) return hit.value;
+			}
+			return launchEnvironmentOf(ctx).get(name)?.value;
+		},
+		async fileExists(path) {
+			const expanded = path.startsWith("~/") || path === "~" ? resolve(homedir(), path.slice(1).replace(/^\//, "")) : path;
+			try {
+				await access(expanded);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
 }
 //#endregion
 //#region lib/types/discovery.js
@@ -1700,6 +2134,156 @@ async function discoverModels(request, storedApiKey) {
 	return readListing(body);
 }
 //#endregion
+//#region lib/types/login.js
+/**
+* Authorization flows for the pi-ai providers that ship a login. This is the
+* whole of the translation between the harness's neutral notice/prompt
+* vocabulary and pi-ai's `AuthInteraction`; nothing above it knows which
+* library ran the conversation.
+*
+* @module nomix-llm-pi-ai/login
+*/
+/**
+* The login methods one catalog provider offers.
+*
+* A method appears only when pi-ai can actually run it: `oauth` always carries
+* a `login`, while an api-key method has one only when the provider collects
+* its key interactively — which every installed one currently does, so a key is
+* typed into pi-ai's own prompt rather than into the settings form.
+* @param provider - the installed catalog provider, if pi-ai ships one.
+* @returns its methods, most preferred first; empty when it offers no login.
+*/
+function loginMethods(provider) {
+	const methods = [];
+	const oauth = provider?.auth.oauth;
+	if (oauth !== void 0) methods.push({
+		id: "oauth",
+		label: oauth.loginLabel ?? oauth.name
+	});
+	const apiKey = provider?.auth.apiKey;
+	if (apiKey?.login !== void 0) methods.push({
+		id: "api-key",
+		label: apiKey.name
+	});
+	return methods;
+}
+/**
+* Restate one pi-ai login event in the seam's vocabulary.
+*
+* A device-code grant is the one event carrying two things the human needs at
+* once — where to go and what to type there — which is why the neutral notice
+* has a `code` beside its `url` rather than folding the code into the message.
+* @param event - what pi-ai reported.
+* @param session - the attempt to report it to.
+*/
+function relay(event, session) {
+	switch (event.type) {
+		case "info": {
+			const link = event.links?.[0];
+			session.notify({
+				message: event.message,
+				...link === void 0 ? {} : { url: link.url }
+			});
+			return;
+		}
+		case "auth_url":
+			session.notify({
+				message: event.instructions ?? "Open this page to continue signing in.",
+				url: event.url
+			});
+			return;
+		case "device_code":
+			session.notify({
+				message: "Enter this code on the verification page to finish signing in.",
+				url: event.verificationUri,
+				code: event.userCode
+			});
+			return;
+		case "progress":
+			session.notify({ message: event.message });
+			return;
+		default: session.notify({ message: "Signing in…" });
+	}
+}
+/**
+* Restate one pi-ai prompt in the seam's vocabulary.
+*
+* `manual_code` becomes a plain text question because the difference pi-ai
+* draws — a code the human copies from a browser rather than a value they know
+* — changes nothing a surface renders. Its own `signal` is carried through, and
+* that is the part which matters: it is how a flow racing a typed code against
+* a browser callback withdraws the losing question.
+* @param prompt - what pi-ai asked.
+* @returns the neutral prompt to put to the human.
+*/
+function restate(prompt) {
+	const signal = prompt.signal === void 0 ? {} : { signal: prompt.signal };
+	switch (prompt.type) {
+		case "select": return {
+			...signal,
+			kind: "select",
+			message: prompt.message,
+			options: prompt.options
+		};
+		case "secret": return {
+			...signal,
+			kind: "secret",
+			message: prompt.message,
+			...prompt.placeholder === void 0 ? {} : { placeholder: prompt.placeholder }
+		};
+		default: return {
+			...signal,
+			kind: "text",
+			message: prompt.message,
+			...prompt.placeholder === void 0 ? {} : { placeholder: prompt.placeholder }
+		};
+	}
+}
+/**
+* Register one authorization flow per installed provider that ships a login.
+*
+* Registration is unconditional on configuration: a provider has to be signed
+* into before a route for it is worth adding, so the flow exists from the
+* moment the plugin mounts rather than appearing once a profile does.
+* @param ctx - the plugin context carrying `ctx.authorization`.
+* @param auth - the injectables every collection here is built with.
+*/
+function registerPiAiFlows(ctx, auth) {
+	for (const providerId of catalogProviderIds()) {
+		const provider = catalogProvider(providerId);
+		const [first, ...rest] = loginMethods(provider);
+		/* v8 ignore next 3 -- every id here names an installed provider and every
+		installed provider ships a login, so nothing is skipped today; the guard
+		is what keeps that from becoming a crash if either stops being true. */
+		if (provider === void 0 || first === void 0) continue;
+		/* v8 ignore next 7 -- every installed catalog id today is a lowercase
+		hyphenated identifier; the guard keeps a future upstream id outside the
+		record grammar (dotted or uppercase, as vendor ids elsewhere already
+		are) from throwing in `recordKeyFor` and failing the whole mount. */
+		if (!isCredentialKeySegment(providerId)) {
+			ctx.logger.warn("llm-pi-ai: catalog provider \"%s\" cannot address a credential record; its sign-in is not offered", providerId);
+			continue;
+		}
+		ctx.authorization.registerFlow({
+			key: recordKeyFor(providerId),
+			label: provider.name,
+			methods: [first, ...rest],
+			async run(session) {
+				const models = createModels(auth);
+				models.setProvider(provider);
+				const type = session.method === "oauth" ? "oauth" : "api_key";
+				await models.login(providerId, type, {
+					signal: session.signal,
+					notify: (event) => {
+						relay(event, session);
+					},
+					prompt: (prompt) => session.prompt(restate(prompt))
+				});
+			}
+		});
+	}
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Generic pi-ai-backed LLM adapter plugin. One plugin instance owns a dict of
@@ -1773,15 +2357,10 @@ function registrationFacts(profiles) {
 	})).sort((left, right) => left.provider.localeCompare(right.provider));
 }
 /**
-* The configurable-provider directory: every installed catalog route this
-* adapter can authenticate, plus every route the current profiles declare. A
-* hand-declared route has no catalog entry, so without this union it would
-* have no settings address and configuration surfaces could neither show nor
-* edit it.
-*
-* The profile half is unconditional, which is what keeps a route already
-* stored against a withheld provider editable and deletable rather than
-* stranded in the settings document with nothing on the page to remove it.
+* The configurable-provider directory: every installed catalog route, plus
+* every route the current profiles declare. A hand-declared route has no
+* catalog entry, so without this union it would have no settings address and
+* configuration surfaces could neither show nor edit it.
 * @param profiles - the currently resolved provider profiles.
 * @returns the directory entries in catalog order, declared routes last.
 */
@@ -1797,7 +2376,7 @@ function directoryEntries(profiles) {
 			declared: !catalog.has(provider)
 		});
 	};
-	for (const provider of catalog) if (catalogProviderTakesApiKey(provider)) declare(provider, provider);
+	for (const provider of catalog) declare(provider, provider);
 	for (const [provider, profile] of profiles) declare(provider, profile.displayName);
 	return [...entries.values()];
 }
@@ -1834,14 +2413,22 @@ function apply(ctx, config) {
 		if (hit !== void 0 && hit.length > 0) return assertUsableApiKey(hit, "llm-pi-ai", ref);
 		throw new LlmError(`llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not set — store ${ref} through the credentials service (the web Models page writes it) or export it, and remove apiKeyEnv only if this provider should authenticate from pi-ai's own environment discovery`, "MISSING_CREDENTIAL");
 	};
+	const auth = {
+		credentials: credentialStoreFrom(ctx),
+		authContext: authContextFrom(ctx)
+	};
 	const adapter = new PiAiAdapter({
 		profiles,
 		resolveApiKey,
+		auth,
 		resolveAttachments: () => ctx.get("attachments"),
 		onReplayDegrade: ({ provider, model, reason }) => {
 			ctx.logger.warn(`llm-pi-ai: unusable replay state on assistant history for route "${provider}/${model}"; sending that message as provider-neutral content (${reason})`);
 		}
 	});
+	ctx.inject(["authorization"], (authorized) => {
+		registerPiAiFlows(authorized, auth);
+	});
 	let directory;
 	let directoryFacts;
 	const ensureDirectory = () => {
@@ -1904,4 +2491,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, PiAiAdapter, apply, inject, name, supportedProtocols };
+export { Config, PiAiAdapter, apply, inject, name, recordKeyFor, supportedProtocols };