@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/providers/runtimes/protocol/anthropic-compat.ts

@@ -0,0 +1,104 @@
+import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
+import type { Api, Model } from "../../../../engine/types.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type {
+	ProbeContext,
+	ProbeResult,
+	RuntimeAuth,
+	RuntimeDescriptor,
+	RuntimeTier,
+} from "../../types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+import { synthLocalModel, targetBaseUrl, withAsIs } from "../common/local-synth.js";
+import { probeOpenAIModels, probeUrl } from "../common/probe-helpers.js";
+
+export interface AnthropicCompatSpec {
+	id: string;
+	displayName: string;
+	provider: string;
+	auth: RuntimeAuth;
+	tier: RuntimeTier;
+	defaultCapabilities: CapabilityFlags;
+	hidden?: boolean;
+	messagesPath?: string;
+	modelsPath?: string;
+}
+
+export interface AnthropicCompatSynthesisInput {
+	target: TargetDescriptor;
+	wireModelId: string;
+	kb: KnowledgeBaseHit | null;
+	defaultCapabilities: CapabilityFlags;
+	provider: string;
+	baseUrlForTarget?: (targetUrl: string) => string;
+}
+
+function synthesizeAnthropicCompatModel(input: AnthropicCompatSynthesisInput): Model<Api> {
+	return synthLocalModel({
+		target: input.target,
+		wireModelId: input.wireModelId,
+		kb: input.kb,
+		defaultCapabilities: input.defaultCapabilities,
+		apiFamily: "anthropic-messages",
+		provider: input.provider,
+		baseUrlForTarget: input.baseUrlForTarget ?? withAsIs,
+	});
+}
+
+export function makeAnthropicCompatRuntime(spec: AnthropicCompatSpec): RuntimeDescriptor {
+	const messagesPath = spec.messagesPath ?? "/v1/messages";
+	const modelsPath = spec.modelsPath ?? "/v1/models";
+	return {
+		id: spec.id,
+		displayName: spec.displayName,
+		kind: "http",
+		tier: spec.tier,
+		apiFamily: "anthropic-messages",
+		auth: spec.auth,
+		defaultCapabilities: spec.defaultCapabilities,
+		...(spec.hidden === true ? { hidden: true } : {}),
+		async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
+			const base = targetBaseUrl(target);
+			if (!base) return { ok: false, error: "target has no url" };
+			return probeUrl(`${base}${messagesPath}`, ctx, "HEAD");
+		},
+		async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
+			const base = targetBaseUrl(target);
+			if (!base) return [];
+			return probeOpenAIModels(base, ctx, modelsPath);
+		},
+		synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
+			return synthesizeAnthropicCompatModel({
+				target,
+				wireModelId,
+				kb,
+				defaultCapabilities: spec.defaultCapabilities,
+				provider: spec.provider,
+			});
+		},
+	};
+}
+
+const defaultCapabilities: CapabilityFlags = {
+	chat: true,
+	tools: true,
+	toolCallFormat: "anthropic",
+	reasoning: false,
+	vision: false,
+	audio: false,
+	embeddings: false,
+	rerank: false,
+	fim: false,
+	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
+	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
+};
+
+export default makeAnthropicCompatRuntime({
+	id: "anthropic-compat",
+	displayName: "Generic Anthropic-compatible",
+	provider: "anthropic-compat",
+	auth: "api-key",
+	tier: "protocol",
+	defaultCapabilities,
+});

package/src/domains/providers/runtimes/protocol/anthropic-messages.ts

@@ -0,0 +1,28 @@
+import type { Api, Model } from "../../../../engine/types.js";
+
+import { synthesizeCatalogBackedModel } from "../../catalog.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+
+export interface AnthropicMessagesSynthesisInput {
+	target: TargetDescriptor;
+	wireModelId: string;
+	kb: KnowledgeBaseHit | null;
+	defaultCapabilities: CapabilityFlags;
+	provider: string;
+	defaultBaseUrl: string;
+}
+
+export function synthesizeAnthropicMessagesModel(input: AnthropicMessagesSynthesisInput): Model<Api> {
+	return synthesizeCatalogBackedModel({
+		target: input.target,
+		wireModelId: input.wireModelId,
+		kb: input.kb,
+		defaultCapabilities: input.defaultCapabilities,
+		runtimeId: "anthropic",
+		api: "anthropic-messages",
+		provider: input.provider,
+		defaultBaseUrl: input.defaultBaseUrl,
+	});
+}

