@usagetap/sdk 1.3.1 → 1.4.0

package/dist/openai/index.cjs

@@ -242,6 +242,11 @@ async function compressMessagesWithUsageTap(options) {
     aggressiveness,
     "UsageTap prompt message compression"
   );
+  if (options.latencyBudgetMs !== void 0 && (!Number.isFinite(options.latencyBudgetMs) || options.latencyBudgetMs < 0)) {
+    throw new Error(
+      "UsageTap prompt message compression latencyBudgetMs must be a non-negative number"
+    );
+  }
   const original = stableStringifyInput(options.input);
   const headers = {
     "content-type": "application/json"
@@ -256,7 +261,15 @@ async function compressMessagesWithUsageTap(options) {
       headers,
       body: JSON.stringify({
         ...cloneInputRecord(options.input),
-        compression_settings: { aggressiveness }
+        compression_settings: {
+          aggressiveness,
+          ...options.mode === void 0 ? {} : { mode: options.mode },
+          ...options.latencyBudgetMs === void 0 ? {} : { latency_budget_ms: options.latencyBudgetMs },
+          ...options.compactEmptyUserMessages === void 0 ? {} : { compact_empty_user_messages: options.compactEmptyUserMessages },
+          ...options.compactDuplicateUserTextParts === void 0 ? {} : {
+            compact_duplicate_user_text_parts: options.compactDuplicateUserTextParts
+          }
+        }
       }),
       signal: options.signal
     }
@@ -752,10 +765,358 @@ function scalarToToon(value) {
   return JSON.stringify(text);
 }
 
+// src/resources.ts
+var CANONICAL_MEDIA_TYPE = "application/vnd.usagetap.v1+json";
+var DEFAULT_GATEWAY_BASE_URL = "https://gateway.usagetap.com";
+function normalizedBaseUrl(value) {
+  return `${value.replace(/\/+$/, "")}/`;
+}
+function errorMessage(payload, status) {
+  if (payload && typeof payload === "object") {
+    const record = payload;
+    const error = record.error;
+    if (error && typeof error === "object") {
+      const message2 = error.message;
+      if (typeof message2 === "string" && message2) return message2;
+    }
+    const message = record.message;
+    if (typeof message === "string" && message) return message;
+  }
+  return `UsageTap request failed with HTTP ${status}`;
+}
+function errorCode(status) {
+  if (status === 401 || status === 403) return "USAGETAP_AUTH_ERROR";
+  if (status === 429) return "USAGETAP_RATE_LIMITED";
+  if (status >= 500) return "USAGETAP_SERVER_ERROR";
+  return "USAGETAP_BAD_REQUEST";
+}
+var ResourceTransport = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  defaultHeaders;
+  sdkVersion;
+  constructor(baseUrl, config) {
+    this.baseUrl = normalizedBaseUrl(baseUrl);
+    this.apiKey = config.apiKey;
+    this.fetchImpl = config.fetchImpl;
+    this.defaultHeaders = config.headers ?? {};
+    this.sdkVersion = config.sdkVersion;
+  }
+  async request(request) {
+    const body = request.body === void 0 ? void 0 : JSON.stringify(request.body);
+    const headers = {
+      ...this.defaultHeaders,
+      accept: request.response === "data" ? CANONICAL_MEDIA_TYPE : request.response === "ndjson" ? "application/x-ndjson" : "application/json",
+      authorization: `Bearer ${this.apiKey}`,
+      "x-usage-sdk": `js/${this.sdkVersion}`,
+      ...body ? { "content-type": "application/json" } : {},
+      ...request.options?.idempotencyKey ? { "idempotency-key": request.options.idempotencyKey } : {},
+      ...request.options?.headers
+    };
+    let response;
+    try {
+      response = await this.fetchImpl(
+        new URL(request.path.replace(/^\/+/, ""), this.baseUrl),
+        {
+          method: request.method,
+          headers,
+          body,
+          signal: request.options?.signal
+        }
+      );
+    } catch (error) {
+      throw new UsageTapError(
+        "USAGETAP_NETWORK_ERROR",
+        "Failed to reach UsageTap",
+        { retryable: true, cause: error }
+      );
+    }
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("x-usage-correlation-id") ?? void 0;
+    const text = await response.text();
+    let payload;
+    if (text && request.response !== "ndjson") {
+      try {
+        payload = JSON.parse(text);
+      } catch (error) {
+        throw new UsageTapError(
+          "USAGETAP_INVALID_RESPONSE",
+          "UsageTap returned invalid JSON",
+          { status: response.status, correlationId: requestId, cause: error }
+        );
+      }
+    }
+    if (!response.ok) {
+      throw new UsageTapError(
+        errorCode(response.status),
+        errorMessage(payload, response.status),
+        {
+          status: response.status,
+          retryable: response.status === 429 || response.status >= 500,
+          correlationId: requestId,
+          details: payload && typeof payload === "object" ? payload : void 0
+        }
+      );
+    }
+    if (request.response === "ndjson") {
+      if (!text.trim()) return [];
+      try {
+        return text.trim().split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+      } catch (error) {
+        throw new UsageTapError(
+          "USAGETAP_INVALID_RESPONSE",
+          "UsageTap returned invalid NDJSON",
+          { status: response.status, correlationId: requestId, cause: error }
+        );
+      }
+    }
+    if (request.response === "data") {
+      if (!payload || typeof payload !== "object" || !("data" in payload)) {
+        throw new UsageTapError(
+          "USAGETAP_INVALID_RESPONSE",
+          "UsageTap response missing data",
+          { status: response.status, correlationId: requestId }
+        );
+      }
+      return payload.data;
+    }
+    if (payload === void 0) {
+      throw new UsageTapError(
+        "USAGETAP_INVALID_RESPONSE",
+        "UsageTap response was empty",
+        { status: response.status, correlationId: requestId }
+      );
+    }
+    return payload;
+  }
+};
+function resourceId(value, keys, label) {
+  const id = typeof value === "string" ? value : keys.map((key) => value[key]).find((candidate) => Boolean(candidate?.trim()));
+  if (!id?.trim()) {
+    throw new UsageTapError(
+      "USAGETAP_BAD_REQUEST",
+      `${label} requires a non-empty ID`
+    );
+  }
+  return id.trim();
+}
+function terminalSummary(status) {
+  return status === "COMPLETE" || status === "FAILED";
+}
+function terminalGatewayBatch(status) {
+  return ["completed", "failed", "expired", "cancelled"].includes(status);
+}
+function validateWaitOptions(options) {
+  const pollIntervalMs = options.pollIntervalMs ?? 1500;
+  const timeoutMs = options.timeoutMs ?? 3 * 6e4;
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) {
+    throw new UsageTapError(
+      "USAGETAP_BAD_REQUEST",
+      "pollIntervalMs must be a non-negative number"
+    );
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+    throw new UsageTapError(
+      "USAGETAP_BAD_REQUEST",
+      "timeoutMs must be a positive number"
+    );
+  }
+  return { pollIntervalMs, timeoutMs };
+}
+var SummarizationResource = class {
+  summaries;
+  batches;
+  profiles;
+  measurements;
+  transport;
+  constructor(config) {
+    this.transport = new ResourceTransport(config.apiBaseUrl, config);
+    this.summaries = {
+      create: (params, options) => this.transport.request({
+        method: "POST",
+        path: "/v1/compression/summaries",
+        body: params,
+        options,
+        response: "data"
+      }),
+      retrieve: (jobId, options) => this.transport.request({
+        method: "GET",
+        path: `/v1/compression/jobs/${encodeURIComponent(
+          resourceId(jobId, ["jobId"], "summaries.retrieve")
+        )}`,
+        options,
+        response: "data"
+      }),
+      wait: (job, options) => this.waitForSummary(job, options)
+    };
+    this.batches = {
+      create: (params, options) => this.transport.request({
+        method: "POST",
+        path: "/v1/compression/batches",
+        body: params,
+        options,
+        response: "data"
+      }),
+      retrieve: (batchId, options) => this.transport.request({
+        method: "GET",
+        path: `/v1/compression/batches/${encodeURIComponent(
+          resourceId(batchId, ["batchId"], "summarization.batches.retrieve")
+        )}`,
+        options,
+        response: "data"
+      }),
+      wait: (batch, options) => this.waitForBatch(batch, options)
+    };
+    this.profiles = {
+      retrieve: (profile, options) => this.transport.request({
+        method: "GET",
+        path: `/v1/compression/profiles/${encodeURIComponent(
+          resourceId(profile, [], "summarization.profiles.retrieve")
+        )}`,
+        options,
+        response: "data"
+      })
+    };
+    this.measurements = {
+      create: (params, options) => this.transport.request({
+        method: "POST",
+        path: "/v1/compression/measurements",
+        body: params,
+        options,
+        response: "data"
+      })
+    };
+  }
+  async waitForSummary(value, options = {}) {
+    const { pollIntervalMs, timeoutMs } = validateWaitOptions(options);
+    const deadline = Date.now() + timeoutMs;
+    let job = typeof value === "string" ? await this.summaries.retrieve(value, options) : value;
+    while (!terminalSummary(job.status)) {
+      if (Date.now() >= deadline) {
+        throw new UsageTapError(
+          "USAGETAP_RETRY_EXHAUSTED",
+          `Summarization job ${job.jobId} did not finish before timeout`,
+          { retryable: true }
+        );
+      }
+      await sleep(pollIntervalMs, options.signal);
+      job = await this.summaries.retrieve(job.jobId, options);
+    }
+    return job;
+  }
+  async waitForBatch(value, options = {}) {
+    const { pollIntervalMs, timeoutMs } = validateWaitOptions(options);
+    const deadline = Date.now() + timeoutMs;
+    let batch = typeof value === "string" ? await this.batches.retrieve(value, options) : value;
+    while (!terminalSummary(batch.status)) {
+      if (Date.now() >= deadline) {
+        throw new UsageTapError(
+          "USAGETAP_RETRY_EXHAUSTED",
+          `Summarization batch ${batch.batchId} did not finish before timeout`,
+          { retryable: true }
+        );
+      }
+      await sleep(pollIntervalMs, options.signal);
+      batch = await this.batches.retrieve(batch.batchId, options);
+    }
+    return batch;
+  }
+};
+var GatewayResource = class {
+  chat;
+  models;
+  batches;
+  transport;
+  idempotencyGenerator;
+  constructor(config) {
+    this.transport = new ResourceTransport(
+      config.gatewayBaseUrl ?? DEFAULT_GATEWAY_BASE_URL,
+      config
+    );
+    this.idempotencyGenerator = config.idempotencyGenerator ?? createIdempotencyKey;
+    this.chat = {
+      completions: {
+        create: (params, options) => this.transport.request({
+          method: "POST",
+          path: "/v1/chat/completions",
+          body: params,
+          options,
+          response: "json"
+        })
+      }
+    };
+    this.models = {
+      list: (options) => this.transport.request({
+        method: "GET",
+        path: "/v1/models",
+        options,
+        response: "json"
+      })
+    };
+    this.batches = {
+      create: (params, options = {}) => this.transport.request({
+        method: "POST",
+        path: "/v1/batches",
+        body: params,
+        options: {
+          ...options,
+          idempotencyKey: options.idempotencyKey ?? this.idempotencyGenerator()
+        },
+        response: "json"
+      }),
+      retrieve: (batchId, options) => this.transport.request({
+        method: "GET",
+        path: `/v1/batches/${encodeURIComponent(
+          resourceId(batchId, ["id"], "gateway.batches.retrieve")
+        )}`,
+        options,
+        response: "json"
+      }),
+      wait: (batch, options) => this.waitForBatch(batch, options),
+      cancel: (batchId, options) => this.transport.request({
+        method: "POST",
+        path: `/v1/batches/${encodeURIComponent(
+          resourceId(batchId, ["id"], "gateway.batches.cancel")
+        )}/cancel`,
+        options,
+        response: "json"
+      }),
+      results: (batchId, options) => this.transport.request({
+        method: "GET",
+        path: `/v1/batches/${encodeURIComponent(
+          resourceId(batchId, ["id"], "gateway.batches.results")
+        )}/results`,
+        options,
+        response: "ndjson"
+      })
+    };
+  }
+  async waitForBatch(value, options = {}) {
+    const { pollIntervalMs, timeoutMs } = validateWaitOptions(options);
+    const deadline = Date.now() + timeoutMs;
+    let batch = typeof value === "string" ? await this.batches.retrieve(value, options) : value;
+    while (!terminalGatewayBatch(batch.status)) {
+      if (Date.now() >= deadline) {
+        throw new UsageTapError(
+          "USAGETAP_RETRY_EXHAUSTED",
+          `Gateway batch ${batch.id} did not finish before timeout`,
+          { retryable: true }
+        );
+      }
+      await sleep(pollIntervalMs, options.signal);
+      batch = await this.batches.retrieve(batch.id, options);
+    }
+    return batch;
+  }
+};
+
 // src/client.ts
 var CALL_BEGIN_PATH = "call_begin";
 var CALL_END_PATH = "call_end";
 var COMPRESS_PROMPT_PATH = "compress_prompt";
