@xopcai/xopc 0.0.389 → 0.0.391

package/dist/src/gateway/hono/routes/status.js

@@ -3,6 +3,7 @@ import { isSTTAvailable } from "../../../voice/stt/availability.js";
 import { mergeSttConfigFromAppConfig } from "../../../voice/stt/config.js";
 import "../../../voice/stt/index.js";
 import { getGatewayAgentEffectiveConfig } from "../../agents-admin.js";
+import { resolveDictationRoute } from "../../../voice/dictation.js";
 import { createHash } from "node:crypto";
 //#region src/gateway/hono/routes/status.ts
 init_providers();
@@ -82,6 +83,7 @@ function buildStatusPayload(service) {
 			sttAvailable: sttConfig ? isSTTAvailable(sttConfig) : false,
 			sttEnabled: sttConfig?.enabled === true,
 			sttProvider: sttConfig?.provider ?? null,
+			dictation: config ? resolveDictationRoute(config) : { mode: "unavailable" },
 			refineAvailable: isRefineAvailable(config)
 		}
 	};

package/dist/src/gateway/hono/routes/voice.js

@@ -1,3 +1,4 @@
+import { init_model_usage, withModelUsageOrigin } from "../../../providers/model-usage.js";
 import { voiceSelectionSchema } from "../../../../packages/realtime-protocol/src/voice-catalog.js";
 import { VOICE_TIMING_METRICS, createVoiceSessionRequestSchema, init_voice } from "../../../../packages/realtime-protocol/src/voice.js";
 import { getDefaultModelSync, init_providers, resolveModel } from "../../../providers/index.js";
@@ -5,6 +6,7 @@ import { completeWithResolvedCredentials } from "../../../providers/model-call.j
 import { isPersonalConversation } from "../../../personal-agent/repository.js";
 import { PlatformVoiceError } from "../../../voice/platform-streams.js";
 import { resolveSttProviderConfigSlice } from "../../../voice/stt/config-slice.js";
+import { resolveSTTProviderChain } from "../../../voice/stt/factory.js";
 import { STTTranscriptionError, transcribe } from "../../../voice/stt/transcribe-core.js";
 import { isSTTAvailable } from "../../../voice/stt/availability.js";
 import { mergeSttConfigFromAppConfig } from "../../../voice/stt/config.js";
@@ -21,10 +23,11 @@ import { resolveOmniRoute } from "../../../voice/realtime/omniRoute.js";
 import { VoiceSessionCreationError, resolveStreamingStt, resolveStreamingTts } from "../../../voice/realtime/runtime.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { createGatewayRouteLogger } from "../lib/route-logger.js";
-import { selectPlatformVoice, voiceSettingsCatalog } from "../../../voice/platform-settings.js";
 import { listTtsProvidersForApi } from "../../../voice/tts/list-providers.js";
+import { selectPlatformVoice, voiceSettingsCatalog } from "../../../voice/platform-settings.js";
 import { z } from "zod";
 //#region src/gateway/hono/routes/voice.ts
+init_model_usage();
 init_voice();
 init_providers();
 const log = createGatewayRouteLogger("Voice");