package/src/domains/providers/runtimes/protocol/bedrock.ts

@@ -0,0 +1,26 @@
+import type { Api, Model } from "../../../../engine/types.js";
+
+import { synthesizeCatalogBackedModel } from "../../catalog.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+
+export interface BedrockSynthesisInput {
+	target: TargetDescriptor;
+	wireModelId: string;
+	kb: KnowledgeBaseHit | null;
+	defaultCapabilities: CapabilityFlags;
+}
+
+export function synthesizeBedrockModel(input: BedrockSynthesisInput): Model<Api> {
+	return synthesizeCatalogBackedModel({
+		target: input.target,
+		wireModelId: input.wireModelId,
+		kb: input.kb,
+		defaultCapabilities: input.defaultCapabilities,
+		runtimeId: "bedrock",
+		api: "bedrock-converse-stream",
+		provider: "amazon-bedrock",
+		defaultBaseUrl: "",
+	});
+}

package/src/domains/providers/runtimes/protocol/google.ts

@@ -0,0 +1,27 @@
+import type { Api, Model } from "../../../../engine/types.js";
+
+import { synthesizeCatalogBackedModel } from "../../catalog.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+
+export interface GoogleSynthesisInput {
+	target: TargetDescriptor;
+	wireModelId: string;
+	kb: KnowledgeBaseHit | null;
+	defaultCapabilities: CapabilityFlags;
+	defaultBaseUrl: string;
+}
+
+export function synthesizeGoogleModel(input: GoogleSynthesisInput): Model<Api> {
+	return synthesizeCatalogBackedModel({
+		target: input.target,
+		wireModelId: input.wireModelId,
+		kb: input.kb,
+		defaultCapabilities: input.defaultCapabilities,
+		runtimeId: "google",
+		api: "google-generative-ai",
+		provider: "google",
+		defaultBaseUrl: input.defaultBaseUrl,
+	});
+}

package/src/domains/providers/runtimes/protocol/openai-compat.ts

