@xopcai/xopc 0.0.371 → 0.0.373

package/dist/src/storage/sqlite/ai-usage-repository.js

@@ -1,5 +1,8 @@
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
+import { creditMicroSchema } from "../../../packages/gateway-contract/src/cloud-credits.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
 //#region src/storage/sqlite/ai-usage-repository.ts
+init_src();
 init_transaction();
 const ERROR_SUMMARY_LIMIT = 512;
 const AI_USAGE_RETENTION_MS = 4320 * 60 * 60 * 1e3;
@@ -43,6 +46,41 @@ function pruneAiUsageEvents(cutoffMs) {
 function getAiUsageEvent(id) {
 	return getSqliteDatabase().prepare("SELECT * FROM ai_usage_events WHERE id = ?").get(id);
 }
+function setAiUsageCloudRequest(id, requestId) {
+	if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(requestId)) return;
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE ai_usage_events SET cloud_request_id = ?, updated_at = ?
+      WHERE id = ? AND provider = 'xopc-cloud' AND cloud_billing_json IS NULL`).run(requestId, Date.now(), id);
+	});
+}
+function setAiUsageCloudReceipt(id, receipt) {
+	if (![
+		"settled",
+		"released",
+		"expired",
+		"reserved",
+		"pending"
+	].includes(receipt.state)) return;
+	const state = receipt.state === "settled" ? "settled" : ["released", "expired"].includes(receipt.state) ? "released" : "pending";
+	const charged = state === "settled" ? receipt.chargedCreditMicro : state === "released" ? "0" : null;
+	if (state === "settled" && charged === null) return;
+	creditMicroSchema.parse(receipt.reservedCreditMicro);
+	creditMicroSchema.parse(receipt.releasedCreditMicro);
+	if (charged !== null) creditMicroSchema.parse(charged);
+	const billing = {
+		source: "xopc_cloud",
+		state,
+		requestId: receipt.requestId,
+		reservedCreditMicro: state === "pending" ? receipt.reservedCreditMicro : "0",
+		chargedCreditMicro: charged,
+		releasedCreditMicro: receipt.releasedCreditMicro
+	};
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE ai_usage_events SET cloud_billing_json = ?, updated_at = ?
+      WHERE id = ? AND provider = 'xopc-cloud' AND cloud_request_id = ?
+      AND COALESCE(json_extract(cloud_billing_json, '$.state'), '') NOT IN ('settled', 'released')`).run(JSON.stringify(billing), Date.now(), id, receipt.requestId);
+	});
+}
 function queryWhere(query) {
 	const clauses = ["started_at >= ?", "started_at < ?"];
 	const values = [query.from, query.to];
@@ -64,6 +102,18 @@ function queryWhere(query) {
 		values
 	};
 }
+function pendingAiUsageCloudReceiptIds(query) {
+	const { sql, values } = queryWhere(query);
+	return getSqliteDatabase().prepare(`SELECT id FROM ai_usage_events WHERE ${sql}
+    AND provider = 'xopc-cloud' AND cloud_request_id IS NOT NULL
+    AND COALESCE(json_extract(cloud_billing_json, '$.state'), '') NOT IN ('settled', 'released')
+    ORDER BY updated_at ASC, id ASC LIMIT 4`).all(...values).map((row) => row.id);
+}
+function markAiUsageCloudReceiptAttempt(id) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE ai_usage_events SET updated_at = ? WHERE id = ? AND provider = 'xopc-cloud'`).run(Date.now(), id);
+	});
+}
 function usd(microusd) {
 	return (microusd / 1e6).toFixed(6).replace(/0+$/, "").replace(/\.$/, "") || "0";
 }
@@ -81,19 +131,44 @@ function totalsFromRow(row) {
 		cacheWriteTokens: Number(row.cache_write_tokens ?? 0),
 		totalTokens: Number(row.total_tokens ?? 0),
 		knownCostUsd: usd(Number(row.known_cost_microusd ?? 0)),
-		costCompleteness: calls === 0 || unknownCostCalls === calls ? "unknown" : unknownCostCalls > 0 ? "partial" : "complete"
+		costCompleteness: Number(row.external_calls ?? 0) === 0 || unknownCostCalls === Number(row.external_calls) ? "unknown" : unknownCostCalls > 0 ? "partial" : "complete",
+		billing: {
+			external: {
+				calls: Number(row.external_calls ?? 0),
+				estimatedCostUsd: usd(Number(row.known_cost_microusd ?? 0)),
+				unknownCostCalls
+			},
+			localCalls: Number(row.local_calls ?? 0),
+			cloud: {
+				calls: Number(row.cloud_calls ?? 0),
+				settledCalls: Number(row.cloud_final_calls ?? 0),
+				pendingCalls: Number(row.cloud_pending_calls ?? 0),
+				unavailableCalls: Number(row.cloud_unavailable_calls ?? 0),
+				chargedCreditMicro: Number(row.cloud_final_calls ?? 0) > 0 ? String(row.cloud_charged_micro ?? "0") : null,
+				reservedCreditMicro: Number(row.cloud_known_reservations ?? 0) > 0 ? String(row.cloud_reserved_micro ?? "0") : null
+			}
+		}
 	};
 }
 const TOTALS_SQL = `COUNT(*) AS calls,
   SUM(CASE WHEN status = 'succeeded' THEN 1 ELSE 0 END) AS succeeded_calls,
   SUM(CASE WHEN status IN ('failed', 'aborted', 'unknown') THEN 1 ELSE 0 END) AS failed_calls,
