@xopcai/xopc 0.0.372 → 0.0.374

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/device-access-repository.d.ts

@@ -8,6 +8,7 @@ export type DeviceRecord = {
     platform: DevicePlatform;
     extensionId?: string;
     publicKeyJwk: DevicePublicKeyJwk;
+    requestProofVersion: number;
     scopes: GatewayScope[];
     createdAt: number;
     lastSeenAt?: number;
@@ -45,7 +46,12 @@ export declare function buildRefreshProofMessage(input: {
     nonce: string;
     requestId: string;
     nextRefreshToken: string;
+    requestProofVersion?: number;
 }): string;
+export declare class DeviceRefreshRateLimitError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
 export declare function rotateDeviceRefreshToken(input: {
     refreshToken: string;
     timestamp: number;
@@ -53,6 +59,7 @@ export declare function rotateDeviceRefreshToken(input: {
     requestId: string;
     nextRefreshToken: string;
     signature: string;
+    requestProofVersion?: number;
     now?: number;
 }): DeviceTokenPair;
 export declare function revokeDevice(deviceId: string, now?: number): boolean;

package/dist/src/storage/sqlite/device-access-repository.js

@@ -2,6 +2,8 @@ import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
 import { initialDeviceRefreshTokenSchema } from "../../../packages/gateway-contract/src/device-pairing.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { buckets } from "../../gateway/rate-limit/buckets.js";
+import { init_rate_limit } from "../../gateway/rate-limit/index.js";
 import { init_gateway_scopes, parseGatewayScopes } from "../../gateway/security/gateway-scopes.js";
 import crypto from "node:crypto";
 //#region src/storage/sqlite/device-access-repository.ts
@@ -23,6 +25,7 @@ function deviceFromRow(row) {
 		displayName: row.display_name,
 		platform: row.platform,
 		publicKeyJwk: JSON.parse(row.public_key_jwk),
+		requestProofVersion: row.request_proof_version,
 		...row.extension_id ? { extensionId: row.extension_id } : {},
 		scopes: parseGatewayScopes(row.scopes_json),
 		createdAt: row.created_at,
@@ -109,7 +112,7 @@ function authenticateDeviceAccessToken(token, now = Date.now()) {
 	};
 }
 function buildRefreshProofMessage(input) {
-	return `xopc-device-refresh-v2\n${input.credentialId}\n${input.timestamp}\n${input.nonce}\n${input.requestId}\n${input.nextRefreshToken}`;
+	return `xopc-device-refresh-v2\n${input.credentialId}\n${input.timestamp}\n${input.nonce}\n${input.requestId}\n${input.nextRefreshToken}${input.requestProofVersion ? `\nrequest-proof:${input.requestProofVersion}` : ""}`;
 }
 function verifyRefreshProof(publicKeyJwk, message, signature) {
 	try {
@@ -146,9 +149,17 @@ function rotateDeviceRefreshToken(input) {
 			timestamp: input.timestamp,
 			nonce: input.nonce,
 			requestId: input.requestId,
-			nextRefreshToken: input.nextRefreshToken
+			nextRefreshToken: input.nextRefreshToken,
+			requestProofVersion: input.requestProofVersion
 		});
 		if (!verifyRefreshProof(JSON.parse(deviceRow.public_key_jwk), message, input.signature)) throw new Error("Invalid refresh proof");
+		const refreshBudget = buckets.deviceRefresh().consume(credential.device_id);
+		if (!refreshBudget.allowed) throw new DeviceRefreshRateLimitError(refreshBudget.retryAfterMs);
+		if (deviceRow.request_proof_version > (input.requestProofVersion ?? 0)) throw new Error("Request proof downgrade denied");
+		if (input.requestProofVersion === 1 && deviceRow.request_proof_version === 0) {
+			db.prepare("UPDATE devices SET request_proof_version = 1 WHERE device_id = ?").run(credential.device_id);
+			db.prepare("UPDATE device_access_sessions SET revoked_at = ? WHERE device_id = ? AND revoked_at IS NULL").run(now, credential.device_id);
+		}
 		if (credential.replaced_by === nextParsed.id && credential.rotation_request_id === input.requestId) {
 			const nextCredential = db.prepare(`
         SELECT credential_id, device_id, token_hash, expires_at, replaced_by,
@@ -198,9 +209,10 @@ function revokeDevice(deviceId, now = Date.now()) {
 		return changed;
 	});
 }
-var ACCESS_TOKEN_TTL_MS, REFRESH_TOKEN_TTL_MS, REFRESH_PROOF_MAX_AGE_MS, ACCESS_TOKEN_PREFIX, REFRESH_TOKEN_PREFIX;
+var ACCESS_TOKEN_TTL_MS, REFRESH_TOKEN_TTL_MS, REFRESH_PROOF_MAX_AGE_MS, ACCESS_TOKEN_PREFIX, REFRESH_TOKEN_PREFIX, DeviceRefreshRateLimitError;
 var init_device_access_repository = __esmMin((() => {
 	init_src();
+	init_rate_limit();
 	init_gateway_scopes();
 	init_transaction();
 	ACCESS_TOKEN_TTL_MS = 900 * 1e3;
@@ -208,7 +220,13 @@ var init_device_access_repository = __esmMin((() => {
 	REFRESH_PROOF_MAX_AGE_MS = 300 * 1e3;
 	ACCESS_TOKEN_PREFIX = "xopc_at_";
 	REFRESH_TOKEN_PREFIX = "xopc_rt_";
+	DeviceRefreshRateLimitError = class extends Error {
+		constructor(retryAfterMs) {
+			super("Too many device refresh requests");
+			this.retryAfterMs = retryAfterMs;
+		}
+	};
 }));
 //#endregion
 init_device_access_repository();
-export { authenticateDeviceAccessToken, buildRefreshProofMessage, createDevice, getDevice, init_device_access_repository, issueDeviceTokenPair, listDevices, registerInitialDeviceRefreshToken, revokeDevice, rotateDeviceRefreshToken };
+export { DeviceRefreshRateLimitError, authenticateDeviceAccessToken, buildRefreshProofMessage, createDevice, getDevice, init_device_access_repository, issueDeviceTokenPair, listDevices, registerInitialDeviceRefreshToken, revokeDevice, rotateDeviceRefreshToken };

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/243_voice_opening_greetings.sql

@@ -0,0 +1,12 @@
+CREATE TABLE voice_opening_greetings (
+  principal_id TEXT NOT NULL,
+  conversation_id TEXT NOT NULL,
+  logical_call_id TEXT NOT NULL,
+  response_id TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('claimed', 'completed', 'skipped', 'interrupted', 'failed', 'expired')),
+  reason TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (principal_id, conversation_id, logical_call_id)
+);
+CREATE INDEX idx_voice_opening_greetings_created ON voice_opening_greetings(created_at);

package/dist/src/storage/sqlite/migrations/244_device_request_proofs.sql

@@ -0,0 +1,8 @@
+ALTER TABLE devices ADD COLUMN request_proof_version INTEGER NOT NULL DEFAULT 0;
+CREATE TABLE device_request_nonces (
+  device_id TEXT NOT NULL REFERENCES devices(device_id) ON DELETE CASCADE,
+  nonce TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  PRIMARY KEY (device_id, nonce)
+) WITHOUT ROWID;
+CREATE INDEX device_request_nonces_expiry ON device_request_nonces(expires_at);

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 = 244;
 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 ?? 244;
 	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 ?? 244;
 	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 = 244;
 }));
 //#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: 244,
 		databasePath: fresh ? void 0 : options.databasePath
 	});
 }

package/dist/src/tunnel/broker-client.js

@@ -29,6 +29,8 @@ const registrationResponseSchema = z.object({
 var TunnelBrokerClient = class {
 	constructor(baseUrl) {
 		this.baseUrl = baseUrl;
+		const url = new URL(baseUrl);
+		if (url.protocol !== "https:" || url.username || url.password) throw new Error("Tunnel broker requires HTTPS without URL credentials");
 	}
 	apiUrl(path) {
 		return `${this.baseUrl.replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;

package/dist/src/tunnel/tunnel-config.js

@@ -1,4 +1,4 @@
-import { TunnelConfigSchema, TunnelConsentSchema, init_schema } from "../config/schema.js";
+import { TunnelBrokerUrlSchema, TunnelConfigSchema, TunnelConsentSchema, init_schema } from "../config/schema.js";
 import { getTunnelRegistrationSecretMeta, isMaskedTunnelSecretPatchValue } from "./env.js";
 import { assertTunnelAutoStartAllowed, buildTunnelConsentRecord, hasValidTunnelConsent } from "./consent.js";
 import { z } from "zod";
@@ -6,7 +6,7 @@ import { z } from "zod";
 init_schema();
 const TunnelConfigPatchSchema = z.object({
 	enabled: z.boolean().optional(),
-	brokerUrl: z.string().url().optional(),
+	brokerUrl: TunnelBrokerUrlSchema.optional(),
 	registrationSecret: z.union([z.string(), z.null()]).optional(),
 	autoStart: z.boolean().optional(),
 	subdomain: z.string().optional(),

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

@@ -1,9 +1,10 @@
 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";
 import { createHash } from "node:crypto";
 //#region src/tunnel/tunnel-rate-limit.ts
+init_rate_limit();
 init_logger();
 const log = createLogger("TunnelRateLimit");
 function tokenKey(token) {

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/utils/logger/redact.js

@@ -62,8 +62,9 @@ var init_redact = __esmMin((() => {
 	KEEP_PREFIX_LENGTH = 6;
 	KEEP_SUFFIX_LENGTH = 4;
 	DEFAULT_REDACT_PATTERNS = [
+		/X-Xopc-Proof\s*[:=]\s*([A-Za-z0-9._-]+)/gi,
 		/\b[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD)\b\s*[=:]\s*((?:\\?["'])?)([^\s"'\\]+)\1/gi,
-		/"(?:apiKey|token|secret|password|passwd|accessToken|refreshToken|privateKey)"\s*:\s*"([^"]+)"/gi,
+		/"(?:apiKey|token|secret|password|passwd|accessToken|refreshToken|privateKey|signature|x-xopc-proof)"\s*:\s*"([^"]+)"/gi,
 		/(?:__Host-xopc-session|xopc-local-session)=([A-Za-z0-9_-]{43})/g,
 		/Authorization\s*[:=]\s*Bearer\s+([A-Za-z0-9._\-+=]+)/gi,
 		/\b(sk-[A-Za-z0-9_-]{8,})\b/gi,
@@ -88,6 +89,8 @@ var init_redact = __esmMin((() => {
 		"cookie",
 		"set-cookie",
 		"signedpayload",
+		"signature",
+		"x-xopc-proof",
 		"credential",
 		"credentials"
 	]);

package/dist/src/voice/platform-streams.d.ts

@@ -1,5 +1,11 @@
 import type { StreamingSttOpenRequest, StreamingSttSession } from '../media-understanding/types.js';
 import type { SpeechSynthesisStreamResult } from './tts/speech-provider-types.js';
+export declare class PlatformVoiceError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, status?: number, code?: string);
+    get clientMessage(): string;
+}
 export declare function openPlatformStt(request: StreamingSttOpenRequest): Promise<StreamingSttSession>;
 export declare function openPlatformTts(request: {
     baseUrl: string;

package/dist/src/voice/platform-streams.js

@@ -1,6 +1,22 @@
 import WebSocket from "ws";
 //#region src/voice/platform-streams.ts
 const MAX_BUFFERED_BYTES = 512 * 1024;
+const MAX_ERROR_BODY_BYTES = 16 * 1024;
+var PlatformVoiceError = class extends Error {
+	constructor(message, status, code) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "PlatformVoiceError";
+	}
+	get clientMessage() {
+		if (this.code === "realtime_quota_workspace_budget") return "XOPC Cloud voice workspace budget is exhausted. Increase the workspace budget or choose another voice provider.";
+		if (this.status === 402 || this.code === "realtime_quota_user_credits") return "XOPC Cloud voice has insufficient Credit or quota. Check your Cloud balance and workspace budget, or choose another voice provider.";
+		if (this.status === 401 || this.status === 403) return "XOPC Cloud voice authorization failed. Sign in again and check your access to this voice model.";
+		if (this.status === 429 || this.code?.startsWith("realtime_quota_")) return "XOPC Cloud voice quota or rate limit reached. Try again later or choose another voice provider.";
+		return "XOPC Cloud voice is unavailable. Try again later or choose another voice provider.";
+	}
+};
 function connect(url, token, signal, onEvent, onFailure) {
 	signal.throwIfAborted();
 	const socket = new WebSocket(url, {
@@ -30,15 +46,38 @@ function connect(url, token, signal, onEvent, onFailure) {
 			if (binary) throw new Error("Unexpected platform binary event");
 			const event = JSON.parse(raw.toString());
 			if (!event || typeof event.type !== "string") throw new Error("Invalid platform voice event");
-			if (event.type === "error") throw new Error(event.error?.message ?? "Platform voice failed");
+			if (event.type === "error") throw new PlatformVoiceError(event.error?.message ?? "Platform voice failed", void 0, event.error?.code);
 			onEvent(event);
 		} catch (error) {
 			fail(error instanceof Error ? error : /* @__PURE__ */ new Error("Invalid platform voice event"));
 		}
 	});
 	socket.on("unexpected-response", (_request, response) => {
-		response.resume();
-		fail(/* @__PURE__ */ new Error(`Platform voice rejected connection (${response.statusCode})`));
+		const fallback = `Platform voice rejected connection (${response.statusCode})`;
+		let bytes = 0;
+		const chunks = [];
+		const reject = () => {
+			let detail;
+			try {
+				detail = JSON.parse(Buffer.concat(chunks).toString("utf8"))?.error;
+			} catch {}
+			const code = typeof detail?.code === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(detail.code) ? detail.code : void 0;
+			const message = typeof detail?.message === "string" ? detail.message.slice(0, 1e3) : void 0;
+			fail(new PlatformVoiceError(`${fallback}${code ? `: ${code}` : ""}${message ? `: ${message}` : ""}`, response.statusCode, code));
+		};
+		response.on("data", (chunk) => {
+			bytes += chunk.length;
+			if (bytes > MAX_ERROR_BODY_BYTES) {
+				chunks.length = 0;
+				reject();
+				response.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		response.once("end", reject);
+		response.once("error", reject);
+		response.once("aborted", reject);
 	});
 	socket.on("error", fail);
 	socket.on("close", () => fail(/* @__PURE__ */ new Error("Platform voice disconnected before completion")));
@@ -265,4 +304,4 @@ async function openPlatformTts(request) {
 	};
 }
 //#endregion
-export { openPlatformStt, openPlatformTts };
+export { PlatformVoiceError, openPlatformStt, openPlatformTts };