@ai-matrx/api 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
 var chunkFNIYADWI_cjs = require('./chunk-FNIYADWI.cjs');
-var chunkYUDQWDCM_cjs = require('./chunk-YUDQWDCM.cjs');
+var chunkHER22VVH_cjs = require('./chunk-HER22VVH.cjs');
 var chunk2SXAAKGV_cjs = require('./chunk-2SXAAKGV.cjs');
-var chunkBMQI7UET_cjs = require('./chunk-BMQI7UET.cjs');
+var chunk5WJLKYH6_cjs = require('./chunk-5WJLKYH6.cjs');
 var format = require('@ai-matrx/kit/format');
 
 // src/core/protocol.ts
@@ -127,7 +127,7 @@ function buildMatrxRequestBody(body, scope) {
   }
   const bodyOrganizationId = base.organization_id;
   if (scope.organization_id !== void 0 && bodyOrganizationId !== void 0 && (typeof bodyOrganizationId !== "string" || bodyOrganizationId.trim() !== scope.organization_id)) {
-    throw new chunkYUDQWDCM_cjs.OrganizationContextError(
+    throw new chunkHER22VVH_cjs.OrganizationContextError(
       "organization_context_mismatch",
       "Request body organization_id must match the request context organization."
     );
@@ -199,14 +199,14 @@ function parseMatrxNdjsonResponse(response, signal, hooks = {}) {
   };
   async function* events() {
     if (!response.body) {
-      throw new chunkYUDQWDCM_cjs.BackendApiError({
+      throw new chunkHER22VVH_cjs.BackendApiError({
         code: "internal_error",
         detail: "Response has no body",
         userMessage: "No response received from server"
       });
     }
     try {
-      for await (const envelope of chunkYUDQWDCM_cjs.readMatrxNdjsonStream(response.body, {
+      for await (const envelope of chunkHER22VVH_cjs.readMatrxNdjsonStream(response.body, {
         ...signal ? { signal } : {},
         ...hooks.onMalformedLine ? { onMalformedLine: hooks.onMalformedLine } : {},
         ...hooks.onUnknownEnvelope ? { onUnknownEnvelope: hooks.onUnknownEnvelope } : {}
@@ -218,7 +218,7 @@ function parseMatrxNdjsonResponse(response, signal, hooks = {}) {
       if (signal?.aborted || error instanceof Error && error.name === "AbortError") {
         return;
       }
-      const transportError = error instanceof chunkYUDQWDCM_cjs.BackendApiError ? error : new chunkYUDQWDCM_cjs.StreamTransportError({
+      const transportError = error instanceof chunkHER22VVH_cjs.BackendApiError ? error : new chunkHER22VVH_cjs.StreamTransportError({
         detail: error instanceof Error ? error.message : "The response stream ended unexpectedly.",
         details: error,
         ...ids.requestId ? { requestId: ids.requestId } : {}
@@ -235,7 +235,7 @@ async function httpErrorFrom(response) {
   const serverDetail = await response.json().catch(() => void 0);
   return {
     type: response.status >= 400 && response.status < 500 ? "validation_error" : "http_error",
-    message: chunkYUDQWDCM_cjs.extractMatrxErrorMessage(serverDetail) ?? bareStatusSentence(response.status),
+    message: chunkHER22VVH_cjs.extractMatrxErrorMessage(serverDetail) ?? bareStatusSentence(response.status),
     status: response.status,
     serverDetail
   };
@@ -311,7 +311,7 @@ async function sendMatrxRequest(url, init = {}, options = {}) {
     return await fetch(url, { ...init, signal: controller.signal });
   } catch (error) {
     if (timedOut) {
-      throw new chunkYUDQWDCM_cjs.BackendApiError({
+      throw new chunkHER22VVH_cjs.BackendApiError({
         code: "request_timeout",
         detail: `${init.method ?? "GET"} ${url} exceeded ${options.timeoutMs}ms`,
         userMessage: "The request timed out \u2014 please retry.",
@@ -325,7 +325,7 @@ async function sendMatrxRequest(url, init = {}, options = {}) {
   }
 }
 async function readMatrxJsonResponse(response) {
-  if (!response.ok) throw await chunkYUDQWDCM_cjs.parseHttpError(response);
+  if (!response.ok) throw await chunkHER22VVH_cjs.parseHttpError(response);
   if (response.status === 204) return null;
   return await response.json();
 }
@@ -335,7 +335,7 @@ function classifyStatus(status) {
   return status >= 400 && status < 500 ? "validation_error" : "http_error";
 }
 function normalizeMatrxError(err) {
-  if (err instanceof chunkYUDQWDCM_cjs.OrganizationContextError) {
+  if (err instanceof chunkHER22VVH_cjs.OrganizationContextError) {
     return {
       type: "validation_error",
       message: err.message,
@@ -347,7 +347,7 @@ function normalizeMatrxError(err) {
   if (err instanceof DOMException && err.name === "AbortError") {
     return { type: "abort_error", message: "Request was cancelled." };
   }
-  if (err instanceof chunkYUDQWDCM_cjs.MatrxApiError) {
+  if (err instanceof chunkHER22VVH_cjs.MatrxApiError) {
     return {
       type: classifyStatus(err.status),
       message: honestTransportMessage(err.message, err.status),
@@ -357,7 +357,7 @@ function normalizeMatrxError(err) {
       name: err.name
     };
   }
-  if (err instanceof chunkYUDQWDCM_cjs.BackendApiError) {
+  if (err instanceof chunkHER22VVH_cjs.BackendApiError) {
     return {
       type: "network_error",
       message: honestTransportMessage(
@@ -455,9 +455,9 @@ function createMatrxTransport(options) {
   };
   const resolveOrganizationId = (callOrganizationId) => {
     if (organizationId === void 0) return null;
-    if (callOrganizationId !== null) return chunkYUDQWDCM_cjs.requireOrganizationContext(callOrganizationId);
+    if (callOrganizationId !== null) return chunkHER22VVH_cjs.requireOrganizationContext(callOrganizationId);
     const candidate = typeof organizationId === "function" ? organizationId() : organizationId;
-    return chunkYUDQWDCM_cjs.requireOrganizationContext(candidate);
+    return chunkHER22VVH_cjs.requireOrganizationContext(candidate);
   };
   return {
     async fetch(path, init) {
@@ -465,7 +465,7 @@ function createMatrxTransport(options) {
       const callOrganizationId = readOrganizationHeader(init.headers);
       const versionedPath = applyAiApiVersion(path, resolveVersion());
       const url = `${target.baseUrl}${versionedPath}`;
-      const credentialHeaders = credentials ? chunkBMQI7UET_cjs.credentialToHeaders(await credentials.get()) : {};
+      const credentialHeaders = credentials ? chunk5WJLKYH6_cjs.credentialToHeaders(await credentials.get()) : {};
       const policyHeaders = stripContentType(target.policyHeaders ?? {});
       let headers = {
         ...init.headers,
@@ -474,7 +474,7 @@ function createMatrxTransport(options) {
       };
       const orgId = resolveOrganizationId(callOrganizationId);
       if (orgId !== null) {
-        headers = chunkYUDQWDCM_cjs.applyOrganizationContextHeader(headers, orgId);
+        headers = chunkHER22VVH_cjs.applyOrganizationContextHeader(headers, orgId);
       }
       const info = {
         url,
@@ -507,11 +507,11 @@ function createMatrxTransport(options) {
       }
       if (!response.ok && !expectedErrorStatuses?.includes(response.status)) {
         const serverDetail = await response.clone().json().catch(() => void 0);
-        const code = chunkYUDQWDCM_cjs.extractMatrxErrorCode(serverDetail);
+        const code = chunkHER22VVH_cjs.extractMatrxErrorCode(serverDetail);
         diagnostics?.onError?.(
           {
             type: classifyStatus(response.status),
-            message: chunkYUDQWDCM_cjs.extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
+            message: chunkHER22VVH_cjs.extractMatrxErrorMessage(serverDetail) ?? `HTTP ${response.status}`,
             status: response.status,
             serverDetail,
             ...code ? { code } : {}
@@ -841,7 +841,7 @@ async function readServerDetail(response) {
   }
 }
 async function throwApiError(path, response) {
-  throw new chunkYUDQWDCM_cjs.MatrxApiError({
+  throw new chunkHER22VVH_cjs.MatrxApiError({
     status: response.status,
     path,
     serverDetail: await readServerDetail(response)
@@ -862,7 +862,7 @@ function toRunHandle(response, options) {
   return {
     requestId: response.headers.get("X-Request-ID"),
     conversationId: response.headers.get("X-Conversation-ID"),
-    events: chunkYUDQWDCM_cjs.readMatrxNdjsonStream(response.body, {
+    events: chunkHER22VVH_cjs.readMatrxNdjsonStream(response.body, {
       ...options.signal ? { signal: options.signal } : {},
       ...options.maxReadAhead !== void 0 ? { maxReadAhead: options.maxReadAhead } : {},
       ...options.onMalformedLine ? { onMalformedLine: options.onMalformedLine } : {},
@@ -885,7 +885,7 @@ async function requestStream(transport, path, options) {
   });
   if (!response.ok) return throwApiError(path, response);
   if (!response.body) {
-    throw new chunkYUDQWDCM_cjs.MatrxApiError({
+    throw new chunkHER22VVH_cjs.MatrxApiError({
       status: response.status,
       path,
       serverDetail: { code: "missing_response_body" },
@@ -945,7 +945,7 @@ async function getRuntimeOperationStatus(transport, requestId, options = {}) {
       { method: "GET", ...options.signal ? { signal: options.signal } : {} }
     );
   } catch (error) {
-    if (error instanceof chunkYUDQWDCM_cjs.MatrxApiError && error.status === 404) return null;
+    if (error instanceof chunkHER22VVH_cjs.MatrxApiError && error.status === 404) return null;
     throw error;
   }
 }
@@ -960,7 +960,7 @@ async function getRuntimeOperationsByLink(transport, linkKind, linkId, options =
       { method: "GET", ...options.signal ? { signal: options.signal } : {} }
     );
   } catch (error) {
-    if (error instanceof chunkYUDQWDCM_cjs.MatrxApiError && error.status === 404) return null;
+    if (error instanceof chunkHER22VVH_cjs.MatrxApiError && error.status === 404) return null;
     throw error;
   }
 }
@@ -1001,7 +1001,7 @@ async function* followRuntimeOperationEvents(transport, executionId, options = {
       ...options.signal ? { signal: options.signal } : {}
     }
   );
-  const frames = chunkYUDQWDCM_cjs.readMatrxSseStream(
+  const frames = chunkHER22VVH_cjs.readMatrxSseStream(
     response.body,
     options.onIncomplete ? { onIncomplete: options.onIncomplete } : {}
   );
@@ -1204,7 +1204,7 @@ async function openMatrxStream(transport, path, options = {}) {
   return toRunHandle(response, options);
 }
 function withRunOrganization(transport, organizationId) {
-  const orgId = chunkYUDQWDCM_cjs.requireOrganizationContext(organizationId);
+  const orgId = chunkHER22VVH_cjs.requireOrganizationContext(organizationId);
   return {
     fetch: (path, init) => transport.fetch(path, {
       ...init,
@@ -1231,7 +1231,7 @@ async function followWorkflowRunEvents(transport, runId, options) {
     throw error;
   }
   try {
-    for await (const frame of chunkYUDQWDCM_cjs.readMatrxSseStream(
+    for await (const frame of chunkHER22VVH_cjs.readMatrxSseStream(
       response.body
     )) {
       if (frame.event === "end") return { ended: true };
@@ -1277,7 +1277,7 @@ async function resumeOrRejoin(transport, resumeCall, options) {
   } catch (error) {
     const target = readLiveRunRejoin(error);
     if (!target) {
-      if (error instanceof chunkYUDQWDCM_cjs.MatrxApiError && isResumeConflict(error)) {
+      if (error instanceof chunkHER22VVH_cjs.MatrxApiError && isResumeConflict(error)) {
         return { kind: "resume_conflict", error };
       }
       throw error;
@@ -1664,117 +1664,195 @@ async function reportProviderSessionFailure(transport, failure, options = {}) {
   }
 }
 
+// src/core/provider-usage.ts
+var TOKEN_MAX = 5e7;
+var clip2 = (value, max) => value.length > max ? value.slice(0, max) : value;
+var count = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.min(Math.floor(value), TOKEN_MAX) : 0;
+function providerSessionUsageBody(usage) {
+  const seconds = typeof usage.seconds === "number" && Number.isFinite(usage.seconds) && usage.seconds > 0 ? Math.min(usage.seconds, 86400) : 0;
+  return {
+    provider: usage.provider,
+    model: clip2(usage.model, 200),
+    usage_id: clip2(usage.usage_id, 200),
+    input_tokens: count(usage.input_tokens),
+    output_tokens: count(usage.output_tokens),
+    cached_input_tokens: count(usage.cached_input_tokens),
+    characters: count(usage.characters),
+    seconds
+  };
+}
+function isEmptyProviderUsage(usage) {
+  return !usage.usage_id?.trim() || !usage.model?.trim() || count(usage.input_tokens) === 0 && count(usage.output_tokens) === 0 && count(usage.cached_input_tokens) === 0 && count(usage.characters) === 0 && !(typeof usage.seconds === "number" && usage.seconds > 0);
+}
+async function reportProviderSessionUsage(transport, usage, options = {}) {
+  try {
+    await requestJson(transport, "/broker/usage", {
+      method: "POST",
+      body: providerSessionUsageBody(usage),
+      ...options.signal ? { signal: options.signal } : {}
+    });
+    return "ok";
+  } catch (error) {
+    if (error instanceof chunkHER22VVH_cjs.MatrxApiError) {
+      const status = error.status;
+      if (status >= 400 && status < 500 && status !== 401 && status !== 408 && status !== 425 && status !== 429) {
+        console.warn(`[provider-usage] server refused ${usage.provider} usage ${usage.usage_id} (${status})`);
+        return "drop";
+      }
+    }
+    return "retry";
+  }
+}
+var DEFAULT_RETRY_DELAYS_MS = [1e3, 4e3, 15e3, 6e4, 18e4];
+function createProviderUsageReporter(options) {
+  const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const seen = /* @__PURE__ */ new Set();
+  const inflight = /* @__PURE__ */ new Set();
+  async function deliver(usage) {
+    for (let attempt2 = 0; ; attempt2 += 1) {
+      let result;
+      try {
+        result = await options.send(usage);
+      } catch {
+        result = "retry";
+      }
+      if (result !== "retry") return;
+      if (attempt2 >= delays.length) {
+        console.warn(`[provider-usage] gave up delivering ${usage.provider} usage ${usage.usage_id}`);
+        seen.delete(`${usage.provider}:${usage.usage_id}`);
+        return;
+      }
+      await sleep(delays[attempt2] ?? 0);
+    }
+  }
+  return {
+    report(usage) {
+      if (isEmptyProviderUsage(usage)) return;
+      const key = `${usage.provider}:${usage.usage_id}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      const task = deliver(usage).finally(() => inflight.delete(task));
+      inflight.add(task);
+    },
+    async flush() {
+      while (inflight.size > 0) await Promise.all([...inflight]);
+    },
+    pending: () => inflight.size
+  };
+}
+
 Object.defineProperty(exports, "monitorStream", {
   enumerable: true,
   get: function () { return chunkFNIYADWI_cjs.monitorStream; }
 });
 Object.defineProperty(exports, "BackendApiError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.BackendApiError; }
+  get: function () { return chunkHER22VVH_cjs.BackendApiError; }
 });
 Object.defineProperty(exports, "CONTRACT_SHA256", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.CONTRACT_SHA256; }
+  get: function () { return chunkHER22VVH_cjs.CONTRACT_SHA256; }
 });
 Object.defineProperty(exports, "DEPLOYMENTS", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.DEPLOYMENTS; }
+  get: function () { return chunkHER22VVH_cjs.DEPLOYMENTS; }
 });
 Object.defineProperty(exports, "DOMAINS", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.DOMAINS; }
+  get: function () { return chunkHER22VVH_cjs.DOMAINS; }
 });
 Object.defineProperty(exports, "MatrxApiError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.MatrxApiError; }
+  get: function () { return chunkHER22VVH_cjs.MatrxApiError; }
 });
 Object.defineProperty(exports, "OrganizationContextError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.OrganizationContextError; }
+  get: function () { return chunkHER22VVH_cjs.OrganizationContextError; }
 });
 Object.defineProperty(exports, "StreamTransportError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.StreamTransportError; }
+  get: function () { return chunkHER22VVH_cjs.StreamTransportError; }
 });
 Object.defineProperty(exports, "applyOrganizationContextHeader", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.applyOrganizationContextHeader; }
+  get: function () { return chunkHER22VVH_cjs.applyOrganizationContextHeader; }
 });
 Object.defineProperty(exports, "assertOrganizationMatchesOperation", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.assertOrganizationMatchesOperation; }
+  get: function () { return chunkHER22VVH_cjs.assertOrganizationMatchesOperation; }
 });
 Object.defineProperty(exports, "assertQueryOrganizationMatchesContext", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.assertQueryOrganizationMatchesContext; }
+  get: function () { return chunkHER22VVH_cjs.assertQueryOrganizationMatchesContext; }
 });
 Object.defineProperty(exports, "createApi", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.createApi; }
+  get: function () { return chunkHER22VVH_cjs.createApi; }
 });
 Object.defineProperty(exports, "createOrganizationOperation", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.createOrganizationOperation; }
+  get: function () { return chunkHER22VVH_cjs.createOrganizationOperation; }
 });
 Object.defineProperty(exports, "describeBackendFailure", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.describeBackendFailure; }
+  get: function () { return chunkHER22VVH_cjs.describeBackendFailure; }
 });
 Object.defineProperty(exports, "extractMatrxErrorCode", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.extractMatrxErrorCode; }
+  get: function () { return chunkHER22VVH_cjs.extractMatrxErrorCode; }
 });
 Object.defineProperty(exports, "extractMatrxErrorMessage", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.extractMatrxErrorMessage; }
+  get: function () { return chunkHER22VVH_cjs.extractMatrxErrorMessage; }
 });
 Object.defineProperty(exports, "getUserMessage", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.getUserMessage; }
+  get: function () { return chunkHER22VVH_cjs.getUserMessage; }
 });
 Object.defineProperty(exports, "isGenericUserMessage", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.isGenericUserMessage; }
+  get: function () { return chunkHER22VVH_cjs.isGenericUserMessage; }
 });
 Object.defineProperty(exports, "isStreamTransportLost", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.isStreamTransportLost; }
+  get: function () { return chunkHER22VVH_cjs.isStreamTransportLost; }
 });
 Object.defineProperty(exports, "openJsonOrStream", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.openJsonOrStream; }
+  get: function () { return chunkHER22VVH_cjs.openJsonOrStream; }
 });
 Object.defineProperty(exports, "openStream", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.openStream; }
+  get: function () { return chunkHER22VVH_cjs.openStream; }
 });
 Object.defineProperty(exports, "parseCallApiError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.parseCallApiError; }
+  get: function () { return chunkHER22VVH_cjs.parseCallApiError; }
 });
 Object.defineProperty(exports, "parseHttpError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.parseHttpError; }
+  get: function () { return chunkHER22VVH_cjs.parseHttpError; }
 });
 Object.defineProperty(exports, "parseHttpErrorBody", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.parseHttpErrorBody; }
+  get: function () { return chunkHER22VVH_cjs.parseHttpErrorBody; }
 });
 Object.defineProperty(exports, "parsePersistedBackendError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.parsePersistedBackendError; }
+  get: function () { return chunkHER22VVH_cjs.parsePersistedBackendError; }
 });
 Object.defineProperty(exports, "parseStreamError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.parseStreamError; }
+  get: function () { return chunkHER22VVH_cjs.parseStreamError; }
 });
 Object.defineProperty(exports, "requireOrganizationContext", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.requireOrganizationContext; }
+  get: function () { return chunkHER22VVH_cjs.requireOrganizationContext; }
 });
 Object.defineProperty(exports, "unwrapUpstreamError", {
   enumerable: true,
-  get: function () { return chunkYUDQWDCM_cjs.unwrapUpstreamError; }
+  get: function () { return chunkHER22VVH_cjs.unwrapUpstreamError; }
 });
 Object.defineProperty(exports, "AbortedError", {
   enumerable: true,
@@ -1834,19 +1912,19 @@ Object.defineProperty(exports, "withRetry", {
 });
 Object.defineProperty(exports, "API_KEY_PREFIX", {
   enumerable: true,
-  get: function () { return chunkBMQI7UET_cjs.API_KEY_PREFIX; }
+  get: function () { return chunk5WJLKYH6_cjs.API_KEY_PREFIX; }
 });
 Object.defineProperty(exports, "MATRX_HEADERS", {
   enumerable: true,
-  get: function () { return chunkBMQI7UET_cjs.MATRX_HEADERS; }
+  get: function () { return chunk5WJLKYH6_cjs.MATRX_HEADERS; }
 });
 Object.defineProperty(exports, "credentialToHeaders", {
   enumerable: true,
-  get: function () { return chunkBMQI7UET_cjs.credentialToHeaders; }
+  get: function () { return chunk5WJLKYH6_cjs.credentialToHeaders; }
 });
 Object.defineProperty(exports, "toCredentialsPort", {
   enumerable: true,
-  get: function () { return chunkBMQI7UET_cjs.toCredentialsPort; }
+  get: function () { return chunk5WJLKYH6_cjs.toCredentialsPort; }
 });
 exports.MATRX_AI_API_VERSION_DEFAULT = MATRX_AI_API_VERSION_DEFAULT;
 exports.MATRX_LIVE_STREAM_UNAVAILABLE = MATRX_LIVE_STREAM_UNAVAILABLE;
@@ -1870,6 +1948,7 @@ exports.buildSafeRequestLog = buildSafeRequestLog;
 exports.continueEphemeralConversationStart = continueEphemeralConversationStart;
 exports.continueStoredConversationStart = continueStoredConversationStart;
 exports.createMatrxTransport = createMatrxTransport;
+exports.createProviderUsageReporter = createProviderUsageReporter;
 exports.createStreamReplayCursor = createStreamReplayCursor;
 exports.createWarmup = createWarmup;
 exports.encodePathSegment = encodePathSegment;
@@ -1885,6 +1964,7 @@ exports.getRuntimeOperationsByLink = getRuntimeOperationsByLink;
 exports.honestTransportMessage = honestTransportMessage;
 exports.isBareTransportCode = isBareTransportCode;
 exports.isCoveredAiPath = isCoveredAiPath;
+exports.isEmptyProviderUsage = isEmptyProviderUsage;
 exports.isJobOutputKind = isJobOutputKind;
 exports.isLiveStreamUnavailable = isLiveStreamUnavailable;
 exports.isResumeConflict = isResumeConflict;
@@ -1901,6 +1981,7 @@ exports.parseMatrxNdjsonResponse = parseMatrxNdjsonResponse;
 exports.pickServerJobOperation = pickServerJobOperation;
 exports.preconnectServer = preconnectServer;
 exports.providerSessionFailureBody = providerSessionFailureBody;
+exports.providerSessionUsageBody = providerSessionUsageBody;
 exports.readConversationOrganizationId = readConversationOrganizationId;
 exports.readLiveRunRejoin = readLiveRunRejoin;
 exports.readLiveRunRequestId = readLiveRunRequestId;
@@ -1912,6 +1993,7 @@ exports.readStreamCursor = readStreamCursor;
 exports.redactUrlForRequestLog = redactUrlForRequestLog;
 exports.rejoinRuntimeOperation = rejoinRuntimeOperation;
 exports.reportProviderSessionFailure = reportProviderSessionFailure;
+exports.reportProviderSessionUsage = reportProviderSessionUsage;
 exports.requestJson = requestJson;
 exports.requestStream = requestStream;
 exports.resetPreconnectedForTests = resetPreconnectedForTests;

package/dist/index.d.cts

@@ -2003,4 +2003,67 @@ declare function reportProviderSessionFailure(transport: MatrxTransport, failure
     signal?: AbortSignal;
 }): Promise<ProviderSessionFailureVerdict | null>;
 
-export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, type CreateWarmupOptions, CredentialsPort, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, type FollowRuntimeOperationOptions, type FollowRuntimeOperationToEndOptions, type FollowRuntimeOperationToEndResult, type FollowServerJobOptions, type FollowUnavailableRejoinOptions, type JsonRequestOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxChatMessage, type MatrxClientSessionProvider, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, type MatrxJsonObject, type MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, type MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, type MatrxRuntimeExecutionStatus, type MatrxRuntimeOperationEvent, type MatrxRuntimeOperationView, type MatrxStoredConversationContinue, type MatrxStoredConversationCreate, type MatrxStreamCallOptions, type MatrxStreamCursorStamp, type MatrxStreamIds, type MatrxStreamParse, type MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportRequest, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type QueryValue, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, ResilientFetchOptions, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SendMatrxRequestOptions, type ServerJobFinalStatus, type ServerJobOutcome, type ServerJobPath, type ServerJobStatus, type ServerJobTarget, type SettleRunPickupOptions, type StreamReplayCursor, type StreamReplayCursorOptions, type StreamRequestOptions, StreamTransportError, TERMINAL_MATRX_RUNTIME_STATUSES, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, type WarmItem, type WarmReason, type Warmup, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createOrganizationOperation, createStreamReplayCursor, createWarmup, describeBackendFailure, encodePathSegment, executeMatrxCall, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isStreamTransportLost, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, pickServerJobOperation, preconnectServer, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, requestJson, requestStream, requireOrganizationContext, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, unwrapUpstreamError, withRunOrganization };
+/**
+ * Browser-held provider sessions report what they spent.
+ *
+ * Realtime voice (OpenAI / xAI) and Cartesia TTS are spent browser -> provider on a
+ * broker-minted ephemeral token, so no server seam sees the money. Every such session reports
+ * the provider's own usage once per billed unit; the server prices it through the AI catalog
+ * (a client never states a cost) and bills the signed-in person in their active organization.
+ *
+ * Server truth: `POST /broker/usage` (`ProviderSessionUsageReport`, `extra="forbid"`). A
+ * `usage_id` bills ONCE — so a repeat send is always safe, which is what lets the reporter
+ * retry freely.
+ *
+ * Two layers:
+ *  - `reportProviderSessionUsage(transport, usage)` - one attempt, classified, never throws;
+ *  - `createProviderUsageReporter({ send })` - the queue every session uses: retries
+ *    transient failures with backoff, drops permanent refusals (4xx), de-duplicates by
+ *    `usage_id`, and `flush()` drains it when a session ends.
+ */
+
+/** One billed unit: a realtime response, a TTS generation, or a slice of session time. */
+interface ProviderSessionUsage {
+    provider: MatrxClientSessionProvider;
+    model: string;
+    /** The provider's own response / generation id; bills once. */
+    usage_id: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    cached_input_tokens?: number;
+    characters?: number;
+    seconds?: number;
+}
+interface ProviderSessionUsageReceipt {
+    billed: boolean;
+    duplicate: boolean;
+    cost_usd: number;
+}
+/** `ok` = the server has it (billed or already had it). `retry` = transient. `drop` = refused for good. */
+type ProviderUsageSendResult = "ok" | "retry" | "drop";
+/** The body the server accepts — bounded exactly as its model bounds it. */
+declare function providerSessionUsageBody(usage: ProviderSessionUsage): Record<string, string | number>;
+/** True when the unit carries nothing the server could price. */
+declare function isEmptyProviderUsage(usage: ProviderSessionUsage): boolean;
+/** One attempt over the transport. Never throws; the result says whether to try again. */
+declare function reportProviderSessionUsage(transport: MatrxTransport, usage: ProviderSessionUsage, options?: {
+    signal?: AbortSignal;
+}): Promise<ProviderUsageSendResult>;
+interface ProviderUsageReporterOptions {
+    send: (usage: ProviderSessionUsage) => Promise<ProviderUsageSendResult>;
+    /** Delay before each retry; its length is the retry budget. */
+    retryDelaysMs?: readonly number[];
+    /** Injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+interface ProviderUsageReporter {
+    /** Queue a unit. Synchronous, never throws. A usage_id already queued or sent is ignored. */
+    report(usage: ProviderSessionUsage): void;
+    /** Resolves when everything queued so far has been delivered or given up on. */
+    flush(): Promise<void>;
+    /** Units still waiting on delivery. */
+    pending(): number;
+}
+declare function createProviderUsageReporter(options: ProviderUsageReporterOptions): ProviderUsageReporter;
+
+export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, type CreateWarmupOptions, CredentialsPort, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, type FollowRuntimeOperationOptions, type FollowRuntimeOperationToEndOptions, type FollowRuntimeOperationToEndResult, type FollowServerJobOptions, type FollowUnavailableRejoinOptions, type JsonRequestOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxChatMessage, type MatrxClientSessionProvider, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, type MatrxJsonObject, type MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, type MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, type MatrxRuntimeExecutionStatus, type MatrxRuntimeOperationEvent, type MatrxRuntimeOperationView, type MatrxStoredConversationContinue, type MatrxStoredConversationCreate, type MatrxStreamCallOptions, type MatrxStreamCursorStamp, type MatrxStreamIds, type MatrxStreamParse, type MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportRequest, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type ProviderSessionUsage, type ProviderSessionUsageReceipt, type ProviderUsageReporter, type ProviderUsageReporterOptions, type ProviderUsageSendResult, type QueryValue, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, ResilientFetchOptions, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SendMatrxRequestOptions, type ServerJobFinalStatus, type ServerJobOutcome, type ServerJobPath, type ServerJobStatus, type ServerJobTarget, type SettleRunPickupOptions, type StreamReplayCursor, type StreamReplayCursorOptions, type StreamRequestOptions, StreamTransportError, TERMINAL_MATRX_RUNTIME_STATUSES, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, type WarmItem, type WarmReason, type Warmup, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createOrganizationOperation, createProviderUsageReporter, createStreamReplayCursor, createWarmup, describeBackendFailure, encodePathSegment, executeMatrxCall, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isEmptyProviderUsage, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isStreamTransportLost, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, pickServerJobOperation, preconnectServer, providerSessionFailureBody, providerSessionUsageBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, reportProviderSessionUsage, requestJson, requestStream, requireOrganizationContext, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, unwrapUpstreamError, withRunOrganization };