@xopcai/xopc 0.0.372 → 0.0.374

package/dist/src/personal-agent/repository.js

@@ -48,6 +48,7 @@ function toRecord(ownerId, agent, session) {
 		userCallName: getUserProfileSnapshot().callName ?? null,
 		appearance: appearanceFrom(agent),
 		voicePreference: agent.profile?.voicePreference ?? null,
+		voiceCallPreferences: agent.profile?.voiceCallPreferences ?? { openingGreetingEnabled: true },
 		preferences: agent.profile?.responsePreferences ?? DEFAULT_PERSONAL_PREFERENCES,
 		revision: agent.revision,
 		errorMessage: agent.provisioningError ?? null

package/dist/src/personal-agent/service.d.ts

@@ -63,9 +63,13 @@ export declare function patchPersonalProfile(service: PersonalAgentHost, ownerId
     provider: string;
     model: string;
     voice: string;
-} | null): Promise<PersonalAgentRecord | null>;
+} | null, voiceCallPreferences?: {
+    openingGreetingEnabled: boolean;
+}): Promise<PersonalAgentRecord | null>;
 export declare function updatePersonalProfileRecord(ownerId: string, revision: number, displayName: string, preferences: PersonalPreferences, appearance: PersonalAppearance, voicePreference?: {
     provider: string;
     model: string;
     voice: string;
-} | null): Promise<PersonalAgentRecord | null>;
+} | null, voiceCallPreferences?: {
+    openingGreetingEnabled: boolean;
+}): Promise<PersonalAgentRecord | null>;

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

@@ -159,14 +159,14 @@ async function provisionPersonalAgent(service, ownerId, requestedModel, availabl
 	completePersonalOnboarding(ownerId);
 	return getPersonalAgent(ownerId) ?? record;
 }
