@xopcai/xopc 0.0.372 → 0.0.373

package/dist/src/providers/provider-auth-service.js

@@ -1,7 +1,7 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { init_paths, resolveModelsJsonPath } from "../config/paths.js";
-import { init_register_bundled_oauth_flows, registerBundledOAuthFlows } from "./register-bundled-oauth-flows.js";
 import { assertCurrentModelProvider, init_provider_policy } from "./provider-policy.js";
+import { init_register_bundled_oauth_flows, registerBundledOAuthFlows } from "./register-bundled-oauth-flows.js";
 import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { XopcModelCredentialStore, init_model_credential_store } from "../auth/model-credential-store.js";
 import { init_register_runtime_providers, registerRuntimeProviders } from "./register-runtime-providers.js";

package/dist/src/providers/provider-disconnect-core.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
 import { CredentialResolver, init_credentials } from "../auth/credentials.js";
-import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
 import { evictAllEmbeddedSessionRunners } from "../agent/embedded/session-runner.js";
 //#region src/providers/provider-disconnect-core.ts

package/dist/src/providers/register-runtime-providers.js

@@ -1,7 +1,7 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
 import { init_provider_policy, isRetiredModelProvider } from "./provider-policy.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
+import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
 import { XOPC_CLOUD_PROVIDER_ID, init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 //#region src/providers/register-runtime-providers.ts
 function registerRuntimeProvider(modelRuntime, source) {

package/dist/src/providers/xopc-cloud-account-service.d.ts

@@ -1,26 +1,6 @@
-import { z } from 'zod';
+import { type CloudAccountSummary, type CloudCreditBudget, type CloudBillingReceipt } from '@xopcai/gateway-contract';
 import { type ProviderAuthService } from './provider-auth-service.js';
-declare const accountSummarySchema: z.ZodObject<{
-    balance: z.ZodObject<{
-        credits: z.ZodNumber;
-        updatedAt: z.ZodString;
-    }, z.core.$strip>;
-    usage: z.ZodObject<{
-        days: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<7>, z.ZodLiteral<30>]>;
-        requests: z.ZodNumber;
-        inputTokens: z.ZodNumber;
-        outputTokens: z.ZodNumber;
-        totalTokens: z.ZodNumber;
-        errors: z.ZodNumber;
-        averageLatencyMs: z.ZodNumber;
-        chargedCredits: z.ZodNumber;
-    }, z.core.$strip>;
-    links: z.ZodObject<{
-        details: z.ZodString;
-        purchase: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export type XopcCloudAccountSummary = z.infer<typeof accountSummarySchema>;
+export type XopcCloudAccountSummary = CloudAccountSummary;
 export declare class XopcCloudAccountError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -35,6 +15,10 @@ export declare class XopcCloudAccountService {
         routerUrl?: string;
         credentials?: Pick<ProviderAuthService, 'resolveApiKey'>;
     });
+    private request;
+    private parse;
     getSummary(days?: 1 | 7 | 30): Promise<XopcCloudAccountSummary | null>;
+    createBudget(limitCreditMicro: string, key: string): Promise<CloudCreditBudget | null>;
+    getReceipt(requestId: string): Promise<CloudBillingReceipt | null>;
+    getBudget(id: string): Promise<CloudCreditBudget | null>;
 }
-export {};

package/dist/src/providers/xopc-cloud-account-service.js

@@ -1,33 +1,12 @@
+import { cloudAccountSummarySchema, cloudBillingReceiptSchema, cloudCreditBudgetSchema, creditMicroSchema, creditUnitSchema } from "../../packages/gateway-contract/src/cloud-credits.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
 import { z } from "zod";
 //#region src/providers/xopc-cloud-account-service.ts
+init_src();
 init_provider_auth_service();
 init_xopc_cloud_config();
-const accountSummarySchema = z.object({
-	balance: z.object({
-		credits: z.number().int().nonnegative(),
-		updatedAt: z.string().datetime()
-	}),
-	usage: z.object({
-		days: z.union([
-			z.literal(1),
-			z.literal(7),
-			z.literal(30)
-		]),
-		requests: z.number().int().nonnegative(),
-		inputTokens: z.number().int().nonnegative(),
-		outputTokens: z.number().int().nonnegative(),
-		totalTokens: z.number().int().nonnegative(),
-		errors: z.number().int().nonnegative(),
-		averageLatencyMs: z.number().nonnegative(),
-		chargedCredits: z.number().int().nonnegative()
-	}),
-	links: z.object({
-		details: z.string().url(),
-		purchase: z.string().url()
-	})
-});
 var XopcCloudAccountError = class extends Error {
 	constructor(message, status, code) {
 		super(message);
@@ -45,22 +24,63 @@ var XopcCloudAccountService = class {
 		this.routerUrl = resolveXopcModelRouterUrl(options.routerUrl);
 		this.credentials = options.credentials ?? getProviderAuthService();
 	}
-	async getSummary(days = 7) {
+	async request(path, init) {
 		const accessToken = await this.credentials.resolveApiKey("xopc-cloud");
 		if (!accessToken) return null;
-		const response = await this.fetchImpl(`${this.routerUrl}/account/summary?days=${days}`, {
+		const response = await this.fetchImpl(`${this.routerUrl}${path}`, {
+			...init,
 			headers: {
+				...Object.fromEntries(new Headers(init?.headers)),
 				authorization: `Bearer ${accessToken}`,
 				accept: "application/json"
 			},
-			signal: AbortSignal.timeout(3e4)
+			signal: AbortSignal.timeout(3e4),
+			redirect: "error"
 		});
 		const body = await response.json().catch(() => null);
 		if (!response.ok) throw new XopcCloudAccountError(typeof body?.error?.message === "string" ? body.error.message : `XOPC account summary failed (${response.status})`, response.status, typeof body?.error?.code === "string" ? body.error.code : void 0);
-		const parsed = accountSummarySchema.safeParse(body);
-		if (!parsed.success) throw new XopcCloudAccountError("XOPC account summary returned an invalid response", response.status, "invalid_response");
+		if (body === null) throw new XopcCloudAccountError("XOPC Cloud returned invalid JSON", 502, "invalid_response");
+		return body;
+	}
+	parse(schema, body) {
+		if (body === null) return null;
+		const parsed = schema.safeParse(body);
+		if (!parsed.success) throw new XopcCloudAccountError("XOPC Cloud returned an invalid Credit response", 502, "invalid_response");
 		return parsed.data;
 	}
+	async getSummary(days = 7) {
+		return this.parse(cloudAccountSummarySchema, await this.request(`/account/summary?version=2&days=${days}`));
+	}
+	async createBudget(limitCreditMicro, key) {
+		creditMicroSchema.parse(limitCreditMicro);
+		if (limitCreditMicro === "0" || limitCreditMicro.length > 15 || !/^[\w:.-]{8,128}$/.test(key)) throw new Error("Invalid Credit budget");
+		return this.parse(z.object({
+			creditUnit: creditUnitSchema,
+			budget: cloudCreditBudgetSchema
+		}), await this.request("/account/budgets", {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"Idempotency-Key": key
+			},
+			body: JSON.stringify({ limitCreditMicro })
+		}))?.budget ?? null;
+	}
+	async getReceipt(requestId) {
+		z.string().min(1).max(128).parse(requestId);
+		return this.parse(z.object({
+			schemaVersion: z.literal(2),
+			creditUnit: creditUnitSchema,
+			receipt: cloudBillingReceiptSchema
+		}), await this.request(`/account/receipts/${encodeURIComponent(requestId)}`))?.receipt ?? null;
+	}
+	async getBudget(id) {
+		z.string().uuid().parse(id);
+		return this.parse(z.object({
+			creditUnit: creditUnitSchema,
+			budget: cloudCreditBudgetSchema
+		}), await this.request(`/account/budgets/${encodeURIComponent(id)}`))?.budget ?? null;
+	}
 };
 //#endregion
 export { XopcCloudAccountError, XopcCloudAccountService };

package/dist/src/providers/xopc-cloud-catalog-coordinator.js

@@ -1,9 +1,9 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
 import { ModelCatalogPersistence, init_model_catalog_persistence } from "./model-catalog-persistence.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { getModelRegistry, init_model_registry } from "./model-registry.js";
+import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
 import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
 import { disconnectProviderCore } from "./provider-disconnect-core.js";
 import { XopcCloudModelSource } from "./xopc-cloud-model-source.js";

package/dist/src/providers/xopc-cloud-credit-budget.d.ts

@@ -0,0 +1,14 @@
+import { XopcCloudAccountService } from './xopc-cloud-account-service.js';
+export declare function hasCloudCreditBudget(): boolean;
+export declare function cloudCreditBudgetStopMessage(): string | undefined;
+export declare function isCloudCreditBudgetExhausted(message: string): boolean;
+export declare function reportCloudCreditError(message: string): void;
+export declare function assertCloudCreditBudgetActive(): void;
+/** Children inherit their parent's scope; repeated attempts use the same platform budget. */
+export declare function withCloudCreditBudget<T>(options: {
+    conversationId: string;
+    runId: string;
+    limitCreditMicro?: string;
+}, action: () => Promise<T>): Promise<T>;
+export declare function cloudCreditBudgetHeaders(service?: Pick<XopcCloudAccountService, 'createBudget'>): Promise<Record<string, string>>;
+export declare function rejectUnbudgetedCloudTransport(operation?: string): void;

package/dist/src/providers/xopc-cloud-credit-budget.js

@@ -0,0 +1,61 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { XopcCloudAccountService } from "./xopc-cloud-account-service.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+//#region src/providers/xopc-cloud-credit-budget.ts
+init_logger();
+const log = createLogger("CloudCreditBudget");
+const scopes = new AsyncLocalStorage();
+const EXHAUSTED = /credit_budget_exhausted|(?:task Credit|Credit task) budget exhausted/i;
+function hasCloudCreditBudget() {
+	return Boolean(scopes.getStore());
+}
+function cloudCreditBudgetStopMessage() {
+	return scopes.getStore()?.stopped;
+}
+function isCloudCreditBudgetExhausted(message) {
+	return EXHAUSTED.test(message);
+}
+function reportCloudCreditError(message) {
+	const scope = scopes.getStore();
+	if (scope && isCloudCreditBudgetExhausted(message)) scope.stopped = "credit_budget_exhausted: Credit task budget exhausted";
+}
+function assertCloudCreditBudgetActive() {
+	const stopped = scopes.getStore()?.stopped;
+	if (stopped) throw new Error(stopped);
+}
+/** Children inherit their parent's scope; repeated attempts use the same platform budget. */
+async function withCloudCreditBudget(options, action) {
+	if (scopes.getStore() || !options.limitCreditMicro) return action();
+	const key = `xopc-run:${createHash("sha256").update(JSON.stringify([options.conversationId, options.runId])).digest("hex")}`;
+	return scopes.run({
+		key,
+		conversationId: options.conversationId,
+		runId: options.runId,
+		limitCreditMicro: options.limitCreditMicro
+	}, action);
+}
+async function cloudCreditBudgetHeaders(service) {
+	assertCloudCreditBudgetActive();
+	const scope = scopes.getStore();
+	if (!scope) return {};
+	scope.budget ??= (service ?? new XopcCloudAccountService()).createBudget(scope.limitCreditMicro, scope.key).then((budget) => {
+		if (budget) log.info({
+			conversationId: scope.conversationId,
+			runId: scope.runId,
+			creditBudgetId: budget.id,
+			limitCreditMicro: budget.limitCreditMicro
+		}, "Created Cloud run Credit budget");
+		return budget;
+	});
+	const budget = await scope.budget;
+	if (!budget) throw new Error("XOPC Cloud authorization is unavailable");
+	assertCloudCreditBudgetActive();
+	return { "x-xopc-credit-budget": budget.id };
+}
+function rejectUnbudgetedCloudTransport(operation = "realtime voice") {
+	if (scopes.getStore()) throw new Error(`Credit run budgets do not support ${operation} yet`);
+}
+//#endregion
+export { assertCloudCreditBudgetActive, cloudCreditBudgetHeaders, cloudCreditBudgetStopMessage, hasCloudCreditBudget, isCloudCreditBudgetExhausted, rejectUnbudgetedCloudTransport, reportCloudCreditError, withCloudCreditBudget };

package/dist/src/storage/sqlite/ai-usage-repository.d.ts

@@ -1,4 +1,5 @@
 import type { AiUsageEvent, AiUsageFinish } from '../../usage/types.js';
+import type { CloudBillingReceipt, UsageBilling, UsageTotals } from '@xopcai/gateway-contract';
 export declare const AI_USAGE_RETENTION_MS: number;
 export declare function insertAiUsageEvent(event: AiUsageEvent): void;
 export declare function finishAiUsageEvent(id: string, finish: AiUsageFinish & {
@@ -7,6 +8,8 @@ export declare function finishAiUsageEvent(id: string, finish: AiUsageFinish & {
 export declare function markStaleAiUsageEventsUnknown(cutoffMs: number, now?: number): number;
 export declare function pruneAiUsageEvents(cutoffMs: number): number;
 export declare function getAiUsageEvent(id: string): Record<string, unknown> | undefined;
+export declare function setAiUsageCloudRequest(id: string, requestId: string): void;
+export declare function setAiUsageCloudReceipt(id: string, receipt: CloudBillingReceipt): void;
 export type AiUsageQuery = {
     from: number;
     to: number;
@@ -16,6 +19,8 @@ export type AiUsageQuery = {
     agentId?: string;
     conversationId?: string;
 };
+export declare function pendingAiUsageCloudReceiptIds(query: AiUsageQuery): string[];
+export declare function markAiUsageCloudReceiptAttempt(id: string): void;
 export type AiUsageTotals = {
     calls: number;
     succeededCalls: number;
@@ -28,6 +33,7 @@ export type AiUsageTotals = {
     totalTokens: number;
     knownCostUsd: string;
     costCompleteness: 'complete' | 'partial' | 'unknown';
+    billing: NonNullable<UsageTotals['billing']>;
 };
 export type ConversationAiUsageTotals = Pick<AiUsageTotals, 'calls' | 'unknownCostCalls' | 'totalTokens' | 'knownCostUsd' | 'costCompleteness'>;
 /** Aggregate all retained AI usage records for the requested conversations. */
@@ -78,6 +84,7 @@ export declare function listAiUsageEvents(query: AiUsageQuery & {
         reasoningTokens: number;
         totalTokens: number;
         estimatedCostUsd: string;
+        billing: UsageBilling;
         costSource: string;
         pricingSnapshot: Record<string, number>;
         errorSummary: string;
@@ -110,6 +117,7 @@ export declare function getAiUsageEventView(id: string): {
     reasoningTokens: number;
     totalTokens: number;
     estimatedCostUsd: string;
+    billing: UsageBilling;
     costSource: string;
     pricingSnapshot: Record<string, number>;
     errorSummary: string;
@@ -140,6 +148,7 @@ export declare function listAiUsageTrace(traceId: string): {
     reasoningTokens: number;
     totalTokens: number;
     estimatedCostUsd: string;
+    billing: UsageBilling;
     costSource: string;
     pricingSnapshot: Record<string, number>;
     errorSummary: string;

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>;