@xopcai/xopc 0.0.389 → 0.0.390

package/dist/src/home-intelligence/host.js

@@ -1,10 +1,10 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { HomeAdviceBudgetExceededError, isHomeProseLocalized } from "./generator.js";
 import { homePatternKey } from "./strategy.js";
-import { HomeAdvicePolicy } from "./policy.js";
 import { HomeIntelligenceRepository } from "./repository.js";
 import { HomeOpportunityApplicationService } from "./application-service.js";
+import { HomeAdvicePolicy } from "./policy.js";
+import { HomeAdviceBudgetExceededError, isHomeProseLocalized } from "./generator.js";
 import { buildHomeOpportunityNotification } from "./notification.js";
 import { createHash } from "node:crypto";
 //#region src/home-intelligence/host.ts

package/dist/src/media-shared/http/provider-http.d.ts

@@ -1,9 +1,3 @@
-/**
- * Shared provider HTTP client (voice, STT/TTS, image-generation extensions).
- *
- * Wraps `globalThis.fetch` with SSRF guard (`assertSafeUrl`), timeout + signal
- * merge, and standardized errors via `assertOkOrThrowProviderError`.
- */
 import { type SsrfGuardOptions } from './ssrf-guard.js';
 export interface ProviderHttpRequestConfig extends SsrfGuardOptions {
     /** Hard timeout in milliseconds. Required: callers must always specify. */

package/dist/src/media-shared/http/provider-http.js

@@ -1,3 +1,4 @@
+import { assertProviderUsage, init_model_usage } from "../../providers/model-usage.js";
 import { assertOkOrThrowProviderError } from "./provider-http-errors.js";
 import { assertSafeUrl } from "./ssrf-guard.js";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -8,6 +9,7 @@ import { setTimeout as setTimeout$1 } from "node:timers/promises";
 * Wraps `globalThis.fetch` with SSRF guard (`assertSafeUrl`), timeout + signal
 * merge, and standardized errors via `assertOkOrThrowProviderError`.
 */
+init_model_usage();
 function mergeHeadersRecord(input) {
 	const out = {};
 	if (!input) return out;
@@ -25,16 +27,15 @@ function mergeHeadersRecord(input) {
 * to assertOk / parse / stream). Throws SsrfBlockedError on guard failure.
 */
 async function fetchWithTimeoutGuarded(url, options) {
+	assertProviderUsage("endpoint", String(url));
 	await assertSafeUrl(url, options);
 	const controller = new AbortController();
 	const timeoutHandle = setTimeout(() => controller.abort(), options.timeoutMs);
-	const callerSignal = options.signal;
-	if (callerSignal) if (callerSignal.aborted) controller.abort(callerSignal.reason);
-	else callerSignal.addEventListener("abort", () => controller.abort(callerSignal.reason), { once: true });
+	const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
 	try {
 		return await fetch(url, {
 			...options.init,
-			signal: controller.signal
+			signal
 		});
 	} finally {
 		clearTimeout(timeoutHandle);

package/dist/src/media-understanding/runner.d.ts

@@ -1,31 +1,3 @@
-/**
- * MediaUnderstanding capability runner.
- *
- * Orchestrates per-attachment fallback across providers for one capability
- * (audio / image / video). For each attachment:
- *   1. Build the candidate provider list from the registry, ordered by
- *      autoPriority (lower = first), with caller-supplied `providerOrder`
- *      overriding when set.
- *   2. Try providers in order. A provider is SKIPPED when it does not declare
- *      the requested capability OR does not implement the corresponding method.
- *   3. The first provider whose capability call resolves successfully wins;
- *      its output is recorded as `chosen`. Failures are recorded as attempts
- *      and the next provider is tried.
- *   4. When ALL providers for an attachment fail, the attachment task is
- *      `failed`; when no provider was even eligible (capability not registered),
- *      it's `disabled`.
- *
- * DECISION (per docs/voice-rearchitecture.md §5):
- *   - This is a thin runner only. xopc v2.0 ships ONLY audio; image/video
- *     branches exist as type-level fall-throughs (the runner happily handles
- *     them once a provider registers describeImage / describeVideo, but no
- *     image-specific helpers — like multi-image batching — live here yet).
- *   - We deliberately do NOT port openclaw's `MediaAttachmentCache` (which
- *     handles temp-file extraction, SSRF re-validation on remote URLs, etc.).
- *     For xopc v2.0 the caller is expected to pre-load the buffer; remote URL
- *     fetching is the caller's responsibility (typically the channel adapter
- *     does this before invoking the runner).
- */
 import type { AudioTranscriptionRequest, CapabilityAttachmentInput, ImageDescriptionRequest, MediaCapability, MediaUnderstandingProvider, MediaUnderstandingResult, VideoDescriptionRequest } from './types.js';
 export type { CapabilityAttachmentInput } from './types.js';
 export interface RunCapabilityOptions {

package/dist/src/media-understanding/runner.js

@@ -1,7 +1,9 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { assertProviderUsage, init_model_usage, isProviderUsageScopeError } from "../providers/model-usage.js";
 import { listProvidersForCapability } from "./registry.js";
 //#region src/media-understanding/runner.ts
+init_model_usage();
 init_logger();
 const log = createLogger("MediaUnderstandingRunner");
 const KIND_BY_CAPABILITY = {
@@ -90,6 +92,7 @@ async function runCapability(options) {
 			}
 			const startedAt = Date.now();
 			try {
+				assertProviderUsage(provider.id, request.baseUrl);
 				const callResult = await method(request);
 				const text = callResult.text?.trim() ?? "";
 				if (!text) {
@@ -123,6 +126,7 @@ async function runCapability(options) {
 				});
 				break;
 			} catch (error) {
+				if (isProviderUsageScopeError(error)) throw error;
 				if (options.signal?.aborted) throw error;
 				const reason = error instanceof Error ? error.message : String(error);
 				log.warn({

package/dist/src/platform/client.d.ts

@@ -33,9 +33,9 @@ export declare const RuntimeCommandSchema: z.ZodObject<{
                 intents: z.ZodArray<z.ZodEnum<{
                     review: "review";
                     coding: "coding";
+                    vision: "vision";
                     fast: "fast";
                     reasoning: "reasoning";
-                    vision: "vision";
                     understanding: "understanding";
                 }>>;
                 allow: z.ZodArray<z.ZodString>;

package/dist/src/platform/contracts.d.ts

@@ -119,9 +119,9 @@ export declare const AgentManifestSchema: z.ZodObject<{
         intents: z.ZodArray<z.ZodEnum<{
             review: "review";
             coding: "coding";
+            vision: "vision";
             fast: "fast";
             reasoning: "reasoning";
-            vision: "vision";
             understanding: "understanding";
         }>>;
         allow: z.ZodArray<z.ZodString>;

package/dist/src/providers/env-keys.js

@@ -16,6 +16,9 @@ var init_env_keys = __esmMin((() => {
 		openai: ["OPENAI_API_KEY"],
 		anthropic: ["ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
 		deepseek: ["DEEPSEEK_API_KEY"],
+		"qwen-token-plan-cn": ["QWEN_TOKEN_PLAN_CN_API_KEY"],
+		"qwen-token-plan": ["QWEN_TOKEN_PLAN_API_KEY"],
+		"qwen-token-plan-individual": ["QWEN_TOKEN_PLAN_API_KEY"],
 		google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
 		"google-vertex": [
 			"GOOGLE_CLOUD_API_KEY",

package/dist/src/providers/extension-stream-bridge.js

@@ -1,11 +1,13 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { assertProviderUsage, init_model_usage } from "./model-usage.js";
 import "./constants.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";
 import { init_providers } from "./index.js";
 import { stripPromptCacheBoundary } from "../agent/prompt/cache-boundary.js";
 import { createAssistantMessageEventStream, getCurrentSystemPrompt, getCurrentTools, streamSimple } from "@earendil-works/pi-ai/compat";
 //#region src/providers/extension-stream-bridge.ts
+init_model_usage();
 init_plugin_registry();
 init_providers();
 init_logger();
@@ -70,6 +72,7 @@ function collectExtraStreamOptions(options) {
 /** Wraps {@link streamSimple} so extension-registered models use the plugin `createStream()` path. */
 function createExtensionAwareStreamFn() {
 	return ((model, context, options) => {
+		assertProviderUsage(model.provider, model.baseUrl);
 		if (model.baseUrl !== "extension://provider-plugin") return streamSimple(model, context, options);
 		const plugin = getProviderRegistry().get(model.provider);
 		if (!plugin) return streamSimple(model, context, options);

package/dist/src/providers/index.js

@@ -468,6 +468,21 @@ var init_providers = __esmMin((() => {
 			category: "specialty",
 			supportsApiKey: true
 		},
+		"qwen-token-plan-cn": {
+			name: "Alibaba Bailian Subscription (China)",
+			category: "domestic",
+			supportsApiKey: true
+		},
+		"qwen-token-plan": {
+			name: "Qwen Token Plan (International)",
+			category: "domestic",
+			supportsApiKey: true
+		},
+		"qwen-token-plan-individual": {
+			name: "Qwen Token Plan Individual (International)",
+			category: "domestic",
+			supportsApiKey: true
+		},
 		"dashscope": {
 			name: "DashScope (Alibaba)",
 			category: "domestic",

package/dist/src/providers/model-call.d.ts

@@ -7,10 +7,13 @@ export declare function resolveModelCallOptions(model: Model<Api>, options?: Sim
 /**
  * Complete a one-shot request with xopc credential resolution and extension-provider routing.
  */
-export declare function completeWithResolvedCredentials(model: Model<Api>, context: Context, options: SimpleStreamOptions, credentialOptions: CredentialResolverOptions | undefined, usageContext: AiUsageContext): Promise<AssistantMessage>;
+declare function completeWithResolvedCredentialsInner(model: Model<Api>, context: Context, options: SimpleStreamOptions, credentialOptions: CredentialResolverOptions | undefined, usageContext: AiUsageContext): Promise<AssistantMessage>;
 /**
  * Start a model stream with xopc credential resolution and extension-provider routing.
  * Callers that need live visible output should consume the returned stream before calling
  * its `result()` method.
  */
-export declare function createResolvedModelStream(model: Model<Api>, context: Context, options: SimpleStreamOptions, credentialOptions: CredentialResolverOptions | undefined, usageContext: AiUsageContext): Promise<import("@earendil-works/pi-ai/compat").AssistantMessageEventStream>;
+declare function createResolvedModelStreamInner(model: Model<Api>, context: Context, options: SimpleStreamOptions, credentialOptions: CredentialResolverOptions | undefined, usageContext: AiUsageContext): Promise<import("@earendil-works/pi-ai/compat").AssistantMessageEventStream>;
+export declare function completeWithResolvedCredentials(...args: Parameters<typeof completeWithResolvedCredentialsInner>): Promise<AssistantMessage>;
+export declare function createResolvedModelStream(...args: Parameters<typeof createResolvedModelStreamInner>): Promise<import("@earendil-works/pi-ai/compat").AssistantMessageEventStream>;
+export {};

package/dist/src/providers/model-call.js

@@ -1,3 +1,4 @@
+import { assertProviderUsage, init_model_usage, modelUsageOriginForCall, withModelUsageOrigin } from "./model-usage.js";
 import { init_constants } from "./constants.js";
 import { getApiKey, init_providers } from "./index.js";
 import { createExtensionAwareStreamFn } from "./extension-stream-bridge.js";
@@ -6,6 +7,7 @@ import { finishAiUsageFromMessage, observeAiUsageStream, startAiUsageCall } from
 import { assertCloudCreditBudgetActive, cloudCreditBudgetHeaders, reportCloudCreditError } from "./xopc-cloud-credit-budget.js";
 import { completeSimple, normalizeContext } from "@earendil-works/pi-ai/compat";
 //#region src/providers/model-call.ts
+init_model_usage();
 init_constants();
 init_providers();
 function isLocalModelBaseUrl(baseUrl) {
@@ -28,6 +30,7 @@ async function resolveModelCallApiKey(model, credentialOptions) {
 }
 async function resolveModelCallOptions(model, options = {}, credentialOptions) {
 	assertCloudCreditBudgetActive();
+	assertProviderUsage(model.provider, model.baseUrl);
 	if (model.provider === "xopc-cloud") options = withCloudUsageResponse(options);
 	const apiKey = options.apiKey ?? await resolveModelCallApiKey(model, credentialOptions);
 	if (!apiKey) throw new Error(`No API key for provider: ${model.provider}`);
@@ -45,7 +48,8 @@ async function resolveModelCallOptions(model, options = {}, credentialOptions) {
 /**
 * Complete a one-shot request with xopc credential resolution and extension-provider routing.
 */
-async function completeWithResolvedCredentials(model, context, options, credentialOptions, usageContext) {
+async function completeWithResolvedCredentialsInner(model, context, options, credentialOptions, usageContext) {
+	if (usageContext.trigger === "scheduled" || usageContext.trigger === "system") withModelUsageOrigin("background", () => assertProviderUsage(model.provider, model.baseUrl));
 	const resolvedOptions = await resolveModelCallOptions(model, options, credentialOptions);
 	const usageCall = startAiUsageCall(model, usageContext, {
 		context,
@@ -79,7 +83,8 @@ async function completeWithResolvedCredentials(model, context, options, credenti
 * Callers that need live visible output should consume the returned stream before calling
 * its `result()` method.
 */
-async function createResolvedModelStream(model, context, options, credentialOptions, usageContext) {
+async function createResolvedModelStreamInner(model, context, options, credentialOptions, usageContext) {
+	if (usageContext.trigger === "scheduled" || usageContext.trigger === "system") withModelUsageOrigin("background", () => assertProviderUsage(model.provider, model.baseUrl));
 	const resolvedOptions = await resolveModelCallOptions(model, options, credentialOptions);
 	const usageCall = startAiUsageCall(model, usageContext, {
 		context,
@@ -103,5 +108,11 @@ async function createResolvedModelStream(model, context, options, credentialOpti
 		throw error;
 	}
 }
+function completeWithResolvedCredentials(...args) {
+	return withModelUsageOrigin(modelUsageOriginForCall(args[4]), () => completeWithResolvedCredentialsInner(...args));
+}
+function createResolvedModelStream(...args) {
+	return withModelUsageOrigin(modelUsageOriginForCall(args[4]), () => createResolvedModelStreamInner(...args));
+}
 //#endregion
 export { completeWithResolvedCredentials, createResolvedModelStream, isLocalModelBaseUrl, resolveModelCallApiKey, resolveModelCallOptions };

package/dist/src/providers/model-reference-auditor.js

@@ -33,6 +33,7 @@ function collectModelPolicy(out, value, location) {
 		addRef(out, chat.primary, `${location}.chat.primary`);
 		if (Array.isArray(chat.fallbacks)) chat.fallbacks.forEach((ref, index) => addRef(out, ref, `${location}.chat.fallbacks[${index}]`));
 	}
+	collectToolModel(out, policy.background, `${location}.background`);
 	const intents = asRecord(policy.intents);
 	for (const [intent, routeValue] of Object.entries(intents ?? {})) {
 		const route = asRecord(routeValue);

package/dist/src/providers/model-response.js

@@ -46,7 +46,7 @@ function extractAssistantText(content) {
 /** True when retrying a model request may recover from a transport or upstream 5xx failure. */
 function isTransientProviderErrorMessage(message) {
 	const lower = message.toLowerCase();
-	if (/insufficient_quota|usage_limit_reached|usage_not_included|credit_budget_exhausted/.test(lower)) return false;
+	if (/provider_usage_scope_denied|insufficient_quota|usage_limit_reached|usage_not_included|credit_budget_exhausted/.test(lower)) return false;
 	return TRANSIENT_PROVIDER_ERROR_SUBSTRINGS.some((value) => lower.includes(value)) || lower.trim() === "terminated" || /(?:^|\D)(?:408|409|429|500|502|503|504|529)(?:\D|$)/.test(lower);
 }
 function stripCodeFences(raw) {

package/dist/src/providers/model-usage.d.ts

@@ -0,0 +1,15 @@
+import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+import type { AiUsageContext } from '../usage/types.js';
+export type ModelUsageOrigin = 'interactive' | 'background' | 'unknown';
+export declare const getModelUsageOrigin: () => ModelUsageOrigin;
+export declare function modelUsageOriginForCall(context: AiUsageContext): ModelUsageOrigin;
+/** A nested task cannot upgrade its parent's background/unknown scope. */
+export declare function withModelUsageOrigin<T>(origin: ModelUsageOrigin, run: () => T): T;
+export declare function modelUsageOriginFromTurn(origin?: TurnOrigin): ModelUsageOrigin;
+export declare class ProviderUsageScopeError extends Error {
+    readonly code = "provider_usage_scope_denied";
+    constructor(provider: string, origin: ModelUsageOrigin);
+}
+/** Transport wrappers may preserve only the error message or code. */
+export declare function isProviderUsageScopeError(error: unknown): boolean;
+export declare function assertProviderUsage(provider: string, baseUrl?: string): void;

package/dist/src/providers/model-usage.js

@@ -0,0 +1,50 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { init_profiles, isInteractiveOnlyProvider } from "./setup/profiles.js";
+import { init_scenario_registry, resolveAiUsageScenario } from "../usage/scenario-registry.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/providers/model-usage.ts
+function modelUsageOriginForCall(context) {
+	const trigger = context.trigger ?? resolveAiUsageScenario(context.operation).trigger;
+	return trigger === "user" ? "interactive" : trigger === "system" || trigger === "scheduled" ? "background" : getModelUsageOrigin();
+}
+/** A nested task cannot upgrade its parent's background/unknown scope. */
+function withModelUsageOrigin(origin, run) {
+	const parent = scopes.getStore();
+	const effective = parent === "background" || origin === "background" ? "background" : parent === "unknown" ? "unknown" : origin;
+	return scopes.run(effective, run);
+}
+function modelUsageOriginFromTurn(origin) {
+	if (!origin) return "unknown";
+	if (origin.type !== "system" || origin.source === "cli") return "interactive";
+	if ([
+		"workflow",
+		"internal",
+		"task_update"
+	].includes(origin.source)) return scopes.getStore() ?? "background";
+	return "background";
+}
+/** Transport wrappers may preserve only the error message or code. */
+function isProviderUsageScopeError(error) {
+	return error instanceof ProviderUsageScopeError || Boolean(error && typeof error === "object" && "code" in error && error.code === "provider_usage_scope_denied") || (error instanceof Error ? error.message : typeof error === "string" ? error : "").includes("provider_usage_scope_denied");
+}
+function assertProviderUsage(provider, baseUrl) {
+	const origin = getModelUsageOrigin();
+	if (origin !== "interactive" && isInteractiveOnlyProvider(provider, baseUrl)) throw new ProviderUsageScopeError(provider, origin);
+}
+var scopes, getModelUsageOrigin, ProviderUsageScopeError;
+var init_model_usage = __esmMin((() => {
+	init_profiles();
+	init_scenario_registry();
+	scopes = new AsyncLocalStorage();
+	getModelUsageOrigin = () => scopes.getStore() ?? "unknown";
+	ProviderUsageScopeError = class extends Error {
+		code = "provider_usage_scope_denied";
+		constructor(provider, origin) {
+			super(`provider_usage_scope_denied: ${provider} requires an interactive user turn; ${origin} calls need a background-capable model.`);
+			this.name = "ProviderUsageScopeError";
+		}
+	};
+}));
+//#endregion
+init_model_usage();
+export { ProviderUsageScopeError, assertProviderUsage, getModelUsageOrigin, init_model_usage, isProviderUsageScopeError, modelUsageOriginForCall, modelUsageOriginFromTurn, withModelUsageOrigin };

package/dist/src/providers/presentation.js

@@ -8,6 +8,7 @@ init_plugin_registry();
 init_model_policy();
 const FEATURED_PROVIDER_ORDER = [
 	"xopc-cloud",
+	"qwen-token-plan-cn",
 	"deepseek",
 	"openai",
 	"anthropic",
@@ -38,6 +39,7 @@ const FEATURED_PROVIDER_ORDER = [
 ];
 const PROVIDER_HINTS = {
 	"xopc-cloud": "Official XOPC model service with models discovered from your account.",
+	"qwen-token-plan-cn": "Alibaba Bailian subscription: one key for chat, vision and image generation.",
 	openai: "Frontier OpenAI models from the official API.",
 	anthropic: "Claude models for coding, long context, and reasoning.",
 	xai: "Grok models from xAI.",
@@ -76,6 +78,12 @@ const PROVIDER_HINTS = {
 };
 const RECOMMENDED_MODEL_PATTERNS = {
 	"xopc-cloud": [/^auto$/],
+	"qwen-token-plan-cn": [
+		/^qwen3\.8-flash$/i,
+		/^qwen3\.8-max$/i,
+		/^qwen3\.7-plus$/i,
+		/^qwen3\.6-flash$/i
+	],
 	openai: [
 		/^gpt-6-sol$/i,
 		/^gpt-6-luna$/i,

package/dist/src/providers/setup/engine.d.ts

@@ -0,0 +1,37 @@
+import type { ModelSetupPreview, ModelSetupRequest, ProviderSetupProfile } from '@xopcai/gateway-contract';
+import type { AgentDefaults } from '../../agent-config/index.js';
+import type { SetupVoiceState, SetupVoiceModel, VoiceSetupUse } from './voice.js';
+export type SetupModel = {
+    ref: string;
+    name: string;
+    baseUrl?: string;
+    api?: string;
+    vision?: boolean;
+    reasoning?: boolean;
+    recommended?: boolean;
+};
+export type SetupSnapshot = {
+    profile: ProviderSetupProfile;
+    defaults: AgentDefaults;
+    models: SetupModel[];
+    images: Array<{
+        ref: string;
+        name: string;
+    }>;
+    configured: boolean;
+    configuredProviders: Set<string>;
+    backgroundRestrictedModels?: Set<string>;
+    voice?: SetupVoiceState;
+};
+export declare class SetupConflictError extends Error {
+}
+/** Pure preview over authoritative catalog and defaults; never writes or probes a model. */
+export declare function previewProviderSetup(snapshot: SetupSnapshot, request?: ModelSetupRequest): ModelSetupPreview;
+export declare function applyProviderSetup(snapshot: SetupSnapshot, request: ModelSetupRequest, revision: string): {
+    defaults: AgentDefaults;
+    preview: ModelSetupPreview;
+    voiceAssignments: Array<{
+        use: VoiceSetupUse;
+        model: SetupVoiceModel;
+    }>;
+};

package/dist/src/providers/setup/engine.js

@@ -0,0 +1,177 @@
+import { init_profiles, isInteractiveOnlyProvider } from "./profiles.js";
+import { createHash } from "node:crypto";
+//#region src/providers/setup/engine.ts
+init_profiles();
+const preferred = {
+	"qwen-token-plan-cn": {
+		fast: [
+			"qwen3.8-flash",
+			"qwen3.7-plus",
+			"qwen3.6-flash"
+		],
+		reasoning: [
+			"qwen3.8-max",
+			"deepseek-v4-pro-0813",
+			"deepseek-v4-pro"
+		]
+	},
+	"xopc-cloud": {
+		fast: ["auto"],
+		reasoning: ["advanced", "auto"]
+	},
+	"xiaomi-token-plan-cn": {
+		fast: ["mimo-v2.5", "mimo-v2.5-pro"],
+		reasoning: ["mimo-v2.5-pro", "mimo-v2.5"]
+	}
+};
+const uses = [
+	"chat",
+	"vision",
+	"image",
+	"background"
+];
+var SetupConflictError = class extends Error {};
+function choose(models, ids, provider) {
+	return ids.map((id) => models.find((model) => model.ref === `${provider}/${id}`)?.ref).find(Boolean) ?? models.find((model) => model.recommended)?.ref ?? (models.length === 1 ? models[0]?.ref : void 0);
+}
+/** Pure preview over authoritative catalog and defaults; never writes or probes a model. */
+function previewProviderSetup(snapshot, request = {}) {
+	const { profile, defaults, configured, configuredProviders } = snapshot;
+	const models = snapshot.models.filter((model) => !request.modelIds || request.modelIds.some((id) => model.ref === id || model.ref === `${profile.id}/${id}`));
+	const vision = models.filter((model) => model.vision);
+	const reasoning = models.filter((model) => model.reasoning);
+	const preference = preferred[profile.id] ?? {
+		fast: [],
+		reasoning: []
+	};
+	const fast = choose(models, preference.fast, profile.id);
+	const complex = choose(reasoning, preference.reasoning, profile.id);
+	const isRestricted = (ref) => snapshot.backgroundRestrictedModels?.has(ref) || isInteractiveOnlyProvider(ref.split("/")[0], snapshot.models.find((model) => model.ref === ref)?.baseUrl);
+	const background = profile.interactiveOnly ? [] : models.filter((model) => !isRestricted(model.ref));
+	const recommended = {
+		chat: fast,
+		vision: choose(vision, preference.fast, profile.id),
+		image: snapshot.images[0]?.ref,
+		background: choose(background, preference.fast, profile.id)
+	};
+	const choices = {
+		chat: models,
+		vision,
+		image: snapshot.images,
+		background
+	};
+	const current = {
+		chat: defaults.models.chat.primary,
+		vision: defaults.models.imageUnderstanding?.primary,
+		image: defaults.models.imageGeneration?.primary,
+		background: defaults.models.background?.primary ?? (!isRestricted(defaults.models.chat.primary) ? defaults.models.chat.primary : void 0)
+	};
+	for (const id of Object.keys(snapshot.voice?.choices ?? {})) {
+		const options = snapshot.voice.choices[id];
+		choices[id] = options;
+		recommended[id] = options.find((model) => model.recommended)?.ref ?? (options.length === 1 ? options[0]?.ref : void 0);
+		current[id] = snapshot.voice.current[id];
+	}
+	const revision = createHash("sha256").update(JSON.stringify({
+		defaults,
+		profile,
+		models: snapshot.models,
+		images: snapshot.images,
+		voice: snapshot.voice,
+		backgroundRestrictedModels: [...snapshot.backgroundRestrictedModels ?? []].sort()
+	})).digest("hex");
+	return {
+		providerId: profile.id,
+		profile,
+		revision,
+		configured,
+		mode: request.mode ?? "fill",
+		taskModels: {
+			...fast ? { fast } : {},
+			...complex ? {
+				reasoning: complex,
+				coding: complex,
+				review: complex
+			} : {},
+			...recommended.vision ? { vision: recommended.vision } : {}
+		},
+		uses: [...uses, ...snapshot.voice ? [
+			"transcription",
+			"speech",
+			"conversation"
+		] : []].map((id) => {
+			const options = (choices[id] ?? []).map((model) => ({
+				id: model.ref,
+				name: model.name
+			}));
+			const override = request.overrides?.[id];
+			if (override && !options.some((model) => model.id === override)) throw new Error(`Invalid ${id} model for ${profile.id}`);
+			const ref = override ?? recommended[id];
+			const currentProvider = current[id]?.split("/")[0];
+			const currentConfigured = currentProvider && (configuredProviders.has(currentProvider) || [
+				"speech",
+				"transcription",
+				"conversation"
+			].includes(id)) && (id !== "background" || !isRestricted(current[id]));
+			const selected = options.length > 0 && Boolean(ref) && (request.selected ? request.selected.includes(id) : request.mode === "replace" || !currentConfigured);
+			return {
+				id,
+				current: current[id],
+				recommended: ref,
+				choices: options,
+				selected,
+				...!options.length ? { reason: id === "background" && profile.interactiveOnly ? "interactive_only" : "not_supported" } : !ref ? { reason: "no_recommendation" } : {}
+			};
+		})
+	};
+}
+function applyProviderSetup(snapshot, request, revision) {
+	const preview = previewProviderSetup(snapshot, request);
+	if (revision !== preview.revision) throw new SetupConflictError("Model catalog or settings changed. Review the refreshed configuration.");
+	for (const id of request.selected ?? []) if (!preview.uses.some((use) => use.id === id && use.selected)) throw new Error(`No eligible model selected for ${id}`);
+	if (!snapshot.configured) throw new Error("Connect this model service before applying its models.");
+	const models = structuredClone(snapshot.defaults.models);
+	const voiceAssignments = [];
+	const route = (primary) => ({
+		primary,
+		fallbacks: []
+	});
+	for (const use of preview.uses) {
+		if (!use.selected) continue;
+		if (!use.recommended) throw new Error(`Choose a model for ${use.id}`);
+		if (use.id === "chat") {
+			models.chat = route(use.recommended);
+			for (const [intent, ref] of Object.entries(preview.taskModels)) {
+				const key = intent;
+				const existing = models.intents[key];
+				const keep = request.mode !== "replace" && existing && snapshot.configuredProviders.has(existing.primary.split("/")[0]);
+				if (ref && !keep && (intent !== "vision" || preview.uses.some((use) => use.id === "vision" && use.selected))) models.intents[key] = route(ref);
+			}
+		} else if (use.id === "vision") models.imageUnderstanding = route(use.recommended);
+		else if (use.id === "image") models.imageGeneration = {
+			...models.imageGeneration,
+			...route(use.recommended),
+			autoProviderFallback: false
+		};
+		else if (use.id === "background") models.background = route(use.recommended);
+		else {
+			const voiceUse = use.id;
+			const model = snapshot.voice?.choices[voiceUse].find((model) => model.ref === use.recommended);
+			if (!model) throw new Error(`No voice binding for ${use.id}`);
+			voiceAssignments.push({
+				use: voiceUse,
+				model
+			});
+		}
+	}
+	return {
+		defaults: {
+			...snapshot.defaults,
+			models
+		},
+		preview,
+		voiceAssignments
+	};
+}
+//#endregion
+export { SetupConflictError, applyProviderSetup, previewProviderSetup };

package/dist/src/providers/setup/profiles.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderSetupProfile } from '@xopcai/gateway-contract';
+/** Plan usage is conservative until a vendor explicitly permits unattended execution. */
+export declare function isInteractiveOnlyProvider(provider: string, baseUrl?: string): boolean;
+export declare function getProviderSetupProfile(provider: string, name?: string, oauth?: boolean, baseUrl?: string): ProviderSetupProfile;