@usagetap/sdk 1.0.0 → 1.1.0

package/dist/express/index.mjs

@@ -27,7 +27,62 @@ var UsageTapError = class extends Error {
   }
 };
 
+// src/prompt-compression.ts
+function estimatePromptTokens(input) {
+  const text = typeof input === "string" ? input : stableStringifyInput(input);
+  return text.match(/[\p{L}\p{N}]+|[^\s]/gu)?.length ?? 0;
+}
+function stableStringifyInput(input) {
+  if (typeof input === "string") return input;
+  return JSON.stringify(input) ?? String(input);
+}
+
 // src/adapters/openai.ts
+var OpenAIPromptCompressionStats = class {
+  history = [];
+  failures = [];
+  _record(turn) {
+    this.history.push(turn);
+  }
+  _recordFailure(failure) {
+    this.failures.push(failure);
+  }
+  get totalOriginalTokens() {
+    return this.history.reduce((sum, turn) => sum + (turn.originalTokens ?? 0), 0);
+  }
+  get totalCompressedTokens() {
+    return this.history.reduce((sum, turn) => sum + (turn.compressedTokens ?? 0), 0);
+  }
+  get totalTokensSaved() {
+    return this.history.reduce((sum, turn) => sum + (turn.savedTokens ?? 0), 0);
+  }
+  get totalOriginalCharacters() {
+    return this.history.reduce((sum, turn) => sum + turn.originalCharacters, 0);
+  }
+  get totalCompressedCharacters() {
+    return this.history.reduce((sum, turn) => sum + turn.compressedCharacters, 0);
+  }
+  get totalCharactersSaved() {
+    return this.history.reduce((sum, turn) => sum + turn.savedCharacters, 0);
+  }
+  get calls() {
+    return this.history.length;
+  }
+  get telemetryFailures() {
+    return this.failures.length;
+  }
+  get failOpenEvents() {
+    return this.history.filter(
+      (turn) => turn.techniques.includes("compression-error") || turn.techniques.includes("fallback-original")
+    ).length;
+  }
+  get tokenSavingsRatio() {
+    return this.totalOriginalTokens > 0 ? this.totalTokensSaved / this.totalOriginalTokens : 0;
+  }
+  get savingsRatio() {
+    return this.totalOriginalCharacters > 0 ? this.totalCharactersSaved / this.totalOriginalCharacters : 0;
+  }
+};
 function toNextResponse(stream, options = {}) {
   const mode = options.mode ?? "text";
   const headers = new Headers(options.headers ?? {});
@@ -125,8 +180,24 @@ function wrapOpenAI(client, usageTap, options = {}) {
   }
   const defaultContext = options.defaultContext;
   const applyVendorHints = options.applyVendorHints !== false;
-  const proxiedChat = client.chat ? createChatProxy(client.chat, usageTap, defaultContext, applyVendorHints) : void 0;
-  const proxiedResponses = typeof client.responses !== "undefined" ? createResponsesProxy(client.responses, usageTap, defaultContext, applyVendorHints) : void 0;
+  const defaultPromptCompression = normalizePromptCompressionOptions(options.promptCompression);
+  const promptCompressionStats = new OpenAIPromptCompressionStats();
+  const proxiedChat = client.chat ? createChatProxy(
+    client.chat,
+    usageTap,
+    defaultContext,
+    applyVendorHints,
+    defaultPromptCompression,
+    promptCompressionStats
+  ) : void 0;
+  const proxiedResponses = typeof client.responses !== "undefined" ? createResponsesProxy(
+    client.responses,
+    usageTap,
+    defaultContext,
+    applyVendorHints,
+    defaultPromptCompression,
+    promptCompressionStats
+  ) : void 0;
   const handler = {
     get(target, prop, receiver) {
       if (prop === "chat" && proxiedChat) {
@@ -141,6 +212,9 @@ function wrapOpenAI(client, usageTap, options = {}) {
       if (prop === "pipeToResponse") {
         return pipeToResponse;
       }
+      if (prop === "promptCompression") {
+        return promptCompressionStats;
+      }
       if (prop === "unwrap") {
         return () => target;
       }
@@ -149,12 +223,14 @@ function wrapOpenAI(client, usageTap, options = {}) {
   };
   return new Proxy(client, handler);
 }
-function createChatProxy(resource, usageTap, defaultContext, applyVendorHints) {
+function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
   const completions = createChatCompletionsProxy(
     resource.completions,
     usageTap,
     defaultContext,
-    applyVendorHints
+    applyVendorHints,
+    defaultPromptCompression,
+    promptCompressionStats
   );
   const handler = {
     get(target, prop, receiver) {
@@ -166,7 +242,7 @@ function createChatProxy(resource, usageTap, defaultContext, applyVendorHints) {
   };
   return new Proxy(resource, handler);
 }
-function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints) {
+function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
   if (!resource || typeof resource !== "object") {
     return void 0;
   }
@@ -175,11 +251,26 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
   }
   const originalCreate = resource.create.bind(resource);
   const wrappedCreate = (params, options) => {
-    const { requestOptions, usageContext, withUsage: withUsage2 } = splitUsageOptions(options);
+    const {
+      requestOptions,
+      usageContext,
+      withUsage: withUsage2,
+      promptCompression
+    } = splitUsageOptions(options);
     const beginRequest = resolveBeginRequest(defaultContext, usageContext);
     const wantsStream = isStreamingRequest(params);
-    return usageTap.withUsage(beginRequest, (ctx) => {
-      const finalParams = applyVendorHints ? applyResponsesVendorHints(params, ctx.begin.data.vendorHints) : params;
+    return usageTap.withUsage(beginRequest, async (ctx) => {
+      const hintedParams = applyVendorHints ? applyResponsesVendorHints(params, ctx.begin.data.vendorHints) : params;
+      const finalParams = await compressResponsesParamsForCall({
+        params: hintedParams,
+        usageTap,
+        ctx,
+        defaultPromptCompression,
+        callPromptCompression: promptCompression,
+        stats: promptCompressionStats,
+        withUsage: withUsage2,
+        operation: "responses.create"
+      });
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
@@ -213,16 +304,31 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
   };
   return new Proxy(resource, handler);
 }
-function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints) {
+function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
   const originalCreate = resource.create.bind(resource);
   const streamCandidate = resource.stream;
   const originalStream = typeof streamCandidate === "function" ? streamCandidate.bind(resource) : void 0;
   const wrappedCreate = (params, options) => {
-    const { requestOptions, usageContext, withUsage: withUsage2 } = splitUsageOptions(options);
+    const {
+      requestOptions,
+      usageContext,
+      withUsage: withUsage2,
+      promptCompression
+    } = splitUsageOptions(options);
     const beginRequest = resolveBeginRequest(defaultContext, usageContext);
     const wantsStream = isStreamingRequest(params);
-    return usageTap.withUsage(beginRequest, (ctx) => {
-      const finalParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
+    return usageTap.withUsage(beginRequest, async (ctx) => {
+      const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
+      const finalParams = await compressChatParamsForCall({
+        params: hintedParams,
+        usageTap,
+        ctx,
+        defaultPromptCompression,
+        callPromptCompression: promptCompression,
+        stats: promptCompressionStats,
+        withUsage: withUsage2,
+        operation: "chat.completions.create"
+      });
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
@@ -247,10 +353,25 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
     }, withUsage2);
   };
   const wrappedStream = originalStream ? (params, options) => {
-    const { requestOptions, usageContext, withUsage: withUsage2 } = splitUsageOptions(options);
+    const {
+      requestOptions,
+      usageContext,
+      withUsage: withUsage2,
+      promptCompression
+    } = splitUsageOptions(options);
     const beginRequest = resolveBeginRequest(defaultContext, usageContext);
-    return usageTap.withUsage(beginRequest, (ctx) => {
-      const finalParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
+    return usageTap.withUsage(beginRequest, async (ctx) => {
+      const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
+      const finalParams = await compressChatParamsForCall({
+        params: hintedParams,
+        usageTap,
+        ctx,
+        defaultPromptCompression,
+        callPromptCompression: promptCompression,
+        stats: promptCompressionStats,
+        withUsage: withUsage2,
+        operation: "chat.completions.stream"
+      });
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       const apiPromise = originalStream(finalParams, request);
       const wrappedPromise = transformApiPromise(apiPromise, (rawStream) => {
@@ -279,16 +400,475 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
   };
   return new Proxy(resource, handler);
 }
+async function compressChatParamsForCall(args) {
+  const compression = resolveEffectivePromptCompressionOptions(
+    args.defaultPromptCompression,
+    args.callPromptCompression
+  );
+  if (!compression) {
+    return args.params;
+  }
+  const outcome = await compressChatParams(
+    args.params,
+    args.usageTap,
+    compression,
+    args.withUsage?.signal
+  );
+  await recordCompressionOutcome({
+    outcome,
+    compression,
+    usageTap: args.usageTap,
+    ctx: args.ctx,
+    stats: args.stats,
+    withUsage: args.withUsage,
+    operation: args.operation
+  });
+  return outcome.params;
+}
+async function compressResponsesParamsForCall(args) {
+  const compression = resolveEffectivePromptCompressionOptions(
+    args.defaultPromptCompression,
+    args.callPromptCompression
+  );
+  if (!compression) {
+    return args.params;
+  }
+  const outcome = await compressResponsesParams(
+    args.params,
+    args.usageTap,
+    compression,
+    args.withUsage?.signal
+  );
+  await recordCompressionOutcome({
+    outcome,
+    compression,
+    usageTap: args.usageTap,
+    ctx: args.ctx,
+    stats: args.stats,
+    withUsage: args.withUsage,
+    operation: args.operation
+  });
+  return outcome.params;
+}
+async function recordCompressionOutcome(args) {
+  const telemetry = buildPromptCompressionTelemetry(args.outcome.segments);
+  if (!telemetry) {
+    return;
+  }
+  const turn = {
+    ...telemetry,
+    callId: args.ctx.begin.data.callId,
+    operation: args.operation,
+    messagesCompressed: args.outcome.segments.length,
+    timestamp: Date.now()
+  };
+  args.stats._record(turn);
+  try {
+    await args.usageTap.recordPromptCompression(
+      {
+        callId: args.ctx.begin.data.callId,
+        promptCompression: telemetry
+      },
+      promptCompressionRequestOptions(args.withUsage, args.ctx.begin.correlationId)
+    );
+  } catch (error) {
+    args.stats._recordFailure({
+      callId: args.ctx.begin.data.callId,
+      operation: args.operation,
+      stage: "telemetry",
+      message: error instanceof Error ? error.message : String(error),
+      timestamp: Date.now()
+    });
+    if (args.compression.failOpen === false) {
+      throw error;
+    }
+  }
+}
+async function compressChatParams(params, usageTap, compression, signal) {
+  if (!params || typeof params !== "object") {
+    return { params, segments: [] };
+  }
+  const source = cloneRecord(params);
+  const messages = Array.isArray(source.messages) ? source.messages : void 0;
+  if (!messages) {
+    return { params, segments: [] };
+  }
+  const messageResults = await Promise.all(
+    messages.map(
+      (message) => compressOpenAIMessage(message, usageTap, compression, signal)
+    )
+  );
+  return {
+    params: {
+      ...source,
+      messages: messageResults.map((result) => result.value)
+    },
+    segments: messageResults.flatMap((result) => result.segments)
+  };
+}
+async function compressResponsesParams(params, usageTap, compression, signal) {
+  if (!params || typeof params !== "object") {
+    return { params, segments: [] };
+  }
+  const source = cloneRecord(params);
+  const segments = [];
+  if (typeof source.instructions === "string") {
+    const compressed = await compressTextForRole(
+      source.instructions,
+      "system",
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      source.instructions = compressed.text;
+      segments.push(compressed.segment);
+    }
+  }
+  if (typeof source.input === "string") {
+    const compressed = await compressTextForRole(
+      source.input,
+      "user",
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      source.input = compressed.text;
+      segments.push(compressed.segment);
+    }
+  } else if (Array.isArray(source.input)) {
+    const inputResults = await Promise.all(
+      source.input.map(
+        (item) => compressResponsesInputItem(item, usageTap, compression, signal)
+      )
+    );
+    source.input = inputResults.map((result) => result.value);
+    segments.push(...inputResults.flatMap((result) => result.segments));
+  }
+  return {
+    params: source,
+    segments
+  };
+}
+async function compressOpenAIMessage(message, usageTap, compression, signal) {
+  if (!isObjectRecord(message)) {
+    return { value: message, segments: [] };
+  }
+  const role = mapOpenAIRole(message.role);
+  if (!role) {
+    return { value: message, segments: [] };
+  }
+  const content = message.content;
+  if (typeof content === "string") {
+    const compressed = await compressTextForRole(
+      content,
+      role,
+      usageTap,
+      compression,
+      signal
+    );
+    if (!compressed) {
+      return { value: message, segments: [] };
+    }
+    return {
+      value: { ...message, content: compressed.text },
+      segments: [compressed.segment]
+    };
+  }
+  if (Array.isArray(content)) {
+    const blockResults = await Promise.all(
+      content.map(
+        (block) => compressOpenAITextBlock(block, role, usageTap, compression, signal)
+      )
+    );
+    const segments = blockResults.flatMap(
+      (result) => result.segment ? [result.segment] : []
+    );
+    return {
+      value: segments.length ? { ...message, content: blockResults.map((result) => result.value) } : message,
+      segments
+    };
+  }
+  return { value: message, segments: [] };
+}
+async function compressOpenAITextBlock(block, role, usageTap, compression, signal) {
+  if (!isObjectRecord(block) || block.type !== "text" || typeof block.text !== "string") {
+    return { value: block };
+  }
+  const compressed = await compressTextForRole(
+    block.text,
+    role,
+    usageTap,
+    compression,
+    signal
+  );
+  if (!compressed) {
+    return { value: block };
+  }
+  return {
+    value: { ...block, text: compressed.text },
+    segment: compressed.segment
+  };
+}
+async function compressResponsesInputItem(item, usageTap, compression, signal) {
+  if (!isObjectRecord(item)) {
+    return { value: item, segments: [] };
+  }
+  const specialToolRole = mapResponsesItemTypeToRole(item.type);
+  const role = specialToolRole ?? mapOpenAIRole(item.role);
+  const segments = [];
+  let next = item;
+  if (role && typeof item.content === "string") {
+    const compressed = await compressTextForRole(
+      item.content,
+      role,
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      next = { ...next, content: compressed.text };
+      segments.push(compressed.segment);
+    }
+  } else if (role && Array.isArray(item.content)) {
+    const contentResults = await Promise.all(
+      item.content.map(
+        (block) => compressResponsesContentBlock(block, role, usageTap, compression, signal)
+      )
+    );
+    segments.push(
+      ...contentResults.flatMap(
+        (result) => result.segment ? [result.segment] : []
+      )
+    );
+    if (segments.length) {
+      next = {
+        ...next,
+        content: contentResults.map((result) => result.value)
+      };
+    }
+  }
+  if (specialToolRole && typeof item.output === "string") {
+    const compressed = await compressTextForRole(
+      item.output,
+      specialToolRole,
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      next = { ...next, output: compressed.text };
+      segments.push(compressed.segment);
+    }
+  }
+  return { value: next, segments };
+}
+async function compressResponsesContentBlock(block, role, usageTap, compression, signal) {
+  if (!isObjectRecord(block)) {
+    return { value: block };
+  }
+  if ((block.type === "input_text" || block.type === "text") && typeof block.text === "string") {
+    const compressed = await compressTextForRole(
+      block.text,
+      role,
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      return {
+        value: { ...block, text: compressed.text },
+        segment: compressed.segment
+      };
+    }
+  }
+  if (role === "tool" && typeof block.output === "string") {
+    const compressed = await compressTextForRole(
+      block.output,
+      role,
+      usageTap,
+      compression,
+      signal
+    );
+    if (compressed) {
+      return {
+        value: { ...block, output: compressed.text },
+        segment: compressed.segment
+      };
+    }
+  }
+  return { value: block };
+}
+async function compressTextForRole(text, role, usageTap, compression, signal) {
+  if (!text.trim()) {
+    return void 0;
+  }
+  const roleOptions = resolveRoleCompressionOptions(compression, role);
+  if (!roleOptions) {
+    return void 0;
+  }
+  const estimatedTokens = estimatePromptTokens(text);
+  if (typeof roleOptions.minTokens === "number" && estimatedTokens < roleOptions.minTokens) {
+    return void 0;
+  }
+  const result = await usageTap.compressPromptInput(text, {
+    provider: roleOptions.provider,
+    failOpen: roleOptions.failOpen,
+    tokenCompanyModel: roleOptions.tokenCompanyModel,
+    tokenCompanyAggressiveness: roleOptions.tokenCompanyAggressiveness,
+    tokenCompanyAppId: roleOptions.tokenCompanyAppId,
+    signal
+  });
+  const compressedText = typeof result.compressedInput === "string" ? result.compressedInput : String(result.compressedInput);
+  return {
+    text: compressedText,
+    segment: { role, result: { ...result, compressedInput: compressedText } }
+  };
+}
+function normalizePromptCompressionOptions(options) {
+  if (!options) {
+    return void 0;
+  }
+  if (options === true) {
+    return {};
+  }
+  if (options.enabled === false) {
+    return void 0;
+  }
+  return options;
+}
+function resolveEffectivePromptCompressionOptions(defaults, override) {
+  if (override === false) {
+    return void 0;
+  }
+  if (override === void 0) {
+    return defaults;
+  }
+  if (override === true) {
+    return defaults ?? {};
+  }
+  const merged = {
+    ...defaults ?? {},
+    ...override,
+    roles: override.roles ?? defaults?.roles
+  };
+  return normalizePromptCompressionOptions(merged);
+}
+function resolveRoleCompressionOptions(compression, role) {
+  const hasExplicitRoles = compression.roles !== void 0;
+  const setting = compression.roles?.[role];
+  if (hasExplicitRoles && setting === void 0) {
+    return void 0;
+  }
+  if (!hasExplicitRoles && role === "assistant") {
+    return void 0;
+  }
+  if (setting === false) {
+    return void 0;
+  }
+  const roleOptions = typeof setting === "object" ? setting : void 0;
+  if (roleOptions?.enabled === false) {
+    return void 0;
+  }
+  return {
+    provider: roleOptions?.provider ?? compression.provider,
+    minTokens: roleOptions?.minTokens ?? compression.minTokens,
+    failOpen: compression.failOpen,
+    tokenCompanyModel: compression.tokenCompanyModel,
+    tokenCompanyAggressiveness: roleOptions?.tokenCompanyAggressiveness ?? resolveTokenCompanyAggressiveness(compression, role),
+    tokenCompanyAppId: compression.tokenCompanyAppId
+  };
+}
+function resolveTokenCompanyAggressiveness(compression, role) {
+  if (typeof compression.tokenCompanyAggressiveness === "number") {
+    return compression.tokenCompanyAggressiveness;
+  }
+  return compression.tokenCompanyAggressiveness?.[role];
+}
+function buildPromptCompressionTelemetry(segments) {
+  if (!segments.length) {
+    return void 0;
+  }
+  const originalCharacters = segments.reduce(
+    (sum, segment) => sum + segment.result.originalCharacters,
+    0
+  );
+  const compressedCharacters = segments.reduce(
+    (sum, segment) => sum + segment.result.compressedCharacters,
+    0
+  );
+  const originalTokens = segments.reduce(
+    (sum, segment) => sum + segment.result.originalTokens,
+    0
+  );
+  const compressedTokens = segments.reduce(
+    (sum, segment) => sum + segment.result.compressedTokens,
+    0
+  );
+  const savedCharacters = Math.max(0, originalCharacters - compressedCharacters);
+  const savedTokens = Math.max(0, originalTokens - compressedTokens);
+  const providers = dedupeStrings(segments.map((segment) => segment.result.provider));
+  const roles = dedupeStrings(segments.map((segment) => `role:${segment.role}`));
+  const techniques = dedupeStrings([
+    "openai-wrapper",
+    ...roles,
+    ...segments.flatMap((segment) => segment.result.techniques),
+    ...providers.length > 1 ? ["mixed-providers"] : []
+  ]);
+  return {
+    provider: segments[0]?.result.provider ?? "heuristic",
+    originalCharacters,
+    compressedCharacters,
+    savedCharacters,
+    originalTokens,
+    compressedTokens,
+    savedTokens,
+    tokenSavingsRatio: originalTokens > 0 ? savedTokens / originalTokens : 0,
+    savingsRatio: originalCharacters > 0 ? savedCharacters / originalCharacters : 0,
+    techniques
+  };
+}
+function promptCompressionRequestOptions(withUsage2, correlationId) {
+  return {
+    signal: withUsage2?.signal,
+    headers: withUsage2?.headers,
+    retries: withUsage2?.retries,
+    correlationId
+  };
+}
+function mapOpenAIRole(role) {
+  if (role === "system" || role === "developer") {
+    return "system";
+  }
+  if (role === "user") {
+    return "user";
+  }
+  if (role === "tool" || role === "function") {
+    return "tool";
+  }
+  if (role === "assistant") {
+    return "assistant";
+  }
+  return void 0;
+}
+function mapResponsesItemTypeToRole(type) {
+  if (type === "function_call_output" || type === "tool_result" || type === "computer_call_output") {
+    return "tool";
+  }
+  return void 0;
+}
 function splitUsageOptions(options) {
   if (!options || typeof options !== "object") {
     return {};
   }
-  const { usageTap, withUsage: withUsage2, ...rest } = options;
+  const { usageTap, withUsage: withUsage2, promptCompression, ...rest } = options;
   const requestOptions = Object.keys(rest).length ? cloneRequestOptions(rest) : void 0;
   return {
     requestOptions,
     usageContext: usageTap,
-    withUsage: withUsage2
+    withUsage: withUsage2,
+    promptCompression
   };
 }
 function resolveBeginRequest(defaults, override) {