-async function patchPersonalProfile(service, ownerId, revision, displayName, preferences, appearance, voicePreference) {
-	const updated = await updatePersonalProfileRecord(ownerId, revision, displayName, preferences, appearance, voicePreference);
+async function patchPersonalProfile(service, ownerId, revision, displayName, preferences, appearance, voicePreference, voiceCallPreferences) {
+	const updated = await updatePersonalProfileRecord(ownerId, revision, displayName, preferences, appearance, voicePreference, voiceCallPreferences);
 	if (!updated) return null;
 	service.refreshAgentCatalog();
 	service.agentService.evictSessionAgent(updated.conversationId);
 	return updated;
 }
-async function updatePersonalProfileRecord(ownerId, revision, displayName, preferences, appearance, voicePreference) {
+async function updatePersonalProfileRecord(ownerId, revision, displayName, preferences, appearance, voicePreference, voiceCallPreferences) {
 	const current = new AgentCatalogRepository().get(personalAgentId(ownerId));
 	if (!current || current.provisioningState !== "ready" || current.revision !== revision || getPersonalAgent(ownerId)?.state !== "ready") return null;
 	const profile = {
@@ -175,6 +175,7 @@ async function updatePersonalProfileRecord(ownerId, revision, displayName, prefe
 		emoji: appearanceEmoji(appearance),
 		avatar: appearanceAvatar(appearance),
 		...voicePreference !== void 0 ? { voicePreference: voicePreference ?? void 0 } : {},
+		...voiceCallPreferences ? { voiceCallPreferences } : {},
 		responsePreferences: preferences,
 		instructions: personalInstructions(preferences)
 	};

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

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

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

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

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/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-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/realtime/runtime.js

@@ -3,6 +3,7 @@ import { init_logger } from "../utils/logger.js";
 import { hasGatewayScope, init_gateway_scopes } from "../gateway/security/gateway-scopes.js";
 import { EndpointToolPolicyError } from "../endpoint-tools/policy.js";
 import { REALTIME_CAPABILITIES, REALTIME_HEARTBEAT_INTERVAL_MS, REALTIME_HEARTBEAT_TIMEOUT_MS, REALTIME_HELLO_TIMEOUT_MS, REALTIME_MAX_CLIENT_FRAME_BYTES, parseClientRealtimeJsonFrame, parseClientRealtimeMessage } from "../../packages/realtime-protocol/src/index.js";
+import { verifyDeviceConnectionProof } from "../gateway/security/device-request-proof.js";
 import { compactRunEvent } from "./compact-run-event.js";
 import { createPreauthConnectionBudget } from "../gateway/security/preauth-connection-budget.js";
 import { RealtimeBroker } from "./broker.js";
@@ -221,6 +222,11 @@ var RealtimeRuntime = class {
 					socket.close(4401, "First realtime message must be hello");
 					return;
 				}
+				const pendingClaim = this.tickets.peek(message.payload.ticket);
+				if (!pendingClaim || pendingClaim.deviceId && !verifyDeviceConnectionProof(pendingClaim.deviceId, message.payload.ticket, new URL(request.url, "http://localhost").pathname + new URL(request.url, "http://localhost").search, typeof request.headers["x-xopc-proof"] === "string" ? request.headers["x-xopc-proof"] : void 0)) {
+					socket.close(4401, "Realtime authentication failed");
+					return;
+				}
 				const claim = this.tickets.consume(message.payload.ticket, message.payload.clientId, message.payload.clientKind);
 				if (!claim || !this.isPrincipalActive(claim.principalId)) {
 					socket.close(4401, "Realtime authentication failed");

package/dist/src/realtime/tickets.d.ts

@@ -15,6 +15,7 @@ export interface IssuedRealtimeTicket extends RealtimeTicketClaim {
 export declare class RealtimeTicketStore {
     private readonly claims;
     issue(clientId: string, clientKind: RealtimeClientKind, principal: Omit<RealtimeTicketClaim, 'clientId' | 'clientKind' | 'expiresAt'>, now?: number): IssuedRealtimeTicket;
+    peek(ticket: string, now?: number): RealtimeTicketClaim | undefined;
     consume(ticket: string, clientId: string, clientKind: RealtimeClientKind, now?: number): RealtimeTicketClaim | undefined;
     revokePrincipal(principalId: string): void;
     private prune;

package/dist/src/realtime/tickets.js

@@ -23,6 +23,10 @@ var RealtimeTicketStore = class {
 			...claim
 		};
 	}
+	peek(ticket, now = Date.now()) {
+		const claim = this.claims.get(ticketKey(ticket));
+		return claim && claim.expiresAt >= now ? claim : void 0;
+	}
 	consume(ticket, clientId, clientKind, now = Date.now()) {
 		const key = ticketKey(ticket);
 		const claim = this.claims.get(key);

package/dist/src/remote-access/exposure-guards.js

@@ -1,7 +1,8 @@
-import { isLoopbackHost } from "../gateway/host.js";
+import { init_host, isLoopbackHost } from "../gateway/host.js";
 import { resolveGatewayBindMode } from "../config/gateway-bind.js";
 import { resolveGatewayListenPlan } from "../gateway/listen.js";
 //#region src/remote-access/exposure-guards.ts
+init_host();
 function collectExposureConflicts(cfg) {
 	const conflicts = [];
 	const tailscaleMode = cfg.gateway?.tailscale?.mode ?? "off";

package/dist/src/share/share-rate-limit.js

@@ -1,8 +1,9 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { buckets } from "../gateway/rate-limit/buckets.js";
-import "../gateway/rate-limit/index.js";
+import { init_rate_limit } from "../gateway/rate-limit/index.js";
 //#region src/share/share-rate-limit.ts
+init_rate_limit();
 init_logger();
 const log = createLogger("ShareRateLimit");
 /**

package/dist/src/share/share-url.js

@@ -1,6 +1,7 @@
-import { enumerateLanGatewayCandidates } from "../gateway/host.js";
+import { enumerateLanGatewayCandidates, init_host } from "../gateway/host.js";
 import { getTunnelService } from "../tunnel/tunnel-service.js";
 //#region src/share/share-url.ts
+init_host();
 function resolveShareUrl(token, ctx) {
 	const tunnelPublicUrl = activeTunnelPublicUrl();
 	const { gatewayHost, gatewayPort, reverseProxyPublicUrl } = ctx;

package/dist/src/share/site-share-router.js

@@ -1,13 +1,14 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { getClientIpFromHeaders, init_loopback } from "../gateway/security/loopback.js";
 import { resolveSiteShareConfig } from "./site-share-config.js";
 import "./share-store.js";
 import { getSiteShareStore } from "./site-share-store.js";
-import { getClientIpFromHeaders } from "../gateway/security/loopback.js";
 import { serveStaticSiteRequest } from "./site-static-serve.js";
 import { forwardHttpRequest, handleProxyWebSocketUpgrade } from "./site-proxy.js";
 import { renderShareExpiredPage } from "./share-landing.js";
 //#region src/share/site-share-router.ts
+init_loopback();
 init_logger();
 const log = createLogger("SiteShareRouter");
 const SITE_SUBPATH_PREFIX = "/site/";

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;