+var SAMPLES_PATH = "samples";
+var SAMPLING_SETTINGS_PATH = "sampling/settings";
+var SAMPLING_DECIDE_PATH = "sampling/decide";
 var CHECK_USAGE_PATH = "customers/{customerId}/usage";
 var CREATE_CUSTOMER_PATH = "customers";
 var CHANGE_PLAN_PATH = "customers/{customerId}/change_plan";
@@ -766,11 +1127,16 @@ var CORRELATION_HEADER = "x-usage-correlation-id";
 var IDEMPOTENCY_HEADER = "idempotency-key";
 var SDK_HEADER = "x-usage-sdk";
 var USER_AGENT = "UsageTapClient";
-var CANONICAL_MEDIA_TYPE = "application/vnd.usagetap.v1+json";
+var CANONICAL_MEDIA_TYPE2 = "application/vnd.usagetap.v1+json";
 var DEFAULT_BASE_URL = "https://api.usagetap.com";
-var SDK_VERSION = "1.3.1" ;
+var DEFAULT_RUN_INACTIVITY_MS = 60 * 60 * 1e3;
+var SDK_VERSION = "1.4.0" ;
 var HAS_WINDOW = typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
 var UsageTapClient = class {
+  /** OpenAI-compatible chat, model, and native batch operations. */
+  gateway;
+  /** Published-profile context summarization operations. */
+  summarization;
   apiKey;
   baseUrl;
   fetchImpl;
@@ -795,6 +1161,11 @@ var UsageTapClient = class {
   usageTapCompressionMessagesEndpoint;
   usageTapCompressionModel;
   usageTapCompressionAggressiveness;
+  sampling;
+  samplingSettingsCacheMs;
+  circuitBreaker;
+  circuitBreakerRuns = /* @__PURE__ */ new Map();
+  samplingSettingsCache;
   constructor(options = {}) {
     const apiKey = options.apiKey?.trim() || readEnvironmentVariable("USAGETAP_API_KEY");
     const baseUrl = options.baseUrl?.trim() || readEnvironmentVariable("USAGETAP_BASE_URL") || DEFAULT_BASE_URL;
@@ -817,10 +1188,21 @@ var UsageTapClient = class {
         "A global fetch implementation was not found. Pass fetchImpl in UsageTapClientOptions."
       );
     }
-    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
-    this.baseUrl = new URL(normalizedBaseUrl);
+    const normalizedBaseUrl2 = normalizeBaseUrl(baseUrl);
+    this.baseUrl = new URL(normalizedBaseUrl2);
     this.apiKey = apiKey;
     this.fetchImpl = wrapFetchImplementation(fetchCandidate, !options.fetchImpl);
+    const resourceConfig = {
+      apiKey,
+      apiBaseUrl: normalizedBaseUrl2,
+      gatewayBaseUrl: options.gatewayBaseUrl?.trim() || readEnvironmentVariable("USAGETAP_GATEWAY_URL"),
+      fetchImpl: this.fetchImpl,
+      headers: options.headers,
+      sdkVersion: SDK_VERSION,
+      idempotencyGenerator: options.idempotencyGenerator
+    };
+    this.gateway = new GatewayResource(resourceConfig);
+    this.summarization = new SummarizationResource(resourceConfig);
     this.defaultFeature = options.defaultFeature;
     this.defaultTags = options.defaultTags?.length ? dedupeStrings(options.defaultTags) : void 0;
     this.defaultHeaders = options.headers ? normalizeHeaderDictionary(options.headers) : {};
@@ -842,11 +1224,122 @@ var UsageTapClient = class {
     this.usageTapCompressionMessagesEndpoint = options.usageTapCompressionMessagesEndpoint;
     this.usageTapCompressionModel = options.usageTapCompressionModel;
     this.usageTapCompressionAggressiveness = options.usageTapCompressionAggressiveness;
+    this.sampling = options.sampling;
+    this.samplingSettingsCacheMs = Number.isFinite(options.samplingSettingsCacheMs) ? Math.max(0, Number(options.samplingSettingsCacheMs)) : 5 * 60 * 1e3;
+    if (options.circuitBreaker) {
+      const maxCallsPerRun = options.circuitBreaker.maxCallsPerRun;
+      if (!Number.isInteger(maxCallsPerRun) || maxCallsPerRun < 1) {
+        throw new UsageTapError(
+          "USAGETAP_BAD_REQUEST",
+          "circuitBreaker.maxCallsPerRun must be a positive integer"
+        );
+      }
+      const runInactivityMs = options.circuitBreaker.runInactivityMs ?? DEFAULT_RUN_INACTIVITY_MS;
+      if (!Number.isFinite(runInactivityMs) || runInactivityMs < 1) {
+        throw new UsageTapError(
+          "USAGETAP_BAD_REQUEST",
+          "circuitBreaker.runInactivityMs must be a positive number"
+        );
+      }
+      this.circuitBreaker = {
+        maxCallsPerRun,
+        runInactivityMs
+      };
+    }
+  }
+  shouldSample(request, policy = this.sampling || void 0) {
+    if (!policy) return false;
+    const rate = Math.min(1, Math.max(0, Number(policy.rate) || 0));
+    if (rate <= 0) return false;
+    const customerId = request.customerId?.trim();
+    if (customerId && policy.customers?.exclude?.includes(customerId)) return false;
+    const feature = request.feature?.trim();
+    if (feature && policy.features?.exclude?.includes(feature)) return false;
+    const included = policy.features?.include?.filter(Boolean) ?? [];
+    if (included.length > 0 && (!feature || !included.includes(feature))) return false;
+    const minimum = Math.max(0, Math.round(policy.minInputTokens ?? 0));
+    if (minimum > 0 && estimatePromptTokens(request.input) < minimum) return false;
+    return (policy.random ?? Math.random)() < rate;
+  }
+  async getSamplingSettings(options = {}) {
+    const now = Date.now();
+    if (!options.forceRefresh && this.samplingSettingsCache && this.samplingSettingsCache.expiresAtMs > now) {
+      return {
+        result: { status: "ACCEPTED", code: "SAMPLING_SETTINGS_CACHED" },
+        data: this.samplingSettingsCache.settings,
+        correlationId: options.correlationId ?? "local-cache"
+      };
+    }
+    const response = await this.requestGet(
+      SAMPLING_SETTINGS_PATH,
+      {
+        signal: options.signal,
+        headers: options.headers,
+        retries: options.retries,
+        correlationId: options.correlationId
+      }
+    );
+    const serverCacheMs = Math.max(0, Number(response.data.cacheSeconds) || 0) * 1e3;
+    const cacheMs = Math.min(this.samplingSettingsCacheMs, serverCacheMs);
+    this.samplingSettingsCache = {
+      settings: response.data,
+      expiresAtMs: now + cacheMs
+    };
+    return response;
+  }
+  async shouldSampleAsync(request, policy) {
+    if (policy) return this.shouldSample(request, policy);
+    if (this.sampling === false) return false;
+    if (this.sampling) return this.shouldSample(request, this.sampling);
+    try {
+      const settings = await this.getSamplingSettings();
+      return this.shouldSample(request, settings.data);
+    } catch {
+      return false;
+    }
+  }
+  async decideSample(request, options = {}) {
+    const hasTokens = Number.isFinite(request.inputTokens) && Number(request.inputTokens) >= 0;
+    const hasCharacters = Number.isFinite(request.inputCharacters) && Number(request.inputCharacters) >= 0;
+    if (!hasTokens && !hasCharacters) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "decideSample requires inputTokens or inputCharacters"
+      );
+    }
+    return this.request(
+      SAMPLING_DECIDE_PATH,
+      request,
+      options
+    );
+  }
+  async captureSample(request, options = {}) {
+    if (!request || request.input === void 0) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "captureSample requires input"
+      );
+    }
+    if (!request.provider?.trim()) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "captureSample requires provider"
+      );
+    }
+    const sampleId = request.sampleId?.trim() || this.idempotencyGenerator();
+    return this.request(
+      SAMPLES_PATH,
+      { ...request, sampleId },
+      { ...options, idempotencyKey: sampleId }
+    );
   }
   async beginCall(request, options = {}) {
     const idempotencyKey = request.idempotencyKey ?? request.idempotency ?? (this.autoIdempotency ? this.idempotencyGenerator() : void 0);
+    this.reserveRunCall(request, idempotencyKey);
+    const apiRequest = { ...request };
+    delete apiRequest.runId;
     const payload = {
-      ...request,
+      ...apiRequest,
       feature: request.feature ?? this.defaultFeature,
       tags: this.mergeTags(request.tags)
     };
@@ -864,6 +1357,28 @@ var UsageTapClient = class {
     );
     return response;
   }
