@xopcai/xopc 0.0.371 → 0.0.373

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

@@ -1,4 +1,5 @@
-import { getAiUsageEventView, listAiUsageEvents, listAiUsageTrace, summarizeAiUsage } from "../../../storage/sqlite/ai-usage-repository.js";
+import { getAiUsageEventView, listAiUsageEvents, listAiUsageTrace, pendingAiUsageCloudReceiptIds, summarizeAiUsage } from "../../../storage/sqlite/ai-usage-repository.js";
+import { reconcileCloudUsageReceipt } from "../../../usage/cloud-receipts.js";
 import { z } from "zod";
 import { Hono } from "hono";
 //#region src/gateway/hono/routes/usage.ts
@@ -41,14 +42,23 @@ function registerUsageRoutes(authenticated, _deps) {
 		if (error instanceof z.ZodError || error.message.startsWith("invalid_usage_")) return c.json({ error: "invalid_usage_query" }, 400);
 		throw error;
 	});
-	app.get("/summary", (c) => c.json(summarizeAiUsage(parseFilters(c.req.query()))));
-	app.get("/events", (c) => {
+	const refreshReceipts = async (query) => {
+		await Promise.all(pendingAiUsageCloudReceiptIds(query).map(reconcileCloudUsageReceipt));
+	};
+	app.get("/summary", async (c) => {
+		const query = parseFilters(c.req.query());
+		await refreshReceipts(query);
+		return c.json(summarizeAiUsage(query));
+	});
+	app.get("/events", async (c) => {
 		const limit = z.coerce.number().int().min(1).max(200).optional().parse(c.req.query("limit"));
-		return c.json(listAiUsageEvents({
+		const query = {
 			...parseFilters(c.req.query()),
 			limit,
 			before: parseCursor(c.req.query("cursor"))
-		}));
+		};
+		await refreshReceipts(query);
+		return c.json(listAiUsageEvents(query));
 	});
 	app.get("/events/:id", (c) => {
 		const event = getAiUsageEventView(c.req.param("id"));

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

@@ -1,8 +1,8 @@
 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";
-import { isPersonalConversation } from "../../../personal-agent/repository.js";
 import { completeWithResolvedCredentials } from "../../../providers/model-call.js";
+import { isPersonalConversation } from "../../../personal-agent/repository.js";
 import { resolveSttProviderConfigSlice } from "../../../voice/stt/config-slice.js";
 import { STTTranscriptionError, transcribe } from "../../../voice/stt/transcribe-core.js";
 import { isSTTAvailable } from "../../../voice/stt/availability.js";

package/dist/src/gateway/service/config-coordinator.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { configureTracing } from "../../observability/runtime.js";
 import { getModelRegistry } from "../../providers/model-registry.js";
 import { init_providers } from "../../providers/index.js";
+import { configureTracing } from "../../observability/runtime.js";
 import { evictAllEmbeddedSessionRunners } from "../../agent/embedded/session-runner.js";
 import { reloadImageGenerationProviders } from "../../agent/image/generation/provider-registry.js";
 import { loadConfig, saveConfig } from "../../config/loader.js";

package/dist/src/gateway/service/session-command-service.js

@@ -1,7 +1,7 @@
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { init_session_repository } from "../../storage/sqlite/session-repository.js";
-import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
+import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
 import { getPersonalAgentByConversation } from "../../personal-agent/repository.js";
 import { resolveProjectAgentId } from "../../projects/project-agent.js";
 import "../../projects/index.js";

package/dist/src/gateway/service.js

@@ -18,17 +18,17 @@ import { getSessionConfig, init_config_repository } from "../storage/sqlite/conf
 import { init_sqlite } from "../storage/sqlite/index.js";
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
-import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
-import { flushTracing } from "../observability/runtime.js";
 import { init_config, resolveKnowledgeReadPolicy } from "../user-context/config.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
+import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_agent_session_key, resolveAgentMainConversationId } from "../routing/agent-session-key.js";
 import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
 import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
-import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
-import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
+import { flushTracing } from "../observability/runtime.js";
 import { AI_USAGE_RETENTION_MS, markStaleAiUsageEventsUnknown, pruneAiUsageEvents } from "../storage/sqlite/ai-usage-repository.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { listKnowledgeItems } from "../knowledge-memory/repository.js";
 import "../knowledge-memory/index.js";
 import { getPersonalAgentByConversation } from "../personal-agent/repository.js";

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

@@ -1,7 +1,7 @@
 import { init_agent_scope, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { extractAssistantText, getAssistantMessageErrorReason } from "../providers/model-response.js";
 import { init_providers, resolveModel } from "../providers/index.js";
 import { completeWithResolvedCredentials, isLocalModelBaseUrl } from "../providers/model-call.js";
-import { extractAssistantText, getAssistantMessageErrorReason } from "../providers/model-response.js";
 import { resolveModelSelector } from "../config/agent-model-intents.js";
 import { z } from "zod";
 //#region src/home-intelligence/generator.ts

package/dist/src/notes/service.js

@@ -7,8 +7,8 @@ import { init_note_markdown, parseNoteMarkdown } from "./note-markdown.js";
 import { init_notes_repository, listNoteProjectSummaries } from "../storage/sqlite/notes-repository.js";
 import { changedFieldsFromPatch, emitActivity, previewText, systemActivityActor, systemActivitySource } from "../activity/emitter.js";
 import { getDefaultModelSync, init_providers, resolveModel } from "../providers/index.js";
-import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { completeWithResolvedCredentials } from "../providers/model-call.js";
+import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { partitionAttachmentsByReference } from "./note-attachment-sync.js";
 import { buildNoteAgentContextArtifact, getCachedNoteAgentContextArtifact } from "./agent-context.js";
 import { revokeNoteShareRecords } from "../share/note-share-revocation.js";

package/dist/src/observability/runtime.js

@@ -1,8 +1,8 @@
 import { init_context, runWithLogContext } from "../utils/logger/context.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { TracingConfigSchema, defaultTracingConfig, init_config } from "./config.js";
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { LangfuseTarget } from "./langfuse.js";
 import { boundedJson, redactString } from "./sanitize.js";
 import { LocalTraceStore } from "./store.js";

package/dist/src/personal-agent/proactivity/service.js

@@ -6,13 +6,13 @@ import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { init_session_instance_repository, readCurrentTranscriptId } from "../../storage/sqlite/session-instance-repository.js";
 import { appendTranscriptEntry, init_transcript_repository } from "../../storage/sqlite/transcript-repository.js";
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
+import { completeWithResolvedCredentials } from "../../providers/model-call.js";
 import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
 import { getPersonalAgent } from "../repository.js";
 import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { enqueueDue, enqueueWakeup, getAttention, getAttentionSources, getProactivitySettings, isQuiet, listAttention, localDay, preparationStrategy, recordFeedback, reserveModelCall, saveAttention, sourceFingerprint, userText } from "./repository.js";
-import { completeWithResolvedCredentials } from "../../providers/model-call.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../../providers/model-response.js";
 import { emitSessionTranscriptUpdate } from "../../session/transcript-events.js";
 import { PERSONAL_PERSONA_GUIDANCE } from "../persona.js";
 import { personalConversationState } from "../conversation-state.js";

package/dist/src/personal-agent/reply-composer.js

@@ -9,12 +9,12 @@ import { appendTranscriptEntry, init_transcript_repository, loadLlmMessagesForSe
 import { getSessionConfig, init_config_repository } from "../storage/sqlite/config-repository.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, resolveAgentProfileDir } from "../agent/agent-scope.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { init_providers, resolveModel } from "../providers/index.js";
+import { completeWithResolvedCredentials } from "../providers/model-call.js";
 import { getPersonalAgentByConversation } from "./repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { loadProfileBootstrapFiles } from "../agent/bootstrap/load-bootstrap-files.js";
-import { completeWithResolvedCredentials } from "../providers/model-call.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { emitSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { PERSONAL_PERSONA_GUIDANCE } from "./persona.js";
 import { PERSONAL_REPLY_EXAMPLES, PERSONAL_REPLY_STYLE_RULES } from "./reply-style.js";

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

@@ -66,9 +66,9 @@ export declare const RuntimeCommandSchema: z.ZodObject<{
                     read: "read";
                     write: "write";
                     execute: "execute";
+                    purchase: "purchase";
                     admin: "admin";
                     send: "send";
-                    purchase: "purchase";
                     publish: "publish";
                 }>>;
             }, z.core.$strict>;

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

@@ -152,9 +152,9 @@ export declare const AgentManifestSchema: z.ZodObject<{
             read: "read";
             write: "write";
             execute: "execute";
+            purchase: "purchase";
             admin: "admin";
             send: "send";
-            purchase: "purchase";
             publish: "publish";
         }>>;
     }, z.core.$strict>;

package/dist/src/platform/index.js

@@ -1,5 +1,5 @@
-import { init_resolution, resolveConnectedPlatformDiscovery, resolveConnectedPlatformEndpoint, setActivePlatformDiscovery } from "./resolution.js";
 import { AgentManifestSchema, PlatformCapabilitySchema, PlatformConfigSchema, PlatformDiscoverySchema, PlatformEventSchema, init_contracts } from "./contracts.js";
+import { init_resolution, resolveConnectedPlatformDiscovery, resolveConnectedPlatformEndpoint, setActivePlatformDiscovery } from "./resolution.js";
 import { PLATFORM_RUNTIME_PROFILE, PLATFORM_RUNTIME_PROVIDER, PlatformRuntimeClient, RuntimeCommandSchema, discoverPlatform } from "./client.js";
 import { processRuntimeCommand } from "./worker.js";
 //#region src/platform/index.ts

package/dist/src/providers/index.js

@@ -1,12 +1,12 @@
 import { __esmMin, __exportAll } from "../../_virtual/_rolldown/runtime.js";
+import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { assertCurrentModelProvider, init_provider_policy, isRetiredModelProvider } from "./provider-policy.js";
 import { PROVIDER_ENV_MAP, getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
+import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
+import { ModelRegistry, getModelRegistry, init_model_registry, prewarmModelRegistry, resetModelRegistry } from "./model-registry.js";
 import { getModelOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
-import { assertCurrentModelProvider, init_provider_policy, isRetiredModelProvider } from "./provider-policy.js";
 import { CredentialResolver, hasCredentials, init_credentials } from "../auth/credentials.js";
-import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
-import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
-import { ModelRegistry, getModelRegistry, init_model_registry, prewarmModelRegistry, resetModelRegistry } from "./model-registry.js";
 import { EXTENSION_PROVIDER_BASE_URL, init_constants } from "./constants.js";
 import { applyOfficialModelMetadataCorrections, getSupplementalModels, init_model_supplements } from "./model-supplements.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";

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

@@ -1,7 +1,9 @@
 import { init_constants } from "./constants.js";
 import { getApiKey, init_providers } from "./index.js";
 import { createExtensionAwareStreamFn } from "./extension-stream-bridge.js";
+import { withCloudUsageResponse } from "../usage/cloud-receipts.js";
 import { finishAiUsageFromMessage, observeAiUsageStream, startAiUsageCall } from "../usage/recorder.js";
+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_constants();
@@ -25,12 +27,18 @@ async function resolveModelCallApiKey(model, credentialOptions) {
 	return isLocalModelBaseUrl(model.baseUrl) ? "xopc-local" : void 0;
 }
 async function resolveModelCallOptions(model, options = {}, credentialOptions) {
+	assertCloudCreditBudgetActive();
+	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}`);
 	const { temperature, ...rest } = options;
 	return {
 		...rest,
 		apiKey,
+		...model.provider === "xopc-cloud" ? { headers: {
+			...options.headers,
+			...await cloudCreditBudgetHeaders()
+		} } : {},
 		...temperature !== void 0 ? { temperature } : {}
 	};
 }
@@ -54,9 +62,11 @@ async function completeWithResolvedCredentials(model, context, options, credenti
 			return result;
 		}
 		const result = await usageCall.run(() => completeSimple(model, context, resolvedOptions));
+		if (result.errorMessage) reportCloudCreditError(result.errorMessage);
 		finishAiUsageFromMessage(usageCall, result);
 		return result;
 	} catch (error) {
+		reportCloudCreditError(error instanceof Error ? error.message : String(error));
 		usageCall?.finish({
 			status: "failed",
 			errorSummary: error instanceof Error ? error.message : String(error)
@@ -80,7 +90,11 @@ async function createResolvedModelStream(model, context, options, credentialOpti
 		}
 	});
 	try {
-		return observeAiUsageStream(await usageCall.run(() => createExtensionAwareStreamFn()(model, normalizeContext(context), resolvedOptions)), usageCall);
+		const stream = await usageCall.run(() => createExtensionAwareStreamFn()(model, normalizeContext(context), resolvedOptions));
+		stream.result().then((message) => {
+			if (message.errorMessage) reportCloudCreditError(message.errorMessage);
+		}).catch(() => {});
+		return observeAiUsageStream(stream, usageCall);
 	} catch (error) {
 		usageCall?.finish({
 			status: "failed",

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

@@ -1,11 +1,11 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
+import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { resolveModelsJsonPath } from "../config/paths.js";
 import { init_provider_policy, isRetiredModelProvider } from "./provider-policy.js";
-import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { getDefaultModelValues, init_models_json, validateModelsConfig } from "../config/models-json.js";
+import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
 import { existsSync, readFileSync } from "fs";

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;