@xopcai/xopc 0.0.388 → 0.0.390

package/dist/src/projects/project-service.js

@@ -2,12 +2,12 @@ import { init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/t
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
 import { changedFieldsFromPatch, emitActivity, systemActivityActor, systemActivitySource } from "../activity/emitter.js";
+import { ExecutionEnvironmentStore } from "../execution-environments/store.js";
 import { ProjectStore } from "./project-store.js";
 import { enqueueProjectChanged } from "./project-change-events.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError, canonicalWorkspacePath, inferProjectNameFromWorkspaceRoot, isPathSameOrInsideWorkspace, isSafeAutoCreateWorkspaceRoot, resolveWorkspaceProjectRoot, workspaceDirectoryExists } from "./workspace-project.js";
 import { drainProjectWorkspaceCreation, queueProjectWorkspaceCreation } from "./project-workspace-creation.js";
 import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
-import { ExecutionEnvironmentStore } from "../execution-environments/store.js";
 import { listPendingProjectUnderstandingRuns } from "../work-discovery/repository.js";
 import { inferProjectExecutionMode } from "./project-kind.js";
 import { bindSessionToProject, listProjectConversationIds, unbindSessionFromProject } from "./session-bind.js";

package/dist/src/projects/project-skill-service.js

@@ -1,8 +1,8 @@
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
-import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "../agent/skills/workspace-skills-dir.js";
-import { loadSkills, loadWorkspaceSkillInventory } from "../agent/skills/index.js";
 import { removeSkillsLockEntry } from "../agent/skills/hub-lock.js";
 import { deleteManagedSkill, installSkillFromZip, isValidSkillId } from "../agent/skills/managed-store.js";
+import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "../agent/skills/workspace-skills-dir.js";
+import { loadSkills, loadWorkspaceSkillInventory } from "../agent/skills/index.js";
 import { pullSkillFromSource } from "../agent/skills/hub-pull.js";
 import { downloadFromMarketplace } from "../agent/skills/skills-marketplace.js";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";

package/dist/src/projects/workspace.js

@@ -1,9 +1,9 @@
 import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
-import { ProjectStore } from "./project-store.js";
 import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { projectWorkspacePath } from "../session/session-workspace.js";
+import { ProjectStore } from "./project-store.js";
 //#region src/projects/workspace.ts
 init_sqlite();
 function resolveProjectWorkspacePath(config, conversationId, project) {

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

@@ -2,8 +2,8 @@ import { AgentCatalogRepository, init_repository } from "../agent-catalog/reposi
 import { init_model_policy, isComputerModel, isDedicatedComputerProfile } from "../computer/model-policy.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { getModelRegistry, init_model_registry } from "./model-registry.js";
-import { getImageGenerationProvider } from "../agent/image/generation/provider-registry.js";
 import { parseImageGenerationModelRef } from "../agent/image/generation/model-ref.js";
+import { getImageGenerationProvider } from "../agent/image/generation/provider-registry.js";
 //#region src/providers/model-reference-auditor.ts
 init_repository();
 init_model_policy();
@@ -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-registry.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { resolveModelsJsonPath } from "../config/paths.js";
 import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
+import { resolveModelsJsonPath } from "../config/paths.js";
 import { init_provider_policy, isRetiredModelProvider } from "./provider-policy.js";
 import { getDefaultModelValues, init_models_json, validateModelsConfig } from "../config/models-json.js";
 import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";

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;

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

@@ -0,0 +1,94 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+//#region src/providers/setup/profiles.ts
+/** Plan usage is conservative until a vendor explicitly permits unattended execution. */
+function isInteractiveOnlyProvider(provider, baseUrl) {
+	if (subscriptionProviders.has(provider?.trim().toLowerCase())) return true;
+	if (!baseUrl) return false;
+	try {
+		const url = new URL(baseUrl);
+		const hostname = url.hostname.toLowerCase().replace(/\.$/, "");
+		return [
+			"token-plan.cn-beijing.maas.aliyuncs.com",
+			"token-plan.ap-southeast-1.maas.aliyuncs.com",
+			"token-plan-cn.xiaomimimo.com",
+			"token-plan-ams.xiaomimimo.com",
+			"token-plan-sgp.xiaomimimo.com",
+			"coding.dashscope.aliyuncs.com",
+			"coding-intl.dashscope.aliyuncs.com"
+		].includes(hostname) || ["ark.cn-beijing.volces.com", "ark.ap-southeast.bytepluses.com"].includes(hostname) && decodeURIComponent(url.pathname).startsWith("/api/coding/");
+	} catch {
+		return false;
+	}
+}
+function getProviderSetupProfile(provider, name = provider, oauth = false, baseUrl) {
+	if (profiles[provider]) return {
+		id: provider,
+		...profiles[provider]
+	};
+	const interactiveOnly = isInteractiveOnlyProvider(provider, baseUrl);
+	const local = Boolean(baseUrl && /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(?=[:/]|$)/.test(baseUrl));
+	return {
+		id: provider,
+		brand: {
+			"dashscope-cn": "Alibaba Bailian",
+			"dashscope-intl": "Alibaba Bailian",
+			"qwen-token-plan": "Alibaba Bailian",
+			"qwen-token-plan-individual": "Alibaba Bailian",
+			xiaomi: "Xiaomi MiMo",
+			"xiaomi-token-plan-ams": "Xiaomi MiMo",
+			"xiaomi-token-plan-sgp": "Xiaomi MiMo"
+		}[provider] ?? name,
+		name,
+		access: interactiveOnly ? "subscription" : local ? "local" : "api",
+		credential: oauth ? "oauth" : local ? "none" : "api-key",
+		interactiveOnly
+	};
+}
+var subscriptionProviders, profiles;
+var init_profiles = __esmMin((() => {
+	subscriptionProviders = new Set([
+		"qwen-token-plan-cn",
+		"qwen-token-plan",
+		"qwen-token-plan-individual",
+		"xiaomi-token-plan-cn",
+		"xiaomi-token-plan-ams",
+		"xiaomi-token-plan-sgp",
+		"zai-coding-cn",
+		"zai-coding-global",
+		"zhipu-coding-cn",
+		"kimi-coding",
+		"volcengine-plan",
+		"byteplus-plan",
+		"stepfun-plan",
+		"stepfun-plan-cn",
+		"stepfun-plan-intl"
+	]);
+	profiles = {
+		"qwen-token-plan-cn": {
+			brand: "Alibaba Bailian",
+			name: "Bailian subscription · Beijing",
+			access: "subscription",
+			credential: "api-key",
+			interactiveOnly: true,
+			apiKeyUrl: "https://bailian.console.aliyun.com/cn-beijing/subscription/overview"
+		},
+		"xopc-cloud": {
+			brand: "XOPC Cloud",
+			name: "XOPC Cloud",
+			access: "account",
+			credential: "oauth",
+			interactiveOnly: false
+		},
+		"xiaomi-token-plan-cn": {
+			brand: "Xiaomi MiMo",
+			name: "MiMo Token Plan · China",
+			access: "subscription",
+			credential: "api-key",
+			interactiveOnly: true,
+			apiKeyUrl: "https://platform.xiaomimimo.com/"
+		}
+	};
+}));
+//#endregion
+init_profiles();
+export { getProviderSetupProfile, init_profiles, isInteractiveOnlyProvider };

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

@@ -0,0 +1,23 @@
+import type { ModelSetupUse } from '@xopcai/gateway-contract';
+import { type Config } from '../../config/schema.js';
+export type VoiceSetupUse = Extract<ModelSetupUse, 'speech' | 'transcription' | 'conversation'>;
+export type SetupVoiceModel = {
+    ref: string;
+    name: string;
+    provider: string;
+    model: string;
+    voice?: string;
+    recommended?: boolean;
+};
+export type SetupVoiceState = {
+    revision: string;
+    current: Partial<Record<VoiceSetupUse, string>>;
+    choices: Record<VoiceSetupUse, SetupVoiceModel[]>;
+};
+export declare const voiceSetupUses: VoiceSetupUse[];
+export declare function readSetupVoiceState(provider: string, config: Config): SetupVoiceState;
+/** Voice lives in the existing app configuration; never copy the provider secret. */
+export declare function applySetupVoice(config: Config, assignments: Array<{
+    use: VoiceSetupUse;
+    model: SetupVoiceModel;
+}>): Config;