@@ -0,0 +1,145 @@
+import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
+import type { Api, Model } from "../../../../engine/types.js";
+import { probeOpenAICompatReasoning } from "../../probe/reasoning.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type {
+	ProbeContext,
+	ProbeResult,
+	ReasoningProbeResult,
+	RuntimeApiFamily,
+	RuntimeAuth,
+	RuntimeDescriptor,
+	RuntimeTier,
+} from "../../types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+import { synthLocalModel, targetBaseUrl, targetRootUrl, withAsIs, withV1 } from "../common/local-synth.js";
+import { probeOpenAIModelCatalog, probeOpenAIModels, probeUrl } from "../common/probe-helpers.js";
+
+export interface OpenAICompatSpec {
+	id: string;
+	displayName: string;
+	provider: string;
+	auth: RuntimeAuth;
+	tier: RuntimeTier;
+	defaultCapabilities: CapabilityFlags;
+	healthPath?: string;
+	modelsPath?: string;
+	apiFamily?: RuntimeApiFamily;
+	baseUrlStyle?: "v1" | "asIs";
+}
+
+export interface OpenAICompatSynthesisInput {
+	target: TargetDescriptor;
+	wireModelId: string;
+	kb: KnowledgeBaseHit | null;
+	defaultCapabilities: CapabilityFlags;
+	apiFamily?: RuntimeApiFamily;
+	provider: string;
+	baseUrlForTarget?: (targetUrl: string) => string;
+}
+
+export function synthesizeOpenAICompatModel(input: OpenAICompatSynthesisInput): Model<Api> {
+	return synthLocalModel({
+		target: input.target,
+		wireModelId: input.wireModelId,
+		kb: input.kb,
+		defaultCapabilities: input.defaultCapabilities,
+		apiFamily: input.apiFamily ?? "openai-completions",
+		provider: input.provider,
+		baseUrlForTarget: input.baseUrlForTarget ?? withV1,
+	});
+}
+
+export function makeOpenAICompatRuntime(spec: OpenAICompatSpec): RuntimeDescriptor {
+	const apiFamily = spec.apiFamily ?? "openai-completions";
+	const asIs = spec.baseUrlStyle === "asIs";
+	const baseUrlForTarget = asIs ? withAsIs : withV1;
+	const healthPath = spec.healthPath ?? "/v1/models";
+	const modelsPath = spec.modelsPath ?? "/v1/models";
+	// The default paths carry their own `/v1`, so they are relative to the server
+	// root and a target naming the `/v1` mount point has to be reduced to it. An
+	// `asIs` spec sends the URL verbatim, so it keeps whatever the user typed.
+	const probeBase = asIs ? targetBaseUrl : targetRootUrl;
+	return {
+		id: spec.id,
+		displayName: spec.displayName,
+		kind: "http",
+		tier: spec.tier,
+		apiFamily,
+		auth: spec.auth,
+		defaultCapabilities: spec.defaultCapabilities,
+		async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
+			const base = probeBase(target);
+			if (!base) return { ok: false, error: "target has no url" };
+			const health = await probeUrl(`${base}${healthPath}`, ctx);
+			if (!health.ok) return health;
+			const catalog = await probeOpenAIModelCatalog(base, ctx, modelsPath);
+			const result: ProbeResult = { ...health };
+			if (catalog.models.length > 0) result.models = catalog.models;
+			if (Object.keys(catalog.modelStates).length > 0) result.modelStates = catalog.modelStates;
+			if (Object.keys(catalog.modelCapabilities).length > 0) {
+				result.modelCapabilities = catalog.modelCapabilities;
+				const selected = target.defaultModel?.trim();
+				const selectedCaps = selected ? catalog.modelCapabilities[selected] : undefined;
+				if (selected && selectedCaps) {
+					result.discoveredCapabilities = selectedCaps;
+					result.capabilityModelId = selected;
+				}
+			}
+			return result;
+		},
+		async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
+			const base = probeBase(target);
+			if (!base) return [];
+			return probeOpenAIModels(base, ctx, modelsPath);
+		},
+		async probeReasoning(target: TargetDescriptor, modelId: string, ctx: ProbeContext): Promise<ReasoningProbeResult> {
+			const base = probeBase(target);
+			if (!base) return { reasoning: false, latencyMs: 0, error: "target has no url" };
+			const apiKeyEnv = target.auth?.apiKeyEnvVar;
+			const apiKey = apiKeyEnv && ctx.credentialsPresent.has(apiKeyEnv) ? process.env[apiKeyEnv] : undefined;
+			const probeOpts: Parameters<typeof probeOpenAICompatReasoning>[0] = {
+				baseUrl: base,
+				modelId,
+				timeoutMs: Math.max(ctx.httpTimeoutMs, 8000),
+			};
+			if (apiKey) probeOpts.apiKey = apiKey;
+			if (ctx.signal) probeOpts.signal = ctx.signal;
+			return probeOpenAICompatReasoning(probeOpts);
+		},
+		synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
+			return synthesizeOpenAICompatModel({
+				target,
+				wireModelId,
+				kb,
+				defaultCapabilities: spec.defaultCapabilities,
+				apiFamily,
+				provider: spec.provider,
+				baseUrlForTarget,
+			});
+		},
+	};
+}
+
+const defaultCapabilities: CapabilityFlags = {
+	chat: true,
+	tools: false,
+	reasoning: false,
+	vision: false,
+	audio: false,
+	embeddings: false,
+	rerank: false,
+	fim: false,
+	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
+	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
+};
+
+export default makeOpenAICompatRuntime({
+	id: "openai-compat",
+	displayName: "Generic OpenAI-compatible",
+	provider: "openai-compat",
+	auth: "api-key",
+	tier: "protocol",
+	defaultCapabilities,
+});

package/src/domains/providers/support.ts