+  /**
+   * Inspect a configured run circuit breaker without consuming another call.
+   */
+  canRunContinue(request) {
+    const identity = this.resolveRunIdentity(request);
+    if (!identity || !this.circuitBreaker) {
+      throw new UsageTapError(
+        "USAGETAP_BAD_REQUEST",
+        "canRunContinue requires circuitBreaker configuration and a non-empty runId"
+      );
+    }
+    this.expireInactiveRuns();
+    const calls = this.circuitBreakerRuns.get(identity.key)?.calls ?? 0;
+    return this.createCircuitBreakerDecision(identity.customerId, identity.runId, calls);
+  }
+  /**
+   * Release local state after a workflow finishes. Returns true when state existed.
+   */
+  resetRun(request) {
+    const identity = this.resolveRunIdentity(request);
+    return identity ? this.circuitBreakerRuns.delete(identity.key) : false;
+  }
   async promptCompress(request, options = {}) {
     if (!request?.callId) {
       throw new UsageTapError(
@@ -961,6 +1476,10 @@ var UsageTapClient = class {
       usageTapCompressionMessagesEndpoint: this.usageTapCompressionMessagesEndpoint,
       aggressiveness: options.aggressiveness ?? this.aggressiveness,
       usageTapCompressionAggressiveness: options.usageTapCompressionAggressiveness ?? this.usageTapCompressionAggressiveness,
+      mode: options.mode,
+      latencyBudgetMs: options.latencyBudgetMs,
+      compactEmptyUserMessages: options.compactEmptyUserMessages,
+      compactDuplicateUserTextParts: options.compactDuplicateUserTextParts,
       fetchImpl: this.fetchImpl,
       signal: options.signal,
       failOpen: options.failOpen
@@ -1002,11 +1521,17 @@ var UsageTapClient = class {
       callId: request.callId,
       feature: feature ?? this.defaultFeature,
       tags: tags ?? this.defaultTags,
+      providerUsed: request.providerUsed,
       modelUsed: request.modelUsed,
+      reasoningEffort: request.reasoningEffort,
+      reasoningEffortSource: request.reasoningEffortSource,
+      reasoningMode: request.reasoningMode,
+      reasoningBudgetTokens: request.reasoningBudgetTokens,
       metrics: {
         inputTokens: request.inputTokens,
         responseTokens: request.responseTokens,
         cachedInputTokens: request.cachedInputTokens,
+        cacheWriteInputTokens: request.cacheWriteInputTokens,
         reasoningTokens: request.reasoningTokens,
         searches: request.searches,
         audioSeconds: request.audioSeconds,
@@ -1114,6 +1639,15 @@ var UsageTapClient = class {
       meterSlot: request.meterSlot,
       amount: request.amount
     };
+    if (request.customerUserId) {
+      payload.customerUserId = request.customerUserId;
+    }
+    if (request.customerUserName) {
+      payload.customerUserName = request.customerUserName;
+    }
+    if (request.customerUserEmail) {
+      payload.customerUserEmail = request.customerUserEmail;
+    }
     if (request.feature) {
       payload.feature = request.feature;
     }
@@ -1150,6 +1684,11 @@ var UsageTapClient = class {
     const beginPayload = idempotencyKey ? { ...beginRequest, idempotencyKey, idempotency: idempotencyKey } : { ...beginRequest };
     const beginResponse = await this.beginCall(beginPayload, options);
     let usage = {};
+    const pricingMode = beginResponse.data.pricingMode ?? beginRequest.pricingMode ?? (beginRequest.batch === true ? "batch" : beginRequest.batch === false ? "standard" : void 0);
+    if (pricingMode) {
+      usage.pricingMode = pricingMode;
+      usage.batch = pricingMode === "batch";
+    }
     const initialStripeCustomerId = typeof beginResponse.data.stripeCustomerId === "string" ? beginResponse.data.stripeCustomerId : typeof beginRequest.stripeCustomerId === "string" ? beginRequest.stripeCustomerId : void 0;
     if (initialStripeCustomerId) {
       usage = { ...usage, stripeCustomerId: initialStripeCustomerId };
@@ -1217,17 +1756,86 @@ var UsageTapClient = class {
   toPromptCompressionTelemetry(result) {
     return {
       provider: result.provider,
-      originalCharacters: result.originalCharacters,
-      compressedCharacters: result.compressedCharacters,
-      savedCharacters: result.savedCharacters,
       originalTokens: result.originalTokens,
       compressedTokens: result.compressedTokens,
       savedTokens: result.savedTokens,
       tokenSavingsRatio: result.tokenSavingsRatio,
-      savingsRatio: result.savingsRatio,
       techniques: result.techniques
     };
   }
+  reserveRunCall(request, idempotencyKey) {
+    const identity = this.resolveRunIdentity(request);
+    if (!identity || !this.circuitBreaker) return;
+    this.expireInactiveRuns();
+    const now = Date.now();
+    const state = this.circuitBreakerRuns.get(identity.key) ?? {
+      calls: 0,
+      reservationKeys: /* @__PURE__ */ new Set(),
+      lastSeenAtMs: now
+    };
+    const reservationKey = idempotencyKey ?? this.idempotencyGenerator();
+    state.lastSeenAtMs = now;
+    if (state.reservationKeys.has(reservationKey)) {
+      this.circuitBreakerRuns.set(identity.key, state);
+      return;
+    }
+    const decision = this.createCircuitBreakerDecision(
+      identity.customerId,
+      identity.runId,
+      state.calls
+    );
+    if (!decision.allowed) {
+      throw new UsageTapError(
+        "USAGETAP_CIRCUIT_OPEN",
+        `Run ${identity.runId} reached its ${decision.limit}-call circuit-breaker limit`,
+        {
+          details: {
+            reason: decision.reason,
+            customerId: identity.customerId,
+            runId: identity.runId,
+            calls: decision.calls,
+            limit: decision.limit,
+            remaining: decision.remaining
+          }
+        }
+      );
+    }
+    state.calls += 1;
+    state.reservationKeys.add(reservationKey);
+    this.circuitBreakerRuns.set(identity.key, state);
+  }
+  resolveRunIdentity(request) {
+    const customerId = request.customerId?.trim();
+    const runId = request.runId?.trim();
+    if (!customerId || !runId) return void 0;
+    return {
+      key: `${customerId}\0${runId}`,
+      customerId,
+      runId
+    };
+  }
+  createCircuitBreakerDecision(customerId, runId, calls) {
+    const limit = this.circuitBreaker?.maxCallsPerRun ?? 0;
+    const allowed = calls < limit;
+    return {
+      allowed,
+      ...allowed ? {} : { reason: "max_calls_per_run" },
+      customerId,
+      runId,
+      calls,
+      limit,
+      remaining: Math.max(0, limit - calls)
+    };
+  }
+  expireInactiveRuns() {
+    if (!this.circuitBreaker || this.circuitBreakerRuns.size === 0) return;
+    const expiredBefore = Date.now() - this.circuitBreaker.runInactivityMs;
+    for (const [key, state] of this.circuitBreakerRuns) {
+      if (state.lastSeenAtMs < expiredBefore) {
+        this.circuitBreakerRuns.delete(key);
+      }
+    }
+  }
   async request(path, payload, options) {
     const url = new URL(path, this.baseUrl).toString();
     const body = payload !== void 0 ? JSON.stringify(payload) : void 0;
@@ -1415,7 +2023,7 @@ var UsageTapClient = class {
       ...this.defaultHeaders,
       [SDK_HEADER]: `js/${SDK_VERSION}`,
       "content-type": "application/json",
-      accept: CANONICAL_MEDIA_TYPE
+      accept: CANONICAL_MEDIA_TYPE2
     };
     if (!HAS_WINDOW) {
       headers["user-agent"] = `${USER_AGENT}/${SDK_VERSION}`;
@@ -1616,17 +2224,18 @@ var OpenAIPromptCompressionStats = class {
   }
 };
 function createOpenAIAdapter(init) {
-  const { client, usageTap } = init;
+  const { client, usageTap, provider = "openai" } = init;
   return {
     async invoke(params) {
       const result = await usageTap.withUsage(
         params.begin,
         async (ctx) => {
+          ctx.setUsage({ providerUsed: provider });
           const response = await params.call(client, {
             hints: ctx.begin.data.vendorHints,
             begin: ctx.begin
           });
-          tryInferUsage(response, ctx.begin.data.vendorHints, params.extractUsage, ctx);
+          tryInferUsage(response, ctx.begin.data.vendorHints, params.extractUsage, ctx, provider);
           return {
             data: response,
             begin: ctx.begin
@@ -1640,6 +2249,7 @@ function createOpenAIAdapter(init) {
       const result = await usageTap.withUsage(
         params.begin,
         async (ctx) => {
+          ctx.setUsage({ providerUsed: provider });
           const { stream, onComplete } = await params.call(client, {
             hints: ctx.begin.data.vendorHints,
             begin: ctx.begin
@@ -1765,6 +2375,181 @@ async function pipeToResponse(stream, res, options = {}) {
   }
 }
 var USAGETAP_CORRELATION_HEADER = "x-usage-correlation-id";
+function withSampling(client, options = {}) {
+  if (!client || !options) {
+    throw new UsageTapError(
+      "USAGETAP_BAD_REQUEST",
+      "withSampling requires an OpenAI-compatible client and sampling options"
+    );
+  }
+  const { apiKey, usageTapClient, provider = "openai", ...policy } = options;
+  const localPolicy = typeof policy.rate === "number" ? policy : void 0;
+  const usageTap = usageTapClient ?? new UsageTapClient({ apiKey, sampling: localPolicy });
+  const wrapCreate = (create) => async (params, requestOptions) => {
+    const { usageTap: callContextRaw, ...providerOptions } = requestOptions ?? {};
+    const callContext = isObjectRecord(callContextRaw) ? callContextRaw : {};
+    const streaming = params.stream === true;
+    const decision = streaming ? Promise.resolve(false) : usageTap.shouldSampleAsync({
+      customerId: readString(callContext.customerId),
+      feature: readString(callContext.feature),
+      input: params
+    }, localPolicy);
+    const startedAt = Date.now();
+    try {
+      const response = await create(
+        params,
+        Object.keys(providerOptions).length ? providerOptions : void 0
+      );
+      const selected = await decision;
+      if (selected) {
+        const record = isObjectRecord(response) ? response : {};
+        await usageTap.captureSample({
+          customerId: readString(callContext.customerId),
+          feature: readString(callContext.feature),
+          environment: readString(callContext.environment),
+          tags: readStringArray(callContext.tags),
+          provider,
+          model: readString(record.model) ?? readString(params.model),
+          input: params,
+          output: response,
+          usage: record.usage,
+          latencyMs: Date.now() - startedAt
+        }).catch(() => void 0);
+      }
+      return response;
+    } catch (error) {
+      const selected = await decision;
+      if (selected) {
+        await usageTap.captureSample({
+          customerId: readString(callContext.customerId),
+          feature: readString(callContext.feature),
+          environment: readString(callContext.environment),
+          tags: readStringArray(callContext.tags),
+          provider,
+          model: readString(params.model),
+          input: params,
+          latencyMs: Date.now() - startedAt,
+          error: serializeSamplingError(error)
+        }).catch(() => void 0);
+      }
+      throw error;
+    }
+  };
+  const chat = client.chat?.completions ? new Proxy(client.chat, {
+    get(target, prop, receiver) {
+      if (prop !== "completions") return safeReflectGet(target, prop, receiver);
+      const completions = target.completions;
+      return new Proxy(completions, {
+        get(completionTarget, completionProp, completionReceiver) {
+          if (completionProp === "create") {
+            return wrapCreate(
+              completionTarget.create.bind(completionTarget)
+            );
+          }
+          return safeReflectGet(
+            completionTarget,
+            completionProp,
+            completionReceiver
+          );
+        }
+      });
+    }
+  }) : void 0;
+  const responses = typeof client.responses !== "undefined" && client.responses ? new Proxy(client.responses, {
+    get(target, prop, receiver) {
+      if (prop === "create") {
+        const create = Reflect.get(target, prop, receiver);
+        return wrapCreate(create.bind(target));
+      }
+      return safeReflectGet(target, prop, receiver);
+    }
+  }) : void 0;
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop === "chat" && chat) return chat;
+      if (prop === "responses" && responses) return responses;
+      if (prop === "unwrap") return () => target;
+      return safeReflectGet(target, prop, receiver);
+    }
+  });
+}
+function safeReflectGet(target, prop, receiver) {
+  return Reflect.get(target, prop, receiver);
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const strings = value.filter((item) => typeof item === "string");
+  return strings.length ? strings : void 0;
+}
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function serializeSamplingError(error) {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message };
+  }
+  return { message: String(error) };
+}
+function normalizeMeteredOpenAISampling(options) {
+  if (!options) return void 0;
+  if (options === true) return { provider: "openai" };
+  const { provider = "openai", ...policyFields } = options;
+  return {
+    provider,
+    policy: typeof policyFields.rate === "number" ? policyFields : void 0
+  };
+}
+function startMeteredOpenAISampleDecision({
+  usageTap,
+  sampling,
+  beginRequest,
+  input
+}) {
+  if (!sampling) return Promise.resolve(false);
+  return usageTap.shouldSampleAsync(
+    {
+      customerId: beginRequest.customerId,
+      feature: beginRequest.feature,
+      input
+    },
+    sampling.policy
+  );
+}
+async function captureMeteredOpenAISample({
+  usageTap,
+  sampling,
+  decision,
+  ctx,
+  beginRequest,
+  input,
+  response,
+  error,
+  startedAt
+}) {
+  if (!sampling) return;
+  let selected = false;
+  try {
+    selected = await decision;
+  } catch {
+    return;
+  }
+  if (!selected) return;
+  const record = isObjectRecord(response) ? response : {};
+  await usageTap.captureSample({
+    sampleId: ctx.begin.data.callId,
+    callId: ctx.begin.data.callId,
+    customerId: beginRequest.customerId,
+    feature: beginRequest.feature,
+    tags: beginRequest.tags,
+    provider: sampling.provider,
+    model: readString(record.model) ?? readString(input.model),
+    input,
+    ...response === void 0 ? {} : { output: response },
+    usage: record.usage,
+    latencyMs: Date.now() - startedAt,
+    ...error === void 0 ? {} : { error: serializeSamplingError(error) }
+  }).catch(() => void 0);
+}
 function withCompression(client, options = {}) {
   if (!client) {
     throw new UsageTapError(
@@ -1775,11 +2560,13 @@ function withCompression(client, options = {}) {
   const {
     apiKey,
     usageTapClient,
+    sampling,
     ...compressionOverrides
   } = options;
   const usageTap = usageTapClient ?? new UsageTapClient({ apiKey });
   const compression = {
     provider: "usagetap",
+    roles: { user: { enabled: true, aggressiveness: 0.2 } },
     minContextTokens: DEFAULT_PROMPT_COMPRESSION_MIN_CONTEXT_TOKENS,
     ...compressionOverrides
   };
@@ -1789,7 +2576,7 @@ function withCompression(client, options = {}) {
     usageTap,
     compression
   ) : void 0;
-  return new Proxy(client, {
+  const compressed = new Proxy(client, {
     get(target, prop, receiver) {
       if (prop === "chat" && proxiedChat) {
         return proxiedChat;
@@ -1803,6 +2590,11 @@ function withCompression(client, options = {}) {
       return Reflect.get(target, prop, receiver);
     }
   });
+  return sampling ? withSampling(compressed, {
+    ...sampling === true ? {} : sampling,
+    apiKey,
+    usageTapClient
+  }) : compressed;
 }
 function withMetering(client, customer) {
   const config = typeof customer === "string" ? { customerId: customer } : customer;
@@ -1817,6 +2609,8 @@ function withMetering(client, customer) {
     usageTapClient,
     applyVendorHints,
     promptCompression,
+    sampling,
+    provider,
     ...defaultContext
   } = config;
   const usageTap = usageTapClient ?? new UsageTapClient({ apiKey });
@@ -1824,7 +2618,9 @@ function withMetering(client, customer) {
   return wrapOpenAI(client, usageTap, {
     defaultContext,
     applyVendorHints,
-    promptCompression: normalizedCompression
+    promptCompression: normalizedCompression,
+    sampling,
+    provider
   });
 }
 function wrapOpenAI(client, usageTap, options = {}) {
@@ -1834,6 +2630,8 @@ function wrapOpenAI(client, usageTap, options = {}) {
   const defaultContext = options.defaultContext;
   const applyVendorHints = options.applyVendorHints !== false;
   const defaultPromptCompression = normalizePromptCompressionOptions(options.promptCompression);
+  const defaultSampling = normalizeMeteredOpenAISampling(options.sampling);
+  const provider = options.provider ?? "openai";
   const promptCompressionStats = new OpenAIPromptCompressionStats();
   const proxiedChat = client.chat ? createChatProxy(
     client.chat,
@@ -1841,7 +2639,9 @@ function wrapOpenAI(client, usageTap, options = {}) {
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   ) : void 0;
   const proxiedResponses = typeof client.responses !== "undefined" ? createResponsesProxy(
     client.responses,
@@ -1849,7 +2649,9 @@ function wrapOpenAI(client, usageTap, options = {}) {
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   ) : void 0;
   const handler = {
     get(target, prop, receiver) {
@@ -1968,14 +2770,16 @@ function streamOpenAIRoute(usageTap, openai, options) {
     });
   };
 }
-function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   const completions = createChatCompletionsProxy(
     resource.completions,
     usageTap,
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   );
   const handler = {
     get(target, prop, receiver) {
@@ -1987,7 +2791,7 @@ function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, d
   };
   return new Proxy(resource, handler);
 }
-function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   if (!resource || typeof resource !== "object") {
     return void 0;
   }
@@ -2002,9 +2806,20 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
       withUsage,
       promptCompression
     } = splitUsageOptions(options);
-    const beginRequest = resolveBeginRequest(defaultContext, usageContext);
+    const beginRequest = withRuntimeCompressionContext(
+      resolveBeginRequest(defaultContext, usageContext),
+      "openai",
+      String(params.model)
+    );
     const wantsStream = isStreamingRequest(params);
     return usageTap.withUsage(beginRequest, async (ctx) => {
+      const sampleStartedAt = Date.now();
+      const sampleDecision = wantsStream ? Promise.resolve(false) : startMeteredOpenAISampleDecision({
+        usageTap,
+        sampling: defaultSampling,
+        beginRequest,
+        input: params
+      });
       const hintedParams = applyVendorHints ? applyResponsesVendorHints(params, ctx.begin.data.vendorHints) : params;
       const finalParams = await compressResponsesParamsForCall({
         params: hintedParams,
@@ -2016,13 +2831,14 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
         withUsage,
         operation: "responses.create"
       });
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
         const wrappedPromise2 = transformApiPromise(apiPromise2, (rawStream) => {
           ensureAsyncIterable(rawStream, "responses.create");
           const wrappedStream = wrapStreamForUsageTap(rawStream, async () => {
-            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
+            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints, provider);
             if (usage) {
               ctx.setUsage(usage);
             }
@@ -2032,9 +2848,31 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
         return wrappedPromise2;
       }
       const apiPromise = originalCreate(finalParams, request);
-      const wrappedPromise = transformApiPromise(apiPromise, (response) => {
-        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx);
+      const wrappedPromise = transformApiPromise(apiPromise, async (response) => {
+        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx, provider);
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          response,
+          startedAt: sampleStartedAt
+        });
         return response;
+      }, async (error) => {
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          error,
+          startedAt: sampleStartedAt
+        });
+        throw error;
       });
       return wrappedPromise;
     }, withUsage);
@@ -2049,7 +2887,7 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
   };
   return new Proxy(resource, handler);
 }
-function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   const originalCreate = resource.create.bind(resource);
   const streamCandidate = resource.stream;
   const originalStream = typeof streamCandidate === "function" ? streamCandidate.bind(resource) : void 0;
@@ -2060,9 +2898,20 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
       withUsage,
       promptCompression
     } = splitUsageOptions(options);
-    const beginRequest = resolveBeginRequest(defaultContext, usageContext);
+    const beginRequest = withRuntimeCompressionContext(
+      resolveBeginRequest(defaultContext, usageContext),
+      "openai",
+      String(params.model)
+    );
     const wantsStream = isStreamingRequest(params);
     return usageTap.withUsage(beginRequest, async (ctx) => {
+      const sampleStartedAt = Date.now();
+      const sampleDecision = wantsStream ? Promise.resolve(false) : startMeteredOpenAISampleDecision({
+        usageTap,
+        sampling: defaultSampling,
+        beginRequest,
+        input: params
+      });
       const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
       const finalParams = await compressChatParamsForCall({
         params: hintedParams,
@@ -2074,13 +2923,14 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
         withUsage,
         operation: "chat.completions.create"
       });
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
         const wrappedPromise2 = transformApiPromise(apiPromise2, (rawStream) => {
           ensureAsyncIterable(rawStream, "chat.completions.create");
           const wrappedStream2 = wrapStreamForUsageTap(rawStream, async () => {
-            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
+            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints, provider);
             if (usage) {
               ctx.setUsage(usage);
             }
@@ -2090,9 +2940,31 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
         return wrappedPromise2;
       }
       const apiPromise = originalCreate(finalParams, request);
-      const wrappedPromise = transformApiPromise(apiPromise, (response) => {
-        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx);
+      const wrappedPromise = transformApiPromise(apiPromise, async (response) => {
+        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx, provider);
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          response,
+          startedAt: sampleStartedAt
+        });
         return response;
+      }, async (error) => {
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          error,
+          startedAt: sampleStartedAt
+        });
+        throw error;
       });
       return wrappedPromise;
     }, withUsage);
@@ -2104,7 +2976,11 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
       withUsage,
       promptCompression
     } = splitUsageOptions(options);
-    const beginRequest = resolveBeginRequest(defaultContext, usageContext);
+    const beginRequest = withRuntimeCompressionContext(
+      resolveBeginRequest(defaultContext, usageContext),
+      "openai",
+      String(params.model)
+    );
     return usageTap.withUsage(beginRequest, async (ctx) => {
       const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
       const finalParams = await compressChatParamsForCall({
@@ -2117,12 +2993,17 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
         withUsage,
         operation: "chat.completions.stream"
       });
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       const apiPromise = originalStream(finalParams, request);
       const wrappedPromise = transformApiPromise(apiPromise, (rawStream) => {
         ensureAsyncIterable(rawStream, "chat.completions.stream");
         const wrappedStreamInner = wrapStreamForUsageTap(rawStream, async () => {
-          const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
+          const usage = await extractUsageFromStream(
+            rawStream,
+            ctx.begin.data.vendorHints,
+            provider
+          );
           if (usage) {
             ctx.setUsage(usage);
           }
@@ -2146,19 +3027,70 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
   return new Proxy(resource, handler);
 }
 async function compressChatParamsForCall(args) {
-  const compression = resolveEffectivePromptCompressionOptions(
+  let compression = resolveEffectivePromptCompressionOptions(
     args.defaultPromptCompression,
     args.callPromptCompression
   );
+  const runtimePolicy = args.ctx.begin.data.runtimeCompressionPolicy;
+  const policyDriven = !compression && Boolean(runtimePolicy);
+  if (policyDriven && runtimePolicy) {
+    if (!runtimePolicy.selected) {
+      args.ctx.setUsage({
+        runtimeCompression: bypassedRuntimeMeasurement(runtimePolicy)
+      });
+      return args.params;
+    }
+    compression = openAIPolicyCompressionOptions(runtimePolicy);
+    if (runtimePolicy.mode === "SHADOW") {
+      const startedAt2 = Date.now();
+      void compressChatParams(
+        args.params,
+        args.usageTap,
+        compression,
+        args.withUsage?.signal
+      ).then((outcome2) => {
+        args.ctx.setUsage({
+          runtimeCompression: openAIRuntimeMeasurement({
+            policy: runtimePolicy,
+            telemetry: buildPromptCompressionTelemetry(outcome2.segments),
+            latencyMs: Date.now() - startedAt2,
+            shadow: true,
+            originalPayload: args.params,
+            resultPayload: outcome2.params
+          })
+        });
+      }).catch(() => {
+        args.ctx.setUsage({
+          runtimeCompression: failedRuntimeMeasurement(
+            runtimePolicy,
+            Date.now() - startedAt2
+          )
+        });
+      });
+      return args.params;
+    }
+  }
   if (!compression) {
     return args.params;
   }
+  const startedAt = Date.now();
   const outcome = await compressChatParams(
     args.params,
     args.usageTap,
     compression,
     args.withUsage?.signal
   );
+  if (policyDriven && runtimePolicy) {
+    const runtimeMeasurement = openAIRuntimeMeasurement({
+      policy: runtimePolicy,
+      telemetry: buildPromptCompressionTelemetry(outcome.segments),
+      latencyMs: Date.now() - startedAt,
+      originalPayload: args.params,
+      resultPayload: outcome.params
+    });
+    args.ctx.setUsage({ runtimeCompression: runtimeMeasurement });
+    if (runtimeMeasurement.decision !== "compressed") return args.params;
+  }
   await recordCompressionOutcome({
     outcome,
     compression,
@@ -2171,19 +3103,70 @@ async function compressChatParamsForCall(args) {
   return outcome.params;
 }
 async function compressResponsesParamsForCall(args) {
-  const compression = resolveEffectivePromptCompressionOptions(
+  let compression = resolveEffectivePromptCompressionOptions(
     args.defaultPromptCompression,
     args.callPromptCompression
   );
+  const runtimePolicy = args.ctx.begin.data.runtimeCompressionPolicy;
+  const policyDriven = !compression && Boolean(runtimePolicy);
+  if (policyDriven && runtimePolicy) {
+    if (!runtimePolicy.selected) {
+      args.ctx.setUsage({
+        runtimeCompression: bypassedRuntimeMeasurement(runtimePolicy)
+      });
+      return args.params;
+    }
+    compression = openAIPolicyCompressionOptions(runtimePolicy);
+    if (runtimePolicy.mode === "SHADOW") {
+      const startedAt2 = Date.now();
+      void compressResponsesParams(
+        args.params,
+        args.usageTap,
+        compression,
+        args.withUsage?.signal
+      ).then((outcome2) => {
+        args.ctx.setUsage({
+          runtimeCompression: openAIRuntimeMeasurement({
+            policy: runtimePolicy,
+            telemetry: buildPromptCompressionTelemetry(outcome2.segments),
+            latencyMs: Date.now() - startedAt2,
+            shadow: true,
+            originalPayload: args.params,
+            resultPayload: outcome2.params
+          })
+        });
+      }).catch(() => {
+        args.ctx.setUsage({
+          runtimeCompression: failedRuntimeMeasurement(
+            runtimePolicy,
+            Date.now() - startedAt2
+          )
+        });
+      });
+      return args.params;
+    }
+  }
   if (!compression) {
     return args.params;
   }
+  const startedAt = Date.now();
   const outcome = await compressResponsesParams(
     args.params,
     args.usageTap,
     compression,
     args.withUsage?.signal
   );
+  if (policyDriven && runtimePolicy) {
+    const runtimeMeasurement = openAIRuntimeMeasurement({
+      policy: runtimePolicy,
+      telemetry: buildPromptCompressionTelemetry(outcome.segments),
+      latencyMs: Date.now() - startedAt,
+      originalPayload: args.params,
+      resultPayload: outcome.params
+    });
+    args.ctx.setUsage({ runtimeCompression: runtimeMeasurement });
+    if (runtimeMeasurement.decision !== "compressed") return args.params;
+  }
   await recordCompressionOutcome({
     outcome,
     compression,
@@ -2195,6 +3178,79 @@ async function compressResponsesParamsForCall(args) {
   });
   return outcome.params;
 }
+function openAIPolicyCompressionOptions(policy) {
+  const roles = Object.fromEntries(
+    ["system", "user", "tool", "assistant"].filter((role) => policy.snapshot.scope.messageRoles.includes(role)).map((role) => [role, true])
+  );
+  return {
+    provider: "usagetap",
+    roles,
+    minContextTokens: policy.snapshot.scope.minimumTokens,
+    failOpen: true
+  };
+}
+function bypassedRuntimeMeasurement(policy) {
+  return {
+    policyId: policy.policyId,
+    policyVersionId: policy.policyVersionId,
+    policyVersion: policy.version,
+    rolloutMode: policy.mode,
+    decision: "bypassed",
+    reasonCode: "not_in_rollout_sample",
+    methodsAttempted: [],
+    methodsApplied: [],
+    originalTokens: 0,
+    resultTokens: 0,
+    savedTokens: 0,
+    reductionPercentage: 0,
+    compressionLatencyMs: 0,
+    compressionComputeCostUsd: 0,
+    financialsEstimated: true
+  };
+}
+function failedRuntimeMeasurement(policy, latencyMs) {
+  return {
+    ...bypassedRuntimeMeasurement(policy),
+    decision: "fallback",
+    reasonCode: "transformation_failed",
+    methodsAttempted: ["deterministic"],
+    compressionLatencyMs: latencyMs
+  };
+}
+function openAIRuntimeMeasurement(input) {
+  const telemetry = input.telemetry;
+  const originalTokens = telemetry?.originalTokens ?? estimatePromptTokens(JSON.stringify(input.originalPayload));
+  const resultTokens = telemetry?.compressedTokens ?? originalTokens;
+  const savedTokens = Math.max(0, telemetry?.savedTokens ?? 0);
+  const reductionPercentage = originalTokens > 0 ? savedTokens / originalTokens * 100 : 0;
+  const belowMinimumSize = originalTokens < input.policy.snapshot.scope.minimumTokens;
+  const latencyExceeded = input.latencyMs > input.policy.snapshot.gates.maximumLatencyMs;
+  const belowSavings = savedTokens < input.policy.snapshot.gates.minimumTokensRemoved || reductionPercentage < input.policy.snapshot.gates.minimumReductionPercentage;
+  const accepted = !belowMinimumSize && !latencyExceeded && !belowSavings;
+  const deepText = input.policy.snapshot.methods.deepText.enabled && !input.policy.snapshot.rollout.deterministicOnly && (input.policy.mode !== "CANARY" || input.policy.snapshot.rollout.deepTextCanaryAllowed);
+  const reasonCode = belowMinimumSize ? "below_minimum_size" : latencyExceeded ? "latency_budget_exceeded" : belowSavings ? "below_minimum_savings" : void 0;
+  const measurement = {
+    policyId: input.policy.policyId,
+    policyVersionId: input.policy.policyVersionId,
+    policyVersion: input.policy.version,
+    rolloutMode: input.policy.mode,
+    decision: accepted ? input.shadow ? "bypassed" : "compressed" : latencyExceeded ? "fallback" : "skipped",
+    ...reasonCode ? { reasonCode } : {},
+    methodsAttempted: [
+      "deterministic",
+      ...deepText ? ["deep_text"] : []
+    ],
+    methodsApplied: accepted ? ["deterministic"] : [],
+    originalTokens,
+    resultTokens: accepted ? resultTokens : originalTokens,
+    savedTokens: accepted ? savedTokens : 0,
+    reductionPercentage: accepted ? reductionPercentage : 0,
+    compressionLatencyMs: input.latencyMs,
+    compressionComputeCostUsd: 0,
+    financialsEstimated: true
+  };
+  return measurement;
+}
 async function recordCompressionOutcome(args) {
   const telemetry = buildPromptCompressionTelemetry(args.outcome.segments);
   if (!telemetry) {
@@ -2248,6 +3304,10 @@ async function compressChatParams(params, usageTap, compression, signal) {
     const result = await usageTap.compressPromptMessages(source, {
       provider: "usagetap",
       failOpen: compression.failOpen,
+      mode: compression.mode,
+      latencyBudgetMs: compression.latencyBudgetMs,
+      compactEmptyUserMessages: compression.compactEmptyUserMessages,
+      compactDuplicateUserTextParts: compression.compactDuplicateUserTextParts,
       aggressiveness: resolveMessageEndpointAggressiveness(compression),
       signal
     });
@@ -2713,23 +3773,53 @@ function resolveBeginRequest(defaults, override) {
   }
   const tags = mergeTags(base.tags, current.tags);
   const begin = { customerId };
+  const runtimeCompressionContext = current.runtimeCompressionContext ?? base.runtimeCompressionContext;
+  if (runtimeCompressionContext) {
+    begin.runtimeCompressionContext = runtimeCompressionContext;
+  }
   const requested = current.requested ?? base.requested;
   if (requested) begin.requested = requested;
   const feature = current.feature ?? base.feature;
   if (feature) begin.feature = feature;
+  const runId = current.runId ?? base.runId;
+  if (runId) begin.runId = runId;
   const idempotency = current.idempotency ?? base.idempotency;
   if (idempotency) begin.idempotency = idempotency;
   const customerName = current.customerName ?? base.customerName;
   if (customerName) begin.customerName = customerName;
   const customerEmail = current.customerEmail ?? base.customerEmail;
   if (customerEmail) begin.customerEmail = customerEmail;
+  const customerUserId = current.customerUserId ?? base.customerUserId;
+  if (customerUserId) begin.customerUserId = customerUserId;
+  const customerUserName = current.customerUserName ?? base.customerUserName;
+  if (customerUserName) begin.customerUserName = customerUserName;
+  const customerUserEmail = current.customerUserEmail ?? base.customerUserEmail;
+  if (customerUserEmail) begin.customerUserEmail = customerUserEmail;
+  const stripeCustomerId = current.stripeCustomerId ?? base.stripeCustomerId;
+  if (stripeCustomerId) begin.stripeCustomerId = stripeCustomerId;
+  const holdUsd = current.holdUsd ?? base.holdUsd;
+  if (typeof holdUsd === "number") begin.holdUsd = holdUsd;
+  const batch = current.batch ?? base.batch;
+  if (typeof batch === "boolean") begin.batch = batch;
+  const pricingMode = current.pricingMode ?? base.pricingMode;
+  if (pricingMode) begin.pricingMode = pricingMode;
   if (tags?.length) {
     begin.tags = tags;
   }
   return begin;
 }
-function transformApiPromise(apiPromise, onResolve) {
-  const resolvedPromise = Promise.resolve(apiPromise).then(onResolve);
+function withRuntimeCompressionContext(begin, provider, model) {
+  return {
+    ...begin,
+    runtimeCompressionContext: {
+      ...begin.runtimeCompressionContext ?? {},
+      provider,
+      model
+    }
+  };
+}
+function transformApiPromise(apiPromise, onResolve, onReject) {
+  const resolvedPromise = Promise.resolve(apiPromise).then(onResolve, onReject);
   if (isObjectRecord(apiPromise)) {
     const proto = Object.getPrototypeOf(apiPromise);
     if (proto) {
@@ -2864,12 +3954,12 @@ function applyResponsesVendorHints(params, hints) {
   }
   return next;
 }
-async function extractUsageFromStream(stream, hints) {
+async function extractUsageFromStream(stream, hints, provider = "openai") {
   const finalPayload = await resolveStreamFinalPayload(stream);
   if (!finalPayload) {
     return void 0;
   }
-  return inferUsageFromResponse(finalPayload, hints);
+  return inferUsageFromResponse(finalPayload, hints, provider);
 }
 async function resolveStreamFinalPayload(stream) {
   if (!stream || typeof stream !== "object") {
@@ -2942,14 +4032,14 @@ function setHeaderIfPossible(res, key, value) {
     res.setHeader(key, value);
   }
 }
-function tryInferUsage(response, hints, extractor, ctx) {
+function tryInferUsage(response, hints, extractor, ctx, provider = "openai") {
   const explicit = extractor?.(response);
-  const inferred = explicit ?? inferUsageFromResponse(response, hints);
+  const inferred = explicit ?? inferUsageFromResponse(response, hints, provider);
   if (inferred) {
     ctx.setUsage(inferred);
   }
 }
-function inferUsageFromResponse(response, hints) {
+function inferUsageFromResponse(response, hints, provider = "openai") {
   if (!response || typeof response !== "object") {
     return void 0;
   }
@@ -2957,12 +4047,41 @@ function inferUsageFromResponse(response, hints) {
   if (!candidate.usage) {
     return void 0;
   }
-  const cachedInputTokens = candidate.usage.prompt_tokens_details?.cached_tokens ?? candidate.usage.cached_tokens;
+  const cachedInputTokens = candidate.usage.prompt_tokens_details?.cached_tokens ?? candidate.usage.input_tokens_details?.cached_tokens ?? candidate.usage.cached_tokens;
+  const responseEffort = normalizeExecutionReasoningEffort(
+    candidate.reasoning?.effort
+  );
   return {
+    providerUsed: provider,
     modelUsed: candidate.model ?? hints?.preferredModel,
-    inputTokens: candidate.usage.prompt_tokens,
-    responseTokens: candidate.usage.completion_tokens,
-    cachedInputTokens
+    inputTokens: candidate.usage.prompt_tokens ?? candidate.usage.input_tokens,
+    responseTokens: candidate.usage.completion_tokens ?? candidate.usage.output_tokens,
+    cachedInputTokens,
+    reasoningTokens: candidate.usage.completion_tokens_details?.reasoning_tokens ?? candidate.usage.output_tokens_details?.reasoning_tokens,
+    ...responseEffort ? {
+      reasoningEffort: responseEffort,
+      reasoningEffortSource: "provider_response"
+    } : {},
+    ...typeof candidate.reasoning?.type === "string" ? { reasoningMode: candidate.reasoning.type } : typeof candidate.reasoning?.mode === "string" ? { reasoningMode: candidate.reasoning.mode } : {}
+  };
+}
+function normalizeExecutionReasoningEffort(value) {
+  return value === "none" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max" ? value : void 0;
+}
+function openAIRequestExecutionMetadata(params, provider) {
+  const record = params && typeof params === "object" ? params : {};
+  const reasoning = record.reasoning && typeof record.reasoning === "object" ? record.reasoning : void 0;
+  const effort = normalizeExecutionReasoningEffort(
+    record.reasoning_effort ?? reasoning?.effort ?? record.thinking_level
+  );
+  const mode = typeof reasoning?.type === "string" ? reasoning.type : typeof reasoning?.mode === "string" ? reasoning.mode : void 0;
+  const rawBudget = reasoning?.budget_tokens ?? record.thinking_budget ?? record.thinking_budget_tokens;
+  const budget = typeof rawBudget === "number" && Number.isInteger(rawBudget) && rawBudget >= 0 ? rawBudget : void 0;
+  return {
+    providerUsed: provider,
+    ...effort ? { reasoningEffort: effort, reasoningEffortSource: "provider_request" } : {},
+    ...mode ? { reasoningMode: mode } : {},
+    ...budget !== void 0 ? { reasoningBudgetTokens: budget } : {}
   };
 }
 function wrapStreamForUsageTap(source, finalize, ctx) {
@@ -3064,7 +4183,7 @@ function isIteratorResult(value) {
 
 // src/adapters/openrouter.ts
 function createOpenRouterAdapter(init) {
-  return createOpenAIAdapter(init);
+  return createOpenAIAdapter({ ...init, provider: "openrouter" });
 }
 
 exports.OpenAIPromptCompressionStats = OpenAIPromptCompressionStats;
@@ -3075,6 +4194,7 @@ exports.streamOpenAIRoute = streamOpenAIRoute;
 exports.toNextResponse = toNextResponse;
 exports.withCompression = withCompression;
 exports.withMetering = withMetering;
+exports.withSampling = withSampling;
 exports.wrapOpenAI = wrapOpenAI;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map