-  SUM(CASE WHEN cost_source <> 'local' AND estimated_cost_microusd IS NULL THEN 1 ELSE 0 END) AS unknown_cost_calls,
+  SUM(CASE WHEN provider <> 'xopc-cloud' AND cost_source <> 'local' AND estimated_cost_microusd IS NULL THEN 1 ELSE 0 END) AS unknown_cost_calls,
+  SUM(CASE WHEN provider <> 'xopc-cloud' AND cost_source <> 'local' THEN 1 ELSE 0 END) AS external_calls,
+  SUM(CASE WHEN provider <> 'xopc-cloud' AND cost_source = 'local' THEN 1 ELSE 0 END) AS local_calls,
+  SUM(CASE WHEN provider = 'xopc-cloud' THEN 1 ELSE 0 END) AS cloud_calls,
+  SUM(CASE WHEN provider = 'xopc-cloud' AND json_extract(cloud_billing_json, '$.state') IN ('settled', 'released') THEN 1 ELSE 0 END) AS cloud_final_calls,
+  SUM(CASE WHEN provider = 'xopc-cloud' AND json_extract(cloud_billing_json, '$.state') = 'pending' THEN 1 ELSE 0 END) AS cloud_pending_calls,
+  SUM(CASE WHEN provider = 'xopc-cloud' AND cloud_billing_json IS NULL THEN 1 ELSE 0 END) AS cloud_unavailable_calls,
+  SUM(CASE WHEN provider = 'xopc-cloud' AND cloud_billing_json IS NOT NULL THEN 1 ELSE 0 END) AS cloud_known_reservations,
+  CAST(COALESCE(SUM(CASE WHEN provider = 'xopc-cloud' THEN CAST(json_extract(cloud_billing_json, '$.chargedCreditMicro') AS INTEGER) ELSE 0 END), 0) AS TEXT) AS cloud_charged_micro,
+  CAST(COALESCE(SUM(CASE WHEN provider = 'xopc-cloud' THEN CAST(json_extract(cloud_billing_json, '$.reservedCreditMicro') AS INTEGER) ELSE 0 END), 0) AS TEXT) AS cloud_reserved_micro,
   COALESCE(SUM(input_tokens), 0) AS input_tokens,
   COALESCE(SUM(output_tokens), 0) AS output_tokens,
   COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
   COALESCE(SUM(cache_write_tokens), 0) AS cache_write_tokens,
   COALESCE(SUM(total_tokens), 0) AS total_tokens,