@@ -104,7 +107,10 @@ async function refineTranscript(raw, config, signal) {
 			maxTokens: Math.min(raw.length * 3, 4096),
 			temperature: .2,
 			signal: mergedSignal
-		}, void 0, { operation: "voice.select" });
+		}, void 0, {
+			operation: "voice.select",
+			trigger: "user"
+		});
 		let out = "";
 		if (Array.isArray(result.content)) {
 			for (const c of result.content) if (c && typeof c === "object" && c.type === "text") out += String(c.text || "");
@@ -246,12 +252,13 @@ function registerVoiceRoutes(authenticated, deps) {
 		let result;
 		let reader;
 		try {
-			result = await speakStream(config.voice?.language === "en" ? "Hello, I am your assistant. You can talk to me naturally." : "你好，我是你的助手。现在可以和我自然对话了。", previewConfig, {
+			const text = config.voice?.language === "en" ? "Hello, I am your assistant. You can talk to me naturally." : "你好，我是你的助手。现在可以和我自然对话了。";
+			result = await withModelUsageOrigin("interactive", () => speakStream(text, previewConfig, {
 				signal,
 				appConfig: config,
 				allowFallback: false,
 				parseDirectives: false
-			});
+			}));
 			if (result.outputFormat !== "pcm") throw new Error("Realtime preview requires PCM audio");
 			reader = result.audioStream.getReader();
 			const chunks = [];
@@ -551,12 +558,12 @@ function registerVoiceRoutes(authenticated, deps) {
 			error: { message: `TTS provider \"${provider}\" is not configured.` }
 		}, 503);
 		try {
-			const result = await speak(text, ttsConfig, {
+			const result = await withModelUsageOrigin("interactive", () => speak(text, ttsConfig, {
 				appConfig: config,
 				parseDirectives: false,
 				signal: c.req.raw.signal,
 				tts: voice ? { voice } : void 0
-			});
+			}));
 			if (!result.audio.length) throw new Error(`TTS provider \"${result.provider}\" returned empty audio`);
 			return new Response(new Uint8Array(result.audio), { headers: {
 				"Content-Type": speechMimeType(result.format),
@@ -630,14 +637,14 @@ function registerVoiceRoutes(authenticated, deps) {
 		}, 503);
 		try {
 			const startedAt = Date.now();
-			const result = await speak(text, ttsConfig, {
+			const result = await withModelUsageOrigin("interactive", () => speak(text, ttsConfig, {
 				appConfig: config,
 				parseDirectives: false,
 				tts: {
 					...typeof body.model === "string" && body.model.trim() ? { model: body.model.trim() } : {},
 					...typeof body.voice === "string" && body.voice.trim() ? { voice: body.voice.trim() } : {}
 				}
-			});
+			}));
 			if (!result.audio.length) throw new Error(`TTS provider "${result.provider}" returned empty audio`);
 			const mimeType = result.format === "opus" || result.format === "ogg" ? "audio/ogg" : result.format === "mp3" || result.format === "mpeg" ? "audio/mpeg" : result.format === "wav" ? "audio/wav" : `audio/${result.format}`;
 			return c.json({
@@ -678,18 +685,22 @@ function registerVoiceRoutes(authenticated, deps) {
 		}, 400);
 		const config = service.currentConfig;
 		const sttConfig = mergeSttConfigFromAppConfig(config.tools?.media?.audio, config.tools?.media);
+		if (input.expectedProvider && input.expectedProvider !== resolveSTTProviderChain(sttConfig)[0]?.id) return c.json({
+			ok: false,
+			error: { message: "Speech recognition provider changed during recording. Restore the previous model or start a new recording." }
+		}, 409);
 		if (!isSTTAvailable(sttConfig)) return c.json({
 			ok: false,
 			error: { message: "STT is not configured. Enable STT in gateway config (tools.media.audio)." }
 		}, 503);
 		const startedAt = Date.now();
 		try {
-			const result = await transcribe(input.audioBuffer, sttConfig, {
+			const result = await withModelUsageOrigin("interactive", () => transcribe(input.audioBuffer, sttConfig, {
 				language: input.language,
 				mime: input.mimeType,
 				fileName: input.fileName,
 				signal: c.req.raw.signal
-			});
+			}));
 			const detectedLanguage = result.language ?? input.language;
 			const refinementAvailable = (config.voice?.input?.refinement?.mode ?? "off") !== "off";
 			return c.json({
@@ -769,12 +780,14 @@ function registerVoiceRoutes(authenticated, deps) {
 			error: { message: "Missing required file field: audio" }
 		}, 400);
 		const languageValue = form.get("language");
+		const expectedProvider = form.get("expectedProvider");
 		const language = typeof languageValue === "string" && languageValue.trim() ? languageValue.trim() : void 0;
 		const fileName = "name" in audio && typeof audio.name === "string" && audio.name.trim() ? audio.name.trim() : `audio-${Date.now()}`;
 		return runTranscription(c, {
 			audioBuffer: Buffer.from(await audio.arrayBuffer()),
 			mimeType: audio.type || "audio/webm",
 			fileName,
+			...typeof expectedProvider === "string" && expectedProvider ? { expectedProvider } : {},
 			...language ? { language } : {}
 		});
 	});

package/dist/src/gateway/provider-model-setup.d.ts

@@ -0,0 +1,4 @@
+import type { SetupSnapshot } from '../providers/setup/engine.js';
+import type { Config } from '../config/schema.js';
+export declare function loadProviderSetupSnapshot(provider: string, config?: Config): Promise<SetupSnapshot>;
+export declare function readProviderSetupSnapshot(provider: string, configured: boolean, config?: Config): SetupSnapshot;

package/dist/src/gateway/provider-model-setup.js

@@ -0,0 +1,56 @@
+import { getProviderSetupProfile, init_profiles, isInteractiveOnlyProvider } from "../providers/setup/profiles.js";
+import { getModelCatalogStore, init_model_catalog_store } from "../providers/model-catalog-store.js";
+import { getAllModels, getAllProviders, getModelsByProvider, getProviderDisplayName, init_providers, isProviderConfigured, isProviderConfiguredSync, providerSupportsOAuth } from "../providers/index.js";
+import { getImageGenerationProvider } from "../agent/image/generation/provider-registry.js";
+import { listSttProvidersForApi } from "../voice/stt/list-providers.js";
+import { listGlobalDefaults } from "./global-defaults-admin.js";
+import { getRecommendedModelsForProvider } from "../providers/presentation.js";
+import { listTtsProvidersForApi } from "../voice/tts/list-providers.js";
+import { readSetupVoiceState } from "../providers/setup/voice.js";
+//#region src/gateway/provider-model-setup.ts
+init_providers();
+init_model_catalog_store();
+init_profiles();
+async function loadProviderSetupSnapshot(provider, config) {
+	const languageProvider = getAllProviders().includes(provider);
+	const mediaProvider = getImageGenerationProvider(provider) || listSttProvidersForApi(config).providers.some((entry) => entry.id === provider) || listTtsProvidersForApi(config).providers.some((entry) => entry.id === provider);
+	if (!languageProvider && !mediaProvider) throw new Error(`Unknown model provider: ${provider}`);
+	return readProviderSetupSnapshot(provider, languageProvider && await isProviderConfigured(provider), config);
+}
+function readProviderSetupSnapshot(provider, configured, config) {
+	const languageProvider = getAllProviders().includes(provider);
+	const models = (languageProvider ? getModelsByProvider(provider) : []).filter((model) => !("computerUse" in model && model.computerUse));
+	const recommended = new Set((languageProvider ? getRecommendedModelsForProvider(provider) : []).map((model) => model.ref));
+	const source = getModelCatalogStore().getSource(provider);
+	const image = getImageGenerationProvider(provider);
+	const images = image?.models.filter((id) => provider !== "xopc-cloud" || source?.models.some((model) => model.id === id && model.availability === "available")) ?? [];
+	const configuredProviders = new Set(getAllProviders().filter(isProviderConfiguredSync));
+	const backgroundRestrictedModels = new Set(getAllModels().filter((model) => isInteractiveOnlyProvider(model.provider, model.baseUrl)).map((model) => `${model.provider}/${model.id}`));
+	for (const model of models) if (/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(?=[:/]|$)/.test(model.baseUrl)) configuredProviders.add(provider);
+	const voice = config ? readSetupVoiceState(provider, config) : void 0;
+	const imageConfigured = image?.isConfigured({ cfg: config }) ?? false;
+	const nativeVoiceConfigured = Boolean(!["qwen-token-plan-cn", "xopc-cloud"].includes(provider) && voice && Object.values(voice.choices).some((choices) => choices.length));
+	return {
+		...config ? { voice } : {},
+		configured: configured || configuredProviders.has(provider) || imageConfigured || nativeVoiceConfigured,
+		configuredProviders,
+		backgroundRestrictedModels,
+		defaults: listGlobalDefaults().defaults,
+		profile: getProviderSetupProfile(provider, getProviderDisplayName(provider), providerSupportsOAuth(provider), models[0]?.baseUrl),
+		models: (!configured && !configuredProviders.has(provider) && (nativeVoiceConfigured || imageConfigured) ? [] : models).map((model) => ({
+			ref: `${provider}/${model.id}`,
+			name: model.name,
+			vision: model.input.includes("image"),
+			reasoning: model.reasoning,
+			baseUrl: model.baseUrl,
+			api: model.api,
+			recommended: recommended.has(`${provider}/${model.id}`)
+		})),
+		images: (nativeVoiceConfigured && !imageConfigured && !configured ? [] : images).map((id) => ({
+			ref: `${provider}/${id}`,
+			name: id
+		}))
+	};
+}
+//#endregion
+export { loadProviderSetupSnapshot, readProviderSetupSnapshot };

package/dist/src/gateway/service/config-coordinator.d.ts

@@ -612,12 +612,12 @@ export declare class GatewayConfigCoordinator {
                     model: string;
                 };
                 tts?: {
-                    provider: "alibaba" | "xopc-cloud";
+                    provider: "xopc-cloud" | "alibaba";
                     model?: string;
                     voice?: string;
                 };
                 omni?: {
-                    provider: "alibaba" | "xopc-cloud";
+                    provider: "qwen-token-plan-cn" | "xopc-cloud" | "alibaba";
                     model: string;
                     voice: string;
                     instructions: string;

package/dist/src/gateway/service.js

@@ -156,6 +156,7 @@ import { GatewayReadiness } from "./startup-readiness.js";
 import { createGatewayStartupTrace } from "./startup-trace.js";
 import { GatewaySceneHost } from "./scenes/host.js";
 import { TaskCollaborationDelivery } from "../tasks/task-collaboration-delivery.js";
+import { TaskMainUpdateExhaustedError } from "../tasks/task-main-update-retry.js";
 import { TaskMainUpdateDelivery } from "../tasks/task-main-update-delivery.js";
 import { allowsPersonalTaskNotification, personalReplyNotification, personalRunDelegated } from "../personal-agent/notifications.js";
 import { TaskMainUpdateDecisionService } from "../tasks/task-main-update-decision-service.js";
@@ -879,6 +880,7 @@ var GatewayService = class {
 				if (this.voiceRealtime.hasConversation(input.conversationId)) {
 					const attempt = selectTaskMainUpdateAttempt(input.conversationId, input.clientMessageId, findSessionInput);
 					if (attempt.kind === "completed") return Promise.resolve(true);
+					if (attempt.kind === "exhausted") throw new TaskMainUpdateExhaustedError();
 					if (attempt.kind !== "new" || !attempt.clientMessageId) return Promise.resolve(false);
 					return this.voiceRealtime.offerTaskUpdate({
 						...input,

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,