@@ -0,0 +1,238 @@
+import type { ClioSettings } from "../../core/config.js";
+import { type AuthTarget, resolveAuthTarget, resolveRuntimeAuthTarget } from "./auth/index.js";
+import { catalogProviderForRuntime, listCatalogModelsForRuntime } from "./catalog.js";
+import { getRuntimeRegistry } from "./registry.js";
+import type { RuntimeDescriptor } from "./types/runtime-descriptor.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+export type ProviderSupportGroup = "featured" | "cloud-api" | "subscription" | "local-http";
+
+/**
+ * Where a runtime's model ids come from, which decides whether their order
+ * means anything.
+ *
+ * `catalog` is the pi-ai provider data, keyed in name order: for openai the two
+ * ASCII-first of 38 ids are `gpt-4` and `gpt-4-turbo`, so any prefix of it is
+ * alphabetical accident rather than a recommendation. `runtime` is a
+ * descriptor's own `knownModels`, which this repo curates and orders with
+ * intent, so its head means something.
+ */
+export type RuntimeModelListSource = "runtime" | "catalog" | "none";
+
+export interface ProviderSupportEntry {
+	runtimeId: string;
+	label: string;
+	group: ProviderSupportGroup;
+	summary: string;
+	/** Absent when the ids are catalog-ordered, because then there is no default to recommend. */
+	defaultModel?: string;
+	modelHints: string[];
+	modelSource: RuntimeModelListSource;
+	featured: boolean;
+	connectable: boolean;
+	supportsCustomUrl: boolean;
+}
+
+export interface ResolvedProviderReference {
+	input: string;
+	target: TargetDescriptor | null;
+	runtime: RuntimeDescriptor;
+	authTarget: AuthTarget;
+}
+
+const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
+	alcf: "ALCF inference gateway (Sophia/Metis) via Globus",
+	anthropic: "Anthropic API",
+	"anthropic-max": "Claude Pro/Max subscription via Anthropic OAuth",
+	bedrock: "Amazon Bedrock",
+	"claude-code": "Claude Code subscription via installed claude CLI",
+	"claude-sdk": "Claude Code subscription via Claude Agent SDK",
+	deepseek: "DeepSeek API",
+	google: "Google Gemini API",
+	groq: "Groq API",
+	mistral: "Mistral API",
+	openai: "OpenAI Platform API",
+	"openai-codex": "ChatGPT Plus/Pro via Codex OAuth",
+	openrouter: "OpenRouter API",
+	"ollama-native": "Ollama native API",
+	"lmstudio-native": "LM Studio SDK + native model management",
+	llamacpp: "llama.cpp server (auto-detect surface)",
+	"anthropic-compat": "Generic Anthropic-compatible REST",
+	"openai-compat": "Generic OpenAI-compatible REST",
+};
+
+function groupPriority(group: ProviderSupportGroup): number {
+	switch (group) {
+		case "featured":
+			return 0;
+		case "subscription":
+			return 1;
+		case "cloud-api":
+			return 2;
+		case "local-http":
+			return 3;
+	}
+}
+
+export function supportGroupLabel(group: ProviderSupportGroup): string {
+	switch (group) {
+		case "featured":
+			return "Featured";
+		case "subscription":
+			return "Subscriptions";
+		case "cloud-api":
+			return "Cloud APIs";
+		case "local-http":
+			return "Local HTTP";
+	}
+}
+
+function classifyGroup(runtime: RuntimeDescriptor): ProviderSupportGroup {
+	if (runtime.id === "openai-codex") return "featured";
+	if (runtime.id === "alcf") return "cloud-api";
+	if (runtime.auth === "oauth" || runtime.auth === "claude-cli") return "subscription";
+	if (catalogProviderForRuntime(runtime.id) || (runtime.auth === "api-key" && !runtime.probe)) {
+		return "cloud-api";
+	}
+	return "local-http";
+}
+
+function knownModelsFor(runtimeId: string, runtime: RuntimeDescriptor | null): string[] {
+	const catalogModels = listCatalogModelsForRuntime(runtimeId);
+	if (catalogModels.length === 0) return runtime?.knownModels ? [...runtime.knownModels] : [];
+	return catalogModels.map((model) => model.id);
+}
+
+export function listKnownModelsForRuntime(runtimeId: string): string[] {
+	return knownModelsFor(runtimeId, getRuntimeIfRegistered(runtimeId));
+}
+
+function getRuntimeIfRegistered(runtimeId: string): RuntimeDescriptor | null {
+	try {
+		return getRuntimeRegistry().get(runtimeId);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * A descriptor that carries its own `knownModels` answers for its model story
+ * even when the catalog also answers for it. `claude-code` and `claude-sdk` are
+ * both: the catalog wins in `listKnownModelsForRuntime`, and they are left on
+ * that path here rather than having their display and default changed by a
+ * decision about openai. Which of the two lists should win for those runtimes
+ * is a separate question.
+ */
+export function runtimeModelListSource(runtime: RuntimeDescriptor): RuntimeModelListSource {
+	if (runtime.knownModels && runtime.knownModels.length > 0) return "runtime";
+	if (listCatalogModelsForRuntime(runtime.id).length > 0) return "catalog";
+	return "none";
+}
+
+function modelListSourceForRuntimeId(runtimeId: string): RuntimeModelListSource {
+	const runtime = getRuntimeIfRegistered(runtimeId);
+	if (runtime) return runtimeModelListSource(runtime);
+	return listCatalogModelsForRuntime(runtimeId).length > 0 ? "catalog" : "none";
+}
+
+/**
+ * The model id a caller may persist without being told which one to use.
+ * Undefined for catalog-ordered runtimes: the head of that list is the
+ * alphabetically first id, not the one anybody would choose.
+ */
+export function defaultModelForRuntime(runtimeId: string): string | undefined {
+	if (modelListSourceForRuntimeId(runtimeId) === "catalog") return undefined;
+	return listKnownModelsForRuntime(runtimeId)[0];
+}
+
+/**
+ * What a screen may say about a runtime's models. A catalog-ordered list gets
+ * its size and its source instead of a sample, so nothing false is asserted
+ * about which ids matter.
+ */
+export function describeRuntimeModels(entry: ProviderSupportEntry, sample: number): string {
+	if (entry.modelSource === "catalog") return `${entry.modelHints.length} in pi-ai catalog`;
+	if (entry.modelHints.length === 0) return "-";
+	return entry.modelHints.slice(0, sample).join(", ");
+}
+
+export function buildProviderSupportEntry(runtime: RuntimeDescriptor): ProviderSupportEntry {
+	// The descriptor in hand, not a registry lookup of its id: an entry built for
+	// a runtime that is not in the global registry used to report no models at all.
+	const modelHints = knownModelsFor(runtime.id, runtime);
+	const modelSource = runtimeModelListSource(runtime);
+	const defaultModel = modelSource === "catalog" ? undefined : modelHints[0];
+	return {
+		runtimeId: runtime.id,
+		label: runtime.displayName,
+		group: classifyGroup(runtime),
+		summary: SUMMARY_BY_RUNTIME_ID[runtime.id] ?? runtime.displayName,
+		...(defaultModel ? { defaultModel } : {}),
+		modelHints,
+		modelSource,
+		featured: runtime.id === "openai-codex",
+		connectable: runtime.auth === "oauth" || runtime.auth === "api-key",
+		supportsCustomUrl:
+			runtime.kind === "http" &&
+			(classifyGroup(runtime) === "local-http" ||
+				runtime.id === "openai-compat" ||
+				runtime.id === "anthropic-compat" ||
+				runtime.id === "alcf"),
+	};
+}
+
+export function compareProviderSupportEntries(a: ProviderSupportEntry, b: ProviderSupportEntry): number {
+	return (
+		groupPriority(a.group) - groupPriority(b.group) ||
+		(a.featured === b.featured ? 0 : a.featured ? -1 : 1) ||
+		a.label.localeCompare(b.label) ||
+		a.runtimeId.localeCompare(b.runtimeId)
+	);
+}
+
+export interface ListProviderSupportOptions {
+	includeHidden?: boolean;
+}
+
+export function listProviderSupportEntries(
+	runtimes: ReadonlyArray<RuntimeDescriptor>,
+	options: ListProviderSupportOptions = {},
+): ProviderSupportEntry[] {
+	const filtered = options.includeHidden ? runtimes : runtimes.filter((runtime) => runtime.hidden !== true);
+	return filtered.map((runtime) => buildProviderSupportEntry(runtime)).sort(compareProviderSupportEntries);
+}
+
+export function configuredTargetsForRuntime(
+	settings: Readonly<ClioSettings>,
+	runtimeId: string,
+): ReadonlyArray<TargetDescriptor> {
+	return settings.targets.filter((target) => target.runtime === runtimeId);
+}
+
+export function resolveProviderReference(
+	input: string,
+	settings: Readonly<ClioSettings>,
+	getRuntime: (runtimeId: string) => RuntimeDescriptor | null,
+): ResolvedProviderReference | null {
+	const trimmed = input.trim();
+	if (trimmed.length === 0) return null;
+	const target = settings.targets.find((entry) => entry.id === trimmed) ?? null;
+	if (target) {
+		const runtime = getRuntime(target.runtime);
+		if (!runtime) return null;
+		return {
+			input: trimmed,
+			target,
+			runtime,
+			authTarget: resolveAuthTarget(target, runtime),
+		};
+	}
+	const runtime = getRuntime(trimmed);
+	if (!runtime) return null;
+	return {
+		input: trimmed,
+		target: null,
+		runtime,
+		authTarget: resolveRuntimeAuthTarget(runtime),
+	};
+}

package/src/domains/providers/thinking-control-policy.ts

@@ -0,0 +1,85 @@
+import type { ThinkingLevel } from "./types/capability-flags.js";
+
+export type ThinkingBudgetByLevel = Partial<Record<ThinkingLevel, number>>;
+export type ThinkingEffortByLevel = Partial<Record<ThinkingLevel, string | null>>;
+
+const ANTHROPIC_MIN_THINKING_BUDGET = 1024;
+const ANTHROPIC_VISIBLE_OUTPUT_RESERVE = 1024;
+
+export const ANTHROPIC_DEFAULT_THINKING_BUDGETS: Readonly<ThinkingBudgetByLevel> = {
+	minimal: 1024,
+	low: 2048,
+	medium: 8192,
+	high: 16384,
+	xhigh: 32768,
+};
+
+export function thinkingBudgetFromMap(
+	budgets: ThinkingBudgetByLevel | undefined,
+	level: ThinkingLevel,
+): number | undefined {
+	if (!budgets) return undefined;
+	if (level === "off") return undefined;
+	if (level === "minimal") return budgets.minimal ?? budgets.low;
+	if (level === "xhigh") return budgets.xhigh ?? budgets.high;
+	return budgets[level];
+}
+
+export function thinkingEffortFromMap(
+	efforts: ThinkingEffortByLevel | undefined,
+	level: ThinkingLevel,
+): string | undefined {
+	if (!efforts) return undefined;
+	// `off` is only wireable when a family maps it explicitly. Models that
+	// reason unconditionally unless told otherwise need an off-effort to send;
+	// sending nothing leaves them reasoning at full rate. Families that reason
+	// only on request still omit the key and keep the send-nothing behaviour.
+	const exact = efforts[level];
+	if (exact === null) return undefined;
+	if (typeof exact === "string") return exact;
+	if (level === "minimal") {
+		const low = efforts.low;
+		return typeof low === "string" ? low : undefined;
+	}
+	if (level === "xhigh") {
+		const high = efforts.high;
+		return typeof high === "string" ? high : undefined;
+	}
+	return undefined;
+}
+
+export function defaultAnthropicBudgetForLevel(
+	level: ThinkingLevel,
+	maxTokens: number | undefined,
+): number | undefined {
+	const desired = thinkingBudgetFromMap(ANTHROPIC_DEFAULT_THINKING_BUDGETS, level);
+	if (desired === undefined) return undefined;
+	if (!Number.isFinite(maxTokens) || maxTokens === undefined || maxTokens <= 0) return desired;
+	if (maxTokens <= ANTHROPIC_MIN_THINKING_BUDGET) return undefined;
+
+	const preferredCap = maxTokens - ANTHROPIC_VISIBLE_OUTPUT_RESERVE;
+	const absoluteCap = maxTokens - 1;
+	const cap = preferredCap >= ANTHROPIC_MIN_THINKING_BUDGET ? preferredCap : absoluteCap;
+	return Math.max(ANTHROPIC_MIN_THINKING_BUDGET, Math.min(desired, cap));
+}
+
+export function defaultAnthropicEffortForLevel(
+	level: ThinkingLevel,
+	effortMap?: ThinkingEffortByLevel,
+): string | undefined {
+	const mapped = thinkingEffortFromMap(effortMap, level);
+	if (mapped) return mapped;
+	switch (level) {
+		case "minimal":
+		case "low":
+			return "low";
+		case "medium":
+			return "medium";
+		case "high":
+			return "high";
+		case "xhigh":
+			return thinkingEffortFromMap(effortMap, "xhigh");
+		default:
+			return undefined;
+	}
+}