-  COALESCE(SUM(estimated_cost_microusd), 0) AS known_cost_microusd`;
+  COALESCE(SUM(CASE WHEN provider <> 'xopc-cloud' AND cost_source <> 'local' THEN estimated_cost_microusd ELSE 0 END), 0) AS known_cost_microusd`;
 /** Aggregate all retained AI usage records for the requested conversations. */
 function summarizeAiUsageByConversations(conversationIds) {
 	const uniqueIds = [...new Set(conversationIds.filter(Boolean))];
@@ -140,6 +215,19 @@ function summarizeAiUsage(query) {
 }
 function eventFromRow(row) {
 	const pricingSnapshot = typeof row.pricing_snapshot_json === "string" ? JSON.parse(row.pricing_snapshot_json) : void 0;
+	const estimatedCostUsd = row.provider === "xopc-cloud" || row.cost_source === "local" || row.estimated_cost_microusd === null ? void 0 : usd(Number(row.estimated_cost_microusd));
+	const billing = row.provider === "xopc-cloud" ? row.cloud_billing_json ? JSON.parse(String(row.cloud_billing_json)) : {
+		source: "xopc_cloud",
+		state: "unavailable",
+		requestId: row.cloud_request_id ?? void 0,
+		reservedCreditMicro: null,
+		chargedCreditMicro: null,
+		releasedCreditMicro: null
+	} : row.cost_source === "local" ? { source: "local" } : {
+		source: "external_provider",
+		currency: "USD",
+		estimatedCostUsd
+	};
 	return {
 		id: String(row.id),
 		traceId: String(row.trace_id),
@@ -165,7 +253,8 @@ function eventFromRow(row) {
 		cacheWriteTokens: row.cache_write_tokens === null ? void 0 : Number(row.cache_write_tokens),
 		reasoningTokens: row.reasoning_tokens === null ? void 0 : Number(row.reasoning_tokens),
 		totalTokens: row.total_tokens === null ? void 0 : Number(row.total_tokens),
-		estimatedCostUsd: row.estimated_cost_microusd === null ? void 0 : usd(Number(row.estimated_cost_microusd)),
+		estimatedCostUsd,
+		billing,
 		costSource: String(row.cost_source),
 		pricingSnapshot,
 		errorSummary: row.error_summary ? String(row.error_summary) : void 0
@@ -198,4 +287,4 @@ function listAiUsageTrace(traceId) {
     ORDER BY started_at ASC, id ASC`).all(traceId).map(eventFromRow);
 }
 //#endregion
-export { AI_USAGE_RETENTION_MS, finishAiUsageEvent, getAiUsageEvent, getAiUsageEventView, insertAiUsageEvent, listAiUsageEvents, listAiUsageTrace, markStaleAiUsageEventsUnknown, pruneAiUsageEvents, summarizeAiUsage, summarizeAiUsageByConversations };
+export { AI_USAGE_RETENTION_MS, finishAiUsageEvent, getAiUsageEvent, getAiUsageEventView, insertAiUsageEvent, listAiUsageEvents, listAiUsageTrace, markAiUsageCloudReceiptAttempt, markStaleAiUsageEventsUnknown, pendingAiUsageCloudReceiptIds, pruneAiUsageEvents, setAiUsageCloudReceipt, setAiUsageCloudRequest, summarizeAiUsage, summarizeAiUsageByConversations };

package/dist/src/storage/sqlite/migrations/242_cloud_usage_receipts.sql

@@ -0,0 +1,5 @@
+ALTER TABLE ai_usage_events ADD COLUMN cloud_request_id TEXT;
+ALTER TABLE ai_usage_events ADD COLUMN cloud_billing_json TEXT
+  CHECK(cloud_billing_json IS NULL OR json_valid(cloud_billing_json));
+CREATE UNIQUE INDEX idx_ai_usage_cloud_request
+  ON ai_usage_events(cloud_request_id) WHERE cloud_request_id IS NOT NULL;

package/dist/src/storage/sqlite/migrations/runner.d.ts

@@ -3,7 +3,7 @@ import type { ApplyMigrationsOptions } from './types.js';
 /** Baseline schema version applied from schema.sql on first open. */
 export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 165;
 /** Latest schema version this release supports (increment when adding migrations). */
-export declare const XOPC_DB_SCHEMA_VERSION = 241;
+export declare const XOPC_DB_SCHEMA_VERSION = 242;
 export declare function resolveMigrationsDir(override?: string): string;
 /**
  * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.

package/dist/src/storage/sqlite/migrations/runner.js

@@ -57,7 +57,7 @@ function applySingleMigration(db, migration, discardOldScenes = false) {
 */
 function applyPendingMigrations(db, options = {}) {
 	db.function("xopc_operation_id", () => currentOperationId() ?? null);
-	const targetVersion = options.targetVersion ?? 241;
+	const targetVersion = options.targetVersion ?? 242;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (!options.migrationsDir && currentVersion < 165) throw new DatabaseSchemaTooOldError(currentVersion, 165);
@@ -95,7 +95,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 241;
+	const appVersion = options.targetVersion ?? 242;
 	const dbVersion = readSchemaVersion(db);
 	if (dbVersion > appVersion) return {
 		dbVersion,
@@ -137,7 +137,7 @@ var init_runner = __esmMin((() => {
 	init_errors();
 	log = createLogger("Sqlite:Migrations");
 	XOPC_DB_BASELINE_SCHEMA_VERSION = 165;
-	XOPC_DB_SCHEMA_VERSION = 241;
+	XOPC_DB_SCHEMA_VERSION = 242;
 }));
 //#endregion
 init_runner();

package/dist/src/storage/sqlite/schema.js

@@ -28,7 +28,7 @@ function ensureXopcDatabaseSchema(db, options = {}) {
 		currentVersion = 165;
 	}
 	applyPendingMigrations(db, {
-		targetVersion: 241,
+		targetVersion: 242,
 		databasePath: fresh ? void 0 : options.databasePath
 	});
 }

package/dist/src/tasks/task-main-update-decision-service.js

@@ -1,9 +1,9 @@
 import { TaskRepository, init_task_repository } from "./task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "./task-run-repository.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { init_providers, resolveModel } from "../providers/index.js";
-import { getPersonalAgentByConversation } from "../personal-agent/repository.js";
 import { completeWithResolvedCredentials } from "../providers/model-call.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
+import { getPersonalAgentByConversation } from "../personal-agent/repository.js";
 import { TaskCollaborationRepository } from "./task-collaboration-repository.js";
 //#region src/tasks/task-main-update-decision-service.ts
 init_providers();

package/dist/src/tui/backends/embedded-backend.js

@@ -11,8 +11,8 @@ import { init_sqlite } from "../../storage/sqlite/index.js";
 import { normalizeAgentId } from "../../agent-catalog/id.js";
 import { init_agent_scope, listAgentEntries } from "../../agent/agent-scope.js";
 import { AgentCatalogService } from "../../agent-catalog/service.js";
-import { init_paths } from "../../config/paths.js";
 import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
+import { init_paths } from "../../config/paths.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../../routing/agent-session-key.js";
 import { resolveEffectiveAgentProfile } from "../../config/agent-profile.js";
 import { effectiveWorkspacePathForSession } from "../../session/session-workspace.js";

package/dist/src/tui/tui.js

@@ -2,8 +2,8 @@ import { version } from "../../package.js";
 import { resolveStateDir, resolveXopcDatabasePath } from "../config/paths-state.js";
 import { init_paths } from "../config/paths.js";
 import { init_agent_session_key, normalizeAgentId } from "../routing/agent-session-key.js";
-import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
 import { getAllModels, getAllProviders, getApiKey, init_providers, isProviderConfiguredSync } from "../providers/index.js";
+import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
 import { isTerminalWorkflowRunStatus } from "../workflows/domain/run.js";
 import "../workflows/domain/index.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";

package/dist/src/usage/cloud-capability.d.ts

@@ -0,0 +1,2 @@
+/** Cloud tools receive independent receipts even when the parent chat uses BYOK. */
+export declare function trackCloudCapabilityUsage<T>(model: string, operation: string, action: () => Promise<T>): Promise<T>;

package/dist/src/usage/cloud-capability.js

@@ -0,0 +1,34 @@
+import { startAiUsageCall } from "./recorder.js";
+import { getEmbeddedExecutionRunId, getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
+//#region src/usage/cloud-capability.ts
+/** Cloud tools receive independent receipts even when the parent chat uses BYOK. */
+async function trackCloudCapabilityUsage(model, operation, action) {
+	const call = startAiUsageCall({
+		provider: "xopc-cloud",
+		id: model,
+		baseUrl: void 0,
+		cost: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0
+		}
+	}, {
+		operation,
+		conversationId: getEmbeddedExecutionSession(),
+		runId: getEmbeddedExecutionRunId()
+	});
+	try {
+		const result = await call.run(action);
+		call.finish({ status: "succeeded" });
+		return result;
+	} catch (error) {
+		call.finish({
+			status: "failed",
+			errorSummary: error instanceof Error ? error.message : String(error)
+		});
+		throw error;
+	}
+}
+//#endregion
+export { trackCloudCapabilityUsage };

package/dist/src/usage/cloud-receipts.d.ts

@@ -0,0 +1,10 @@
+import type { SimpleStreamOptions } from '@earendil-works/pi-ai';
+export declare function withUsageReceiptContext<T>(id: string, action: () => T): T;
+export declare function captureCloudUsageResponse(response: {
+    status: number;
+    headers: Headers | Record<string, string>;
+}): void;
+/** Preserve existing response hooks while linking the physical Cloud request to its usage row. */
+export declare function withCloudUsageResponse(options?: SimpleStreamOptions): SimpleStreamOptions;
+/** Bounded, read-only synchronization. Missing authorization or receipt never becomes a zero charge. */
+export declare function reconcileCloudUsageReceipt(id: string): Promise<void>;

package/dist/src/usage/cloud-receipts.js

@@ -0,0 +1,55 @@
+import { init_connection, isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import { getAiUsageEvent, markAiUsageCloudReceiptAttempt, setAiUsageCloudReceipt, setAiUsageCloudRequest } from "../storage/sqlite/ai-usage-repository.js";
+import { XopcCloudAccountService } from "../providers/xopc-cloud-account-service.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/usage/cloud-receipts.ts
+init_connection();
+const calls = new AsyncLocalStorage();
+const active = /* @__PURE__ */ new Map();
+function withUsageReceiptContext(id, action) {
+	return calls.run({ id }, action);
+}
+function captureCloudUsageResponse(response) {
+	if (response.status < 200 || response.status >= 300) return;
+	const id = calls.getStore()?.id;
+	const requestId = new Headers(response.headers).get("x-xopc-request-id");
+	if (id && requestId && isXopcDatabaseOpen()) try {
+		setAiUsageCloudRequest(id, requestId);
+	} catch {}
+}
+/** Preserve existing response hooks while linking the physical Cloud request to its usage row. */
+function withCloudUsageResponse(options) {
+	return {
+		...options,
+		onResponse: async (response, model) => {
+			if (model.provider === "xopc-cloud") captureCloudUsageResponse(response);
+			await options?.onResponse?.(response, model);
+		}
+	};
+}
+/** Bounded, read-only synchronization. Missing authorization or receipt never becomes a zero charge. */
+function reconcileCloudUsageReceipt(id) {
+	const running = active.get(id);
+	if (running) return running;
+	if (!isXopcDatabaseOpen() || active.size >= 4) return Promise.resolve();
+	const row = getAiUsageEvent(id);
+	if (row?.provider !== "xopc-cloud" || typeof row.cloud_request_id !== "string") return Promise.resolve();
+	const state = row.cloud_billing_json ? JSON.parse(String(row.cloud_billing_json)).state : void 0;
+	if (state === "settled" || state === "released") return Promise.resolve();
+	const requestId = row.cloud_request_id;
+	markAiUsageCloudReceiptAttempt(id);
+	const service = new XopcCloudAccountService({ fetchImpl: (url, init) => fetch(url, {
+		...init,
+		signal: AbortSignal.timeout(5e3)
+	}) });
+	const sync = (async () => {
+		try {
+			const receipt = await service.getReceipt(requestId);
+			if (receipt?.requestId === requestId && isXopcDatabaseOpen()) setAiUsageCloudReceipt(id, receipt);
+		} catch {}
+	})().finally(() => active.delete(id));
+	active.set(id, sync);
+	return sync;
+}
+//#endregion
+export { captureCloudUsageResponse, reconcileCloudUsageReceipt, withCloudUsageResponse, withUsageReceiptContext };

package/dist/src/usage/cost.js

@@ -17,6 +17,7 @@ function pricingSnapshot(model) {
 	};
 }
 function classifyCostSource(model) {
+	if (model.provider === "xopc-cloud") return "unknown";
 	if (isLocalBaseUrl(model.baseUrl)) return "local";
 	return Object.values(pricingSnapshot(model)).some((price) => price > 0) ? "model_catalog" : "unknown";
 }

package/dist/src/usage/recorder.js

@@ -5,6 +5,7 @@ import { startObservation } from "../observability/runtime.js";
 import { finishAiUsageEvent, insertAiUsageEvent } from "../storage/sqlite/ai-usage-repository.js";
 import { classifyCostSource, dollarsToMicrousd, pricingSnapshot } from "./cost.js";
 import { resolveAiUsageScenario } from "./scenario-registry.js";
+import { reconcileCloudUsageReceipt, withUsageReceiptContext } from "./cloud-receipts.js";
 import { randomUUID } from "node:crypto";
 //#region src/usage/recorder.ts
 init_connection();
@@ -67,7 +68,7 @@ function startAiUsageCall(model, context, input) {
 	let completed = false;
 	return {
 		id,
-		run: observation.run,
+		run: (fn) => observation.run(() => withUsageReceiptContext(id, fn)),
 		finish(result) {
 			if (completed) return;
 			completed = true;
@@ -90,6 +91,7 @@ function startAiUsageCall(model, context, input) {
 					...result,
 					estimatedCostMicrousd: costSource === "local" ? 0 : costSource === "unknown" ? void 0 : dollarsToMicrousd(result.usage?.cost?.total)
 				});
+				if (model.provider === "xopc-cloud") reconcileCloudUsageReceipt(id);
 			} catch (err) {
 				log.error({
 					err,

package/dist/src/usage/scenario-registry.js

@@ -1,5 +1,20 @@
 //#region src/usage/scenario-registry.ts
 const SCENARIOS = {
+	"images.generate": {
+		category: "other",
+		reasonKey: "usage.reason.imageGeneration",
+		trigger: "agent"
+	},
+	"audio.transcribe": {
+		category: "other",
+		reasonKey: "usage.reason.audioTranscription",
+		trigger: "user"
+	},
+	"audio.speech": {
+		category: "other",
+		reasonKey: "usage.reason.audioSpeech",
+		trigger: "agent"
+	},
 	"agent.answer": {
 		category: "chat",
 		reasonKey: "usage.reason.agentAnswer",

package/dist/src/voice/realtime/runtime.js

@@ -418,29 +418,34 @@ var VoiceRealtimeRuntime = class {
 			sockets?.delete(socket);
 			if (sockets?.size === 0) this.socketsByPrincipal.delete(claim.principalId);
 		};
-		const shutdown = async (reason, notify) => {
-			if (closed) return;
+		let shutdownCompletion;
+		const shutdown = (reason, notify) => {
+			if (shutdownCompletion) return shutdownCompletion;
+			if (closed) return Promise.resolve();
 			closed = true;
-			if (claim && this.activeSessions.get(claim.sessionId)?.socket === socket) this.activeSessions.delete(claim.sessionId);
-			unsubscribeMemory?.();
-			unsubscribeSession?.();
-			clearTimeout(startTimer);
-			clearInterval(lifecycleTimer);
-			try {
-				await engine?.close();
-			} catch (err) {
-				log.error({
-					err,
-					sessionId: claim?.sessionId
-				}, "Voice cleanup failed");
-			} finally {
-				abortController.abort(reason);
-			}
-			if (notify) send("session.closed", { reason });
-			detachPrincipal();
-			if (claim) this.releaseConversationReservation(claim);
-			this.preauthBudget.release(clientIp);
-			if (socket.readyState === WebSocketState.OPEN) socket.close(1e3, reason.slice(0, 120));
+			shutdownCompletion = (async () => {
+				unsubscribeMemory?.();
+				unsubscribeSession?.();
+				clearTimeout(startTimer);
+				clearInterval(lifecycleTimer);
+				try {
+					await engine?.close();
+				} catch (err) {
+					log.error({
+						err,
+						sessionId: claim?.sessionId
+					}, "Voice cleanup failed");
+				} finally {
+					abortController.abort(reason);
+				}
+				if (notify) send("session.closed", { reason });
+				detachPrincipal();
+				if (claim && this.activeSessions.get(claim.sessionId)?.socket === socket) this.activeSessions.delete(claim.sessionId);
+				if (claim) this.releaseConversationReservation(claim);
+				this.preauthBudget.release(clientIp);
+				if (socket.readyState === WebSocketState.OPEN) socket.close(1e3, reason.slice(0, 120));
+			})();
+			return shutdownCompletion;
 		};
 		const startTimer = setTimeout(() => socket.close(4401, "Voice session start timeout"), VOICE_REALTIME_START_TIMEOUT_MS);
 		const lifecycleTimer = setInterval(() => {

package/dist/src/voice/stt/providers/xopc-cloud-transcription.js

@@ -1,8 +1,11 @@
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "../../../providers/xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "../../../providers/provider-auth-service.js";
+import { captureCloudUsageResponse } from "../../../usage/cloud-receipts.js";
+import { cloudCreditBudgetHeaders, rejectUnbudgetedCloudTransport, reportCloudCreditError } from "../../../providers/xopc-cloud-credit-budget.js";
 import { compareCatalogModels } from "../../../providers/model-catalog-ranking.js";
 import { registerMediaUnderstandingProvider } from "../../../media-understanding/registry.js";
+import { trackCloudCapabilityUsage } from "../../../usage/cloud-capability.js";
 import { openPlatformStt } from "../../platform-streams.js";
 import { platformVoiceModels, requirePlatformVoiceModel } from "../../platform-catalog.js";
 //#region src/voice/stt/providers/xopc-cloud-transcription.ts
@@ -32,21 +35,31 @@ const xopcCloudTranscriptionProvider = {
 		form.append("file", new File([Uint8Array.from(request.buffer)], request.fileName, { type: request.mime ?? "application/octet-stream" }));
 		if (request.language) form.append("language", request.language);
 		if (request.prompt) form.append("prompt", request.prompt);
-		const response = await fetch(`${baseUrl}/audio/transcriptions`, {
-			method: "POST",
-			headers: { authorization: `Bearer ${accessToken}` },
-			body: form,
-			signal: request.signal ?? AbortSignal.timeout(request.timeoutMs),
-			redirect: "error"
+		return trackCloudCapabilityUsage(model, "audio.transcribe", async () => {
+			const response = await fetch(`${baseUrl}/audio/transcriptions`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${accessToken}`,
+					...await cloudCreditBudgetHeaders()
+				},
+				body: form,
+				signal: request.signal ?? AbortSignal.timeout(request.timeoutMs),
+				redirect: "error"
+			});
+			captureCloudUsageResponse(response);
+			const body = await response.json().catch(() => null);
+			if (!response.ok) {
+				const message = `${body?.error?.code ?? ""}: ${typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud STT failed (${response.status})`}`;
+				reportCloudCreditError(message);
+				throw new Error(message);
+			}
+			if (typeof body?.text !== "string") throw new Error("XOPC Cloud STT returned an invalid response");
+			return {
+				text: body.text,
+				model,
+				...request.language ? { language: request.language } : {}
+			};
 		});
-		const body = await response.json().catch(() => null);
-		if (!response.ok) throw new Error(typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud STT failed (${response.status})`);
-		if (typeof body?.text !== "string") throw new Error("XOPC Cloud STT returned an invalid response");
-		return {
-			text: body.text,
-			model,
-			...request.language ? { language: request.language } : {}
-		};
 	},
 	streamingAudio: {
 		inputSampleRates: [16e3],
@@ -59,6 +72,7 @@ const xopcCloudTranscriptionProvider = {
 		}
 	},
 	openAudioStream: async (request) => {
+		rejectUnbudgetedCloudTransport();
 		const catalogModel = requirePlatformVoiceModel(request.model, "transcription.stream");
 		const accessToken = await getProviderAuthService().resolveApiKey("xopc-cloud", request.signal);
 		if (!accessToken) throw new Error("XOPC Cloud authorization is unavailable");

package/dist/src/voice/tts/providers/xopc-cloud-speech.js

@@ -1,7 +1,10 @@
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "../../../providers/xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "../../../providers/provider-auth-service.js";
+import { captureCloudUsageResponse } from "../../../usage/cloud-receipts.js";
+import { cloudCreditBudgetHeaders, rejectUnbudgetedCloudTransport, reportCloudCreditError } from "../../../providers/xopc-cloud-credit-budget.js";
 import { compareCatalogModels } from "../../../providers/model-catalog-ranking.js";
+import { trackCloudCapabilityUsage } from "../../../usage/cloud-capability.js";
 import { openPlatformTts } from "../../platform-streams.js";
 import { requirePlatformVoiceModel } from "../../platform-catalog.js";
 import { registerSpeechProvider } from "../speech-registry.js";
@@ -74,38 +77,45 @@ const xopcCloudSpeechProvider = {
 		const outputFormat = request.target === "voice-note" && catalogModel.tts?.outputFormats.includes("opus") ? "opus" : catalogModel.tts?.outputFormats.includes("mp3") ? "mp3" : catalogModel.tts?.outputFormats[0] ?? "wav";
 		const token = await getProviderAuthService().resolveApiKey("xopc-cloud");
 		if (!token) throw new Error("XOPC Cloud authorization is unavailable");
-		const response = await fetch(`${config.baseUrl.replace(/\/+$/, "")}/audio/speech`, {
-			method: "POST",
-			headers: {
-				authorization: `Bearer ${token}`,
-				"content-type": "application/json"
-			},
-			body: JSON.stringify({
-				model,
-				input: request.text,
-				voice,
-				response_format: outputFormat,
-				...speed !== void 0 && catalogModel.tts?.speed ? { speed } : {},
-				...instructions && catalogModel.tts?.instructions ? { instructions } : {}
-			}),
-			signal: request.signal,
-			redirect: "error"
+		return trackCloudCapabilityUsage(model, "audio.speech", async () => {
+			const response = await fetch(`${config.baseUrl.replace(/\/+$/, "")}/audio/speech`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${token}`,
+					"content-type": "application/json",
+					...await cloudCreditBudgetHeaders()
+				},
+				body: JSON.stringify({
+					model,
+					input: request.text,
+					voice,
+					response_format: outputFormat,
+					...speed !== void 0 && catalogModel.tts?.speed ? { speed } : {},
+					...instructions && catalogModel.tts?.instructions ? { instructions } : {}
+				}),
+				signal: request.signal,
+				redirect: "error"
+			});
+			captureCloudUsageResponse(response);
+			if (!response.ok) {
+				const body = await response.json().catch(() => null);
+				const message = `${body?.error?.code ?? ""}: ${typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud TTS failed (${response.status})`}`;
+				reportCloudCreditError(message);
+				throw new Error(message);
+			}
+			const audioBuffer = Buffer.from(await response.arrayBuffer());
+			if (audioBuffer.length === 0) throw new Error("XOPC Cloud TTS returned empty audio");
+			const fileExtension = extension(response.headers.get("content-type"), outputFormat);
+			return {
+				audioBuffer,
+				outputFormat: fileExtension,
+				fileExtension,
+				voiceCompatible: fileExtension === "opus" || fileExtension === "ogg"
+			};
 		});
-		if (!response.ok) {
-			const body = await response.json().catch(() => null);
-			throw new Error(typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud TTS failed (${response.status})`);
-		}
-		const audioBuffer = Buffer.from(await response.arrayBuffer());
-		if (audioBuffer.length === 0) throw new Error("XOPC Cloud TTS returned empty audio");
-		const fileExtension = extension(response.headers.get("content-type"), outputFormat);
-		return {
-			audioBuffer,
-			outputFormat: fileExtension,
-			fileExtension,
-			voiceCompatible: fileExtension === "opus" || fileExtension === "ogg"
-		};
 	},
 	synthesizeStream: async (request) => {
+		rejectUnbudgetedCloudTransport();
 		const config = readConfig(request.providerConfig);
 		const model = typeof request.providerOverrides?.model === "string" ? request.providerOverrides.model : config.model;
 		const voice = typeof request.providerOverrides?.voice === "string" ? request.providerOverrides.voice : config.voice;

package/dist/src/voice/tts/speech-provider-types.d.ts

@@ -97,6 +97,7 @@ export interface SpeechStreamSession {
 export type SpeechStreamSessionRequest = Omit<SpeechSynthesisStreamRequest, 'text'>;
 /** Voice catalog entry returned by `listVoices`. */
 export interface SpeechVoiceOption {
+    displayNames?: Partial<Record<'zh-CN' | 'en', string>>;
     id: string;
     name?: string;
     category?: string;