@robota-sdk/agent-provider-openai 3.0.0-beta.82 → 3.0.0-beta.83

package/src/openai/loggers/console-payload-logger.ts

@@ -8,7 +8,7 @@ import type { IOpenAILogData } from '../types/api-types';
 /**
  * Console-based payload logger for browser environments
  *
- * This logger outputs API request/response payloads to the browser console
+ * This logger outputs a summary of each Chat Completions request to the browser console
  * using structured logging. It's designed specifically for browser environments
  * and development/debugging scenarios.
  *
@@ -47,7 +47,7 @@ export class ConsolePayloadLogger implements IPayloadLogger {
 
   /**
    * Log API payload to browser console
-   * @param payload - The API request payload
+   * @param payload - Summary of the outgoing Chat Completions request
    * @param type - Type of request ('chat' or 'stream')
    */
   async logPayload(payload: IOpenAILogData, type: 'chat' | 'stream' = 'chat'): Promise<void> {

package/src/openai/loggers/file-payload-logger.ts

@@ -16,7 +16,7 @@ const OWNER_ONLY_DIR_MODE = 0o700;
 /**
  * File-based payload logger for Node.js environments
  *
- * This logger saves API request/response payloads to JSON files on disk.
+ * This logger saves a summary of each Chat Completions request to a JSON file on disk.
  * It's designed specifically for Node.js environments with filesystem access.
  *
  * @example
@@ -65,8 +65,8 @@ export class FilePayloadLogger implements IPayloadLogger {
   }
 
   /**
-   * Log API payload to file
-   * @param payload - The API request payload
+   * Log a request summary to file
+   * @param payload - Summary of the outgoing Chat Completions request
    * @param type - Type of request ('chat' or 'stream')
    */
   async logPayload(payload: IOpenAILogData, type: 'chat' | 'stream' = 'chat'): Promise<void> {
@@ -89,8 +89,9 @@ export class FilePayloadLogger implements IPayloadLogger {
         payload: sanitizeOpenAILogData(payload),
       };
 
-      // SEC-003: payload logs contain prompt/response content and `logDir` is
-      // caller-supplied, so create them owner-only rather than under the process umask.
+      // SEC-003: payload logs record the caller's request history (a request summary, not
+      // prompt/response content) and `logDir` is caller-supplied, so create them owner-only
+      // rather than under the process umask.
       await fs.promises.writeFile(filepath, JSON.stringify(logData, null, 2), {
         encoding: 'utf8',
         mode: OWNER_ONLY_FILE_MODE,

package/src/openai/message-converter.ts

@@ -16,8 +16,12 @@ export function convertToOpenAIMessages(
 }
 
 /**
- * Convert tool schemas to OpenAI function tool format.
+ * Convert tool schemas to OpenAI function tool format. With `strictTools` each function is declared
+ * `strict: true`, as the Responses surface does, so strict mode is requested on both surfaces.
  */
-export function convertToOpenAITools(tools: IToolSchema[]): OpenAI.Chat.ChatCompletionTool[] {
-  return convertToOpenAICompatibleTools(tools);
+export function convertToOpenAITools(
+  tools: IToolSchema[],
+  strictTools?: boolean,
+): OpenAI.Chat.ChatCompletionTool[] {
+  return convertToOpenAICompatibleTools(tools, { strict: strictTools === true });
 }

package/src/openai/responses-parser.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+
+import { assembleOpenAIResponsesStream, parseOpenAIResponsesResponse } from './responses-parser';
+
+import type {
+  IOpenAIResponsesResponse,
+  IOpenAIResponsesUsage,
+  TOpenAIResponsesStreamEvent,
+} from './responses-types';
+
+function responseWithUsage(usage: IOpenAIResponsesUsage): IOpenAIResponsesResponse {
+  return {
+    id: 'resp-cached',
+    model: 'gpt-4o',
+    output_text: 'ok',
+    output: [],
+    status: 'completed',
+    usage,
+  };
+}
+
+function usageOf(message: unknown): Record<string, number> | undefined {
+  return (message as { usage?: Record<string, number> }).usage;
+}
+
+async function* eventsFrom(
+  events: TOpenAIResponsesStreamEvent[],
+): AsyncIterable<TOpenAIResponsesStreamEvent> {
+  for (const event of events) yield event;
+}
+
+describe('OpenAI Responses usage', () => {
+  it('surfaces input_tokens_details.cached_tokens as cacheReadTokens on the message usage', () => {
+    const message = parseOpenAIResponsesResponse(
+      responseWithUsage({
+        input_tokens: 1000,
+        output_tokens: 20,
+        total_tokens: 1020,
+        input_tokens_details: { cached_tokens: 800 },
+      }),
+    );
+
+    expect(usageOf(message)).toEqual({
+      promptTokens: 1000,
+      completionTokens: 20,
+      totalTokens: 1020,
+      cacheReadTokens: 800,
+    });
+  });
+
+  it('adds no cacheReadTokens when the usage carries no cached-token details', () => {
+    const message = parseOpenAIResponsesResponse(
+      responseWithUsage({ input_tokens: 1000, output_tokens: 20, total_tokens: 1020 }),
+    );
+
+    expect(usageOf(message)).toBeDefined();
+    expect(usageOf(message)).not.toHaveProperty('cacheReadTokens');
+  });
+
+  it('leaves totalTokens absent when the response omits total_tokens', () => {
+    const message = parseOpenAIResponsesResponse(
+      responseWithUsage({ input_tokens: 5000, output_tokens: 100 }),
+    );
+
+    expect(usageOf(message)).toEqual({ promptTokens: 5000, completionTokens: 100 });
+    expect(message.metadata?.['usageProvenance']).toBe('partial');
+  });
+
+  it('carries the cached tokens of a streamed response.completed usage', async () => {
+    const message = await assembleOpenAIResponsesStream({
+      stream: eventsFrom([
+        { type: 'response.output_text.delta', delta: 'ok' },
+        {
+          type: 'response.completed',
+          response: responseWithUsage({
+            input_tokens: 1000,
+            output_tokens: 20,
+            total_tokens: 1020,
+            input_tokens_details: { cached_tokens: 800 },
+          }),
+        },
+      ]),
+    });
+
+    expect(usageOf(message)).toMatchObject({ promptTokens: 1000, cacheReadTokens: 800 });
+  });
+});

package/src/openai/responses-parser.ts

@@ -13,7 +13,16 @@ import type {
   TOpenAIResponsesOutputItem,
   TOpenAIResponsesStreamEvent,
 } from './responses-types';
-import type { IToolCall, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import type {
+  IToolCall,
+  ITokenUsageWithCacheRead,
+  TTextDeltaCallback,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+
+/** Message usage; `totalTokens` is absent when the response omitted `total_tokens`. */
+type TResponsesMessageUsage = Omit<ITokenUsageWithCacheRead, 'totalTokens'> &
+  Partial<Pick<ITokenUsageWithCacheRead, 'totalTokens'>>;
 
 interface IOpenAIResponsesStreamAssemblyOptions {
   stream: AsyncIterable<TOpenAIResponsesStreamEvent>;
@@ -27,12 +36,6 @@ interface IOpenAIResponsesReasoningMetadata {
   hasEncryptedReasoning: boolean;
 }
 
-interface IOpenAIResponseUsage {
-  promptTokens: number;
-  completionTokens: number;
-  totalTokens: number;
-}
-
 interface IOpenAIResponsesStreamState {
   textParts: string[];
   toolCalls: IToolCall[];
@@ -191,11 +194,14 @@ function buildMetadata(
   };
 }
 
-function mapUsage(usage: IOpenAIResponsesUsage): IOpenAIResponseUsage {
+function mapUsage(usage: IOpenAIResponsesUsage): TResponsesMessageUsage {
+  const cachedTokens = usage.input_tokens_details?.cached_tokens;
   return {
     promptTokens: usage.input_tokens ?? 0,
     completionTokens: usage.output_tokens ?? 0,
-    totalTokens: usage.total_tokens ?? 0,
+    // An omitted total stays omitted: a 0 reads downstream as a real, empty call.
+    ...(usage.total_tokens !== undefined && { totalTokens: usage.total_tokens }),
+    ...(typeof cachedTokens === 'number' && { cacheReadTokens: cachedTokens }),
   };
 }
 

package/src/openai/responses-types.ts

@@ -148,6 +148,8 @@ export interface IOpenAIResponsesUsage {
   input_tokens?: number;
   output_tokens?: number;
   total_tokens?: number;
+  /** `cached_tokens` is the part of `input_tokens` served from the prompt cache. */
+  input_tokens_details?: { cached_tokens?: number } | null;
 }
 
 export interface IOpenAIResponsesErrorBody {

package/src/openai/types.ts

@@ -93,7 +93,7 @@ export interface IOpenAIProviderOptions {
    * @example
    * ```ts
    * // Vercel AI Gateway with a non-OpenAI model slug
-   * createOpenAIProvider({
+   * new OpenAIProvider({
    *   apiKey: process.env.AI_GATEWAY_API_KEY,
    *   baseURL: 'https://ai-gateway.vercel.sh/v1',
    *   defaultModel: 'anthropic/claude-sonnet-4-5',
@@ -156,6 +156,9 @@ export interface IOpenAIProviderOptions {
    * schema marked optional becomes required and gains a `null` branch. The model must then supply
    * the key explicitly, with `null` standing for "not provided". A tool whose handler distinguishes
    * an absent key from a null value will see the difference.
+   *
+   * Both surfaces declare the functions strict (`strict: true` on each tool), so an OpenAI-compatible
+   * endpoint that rejects that field needs `strictTools` left off.
    */
   strictTools?: boolean;
 
@@ -174,7 +177,9 @@ export interface IOpenAIProviderOptions {
   client?: OpenAI;
 
   /**
-   * Payload logger instance for debugging API requests/responses
+   * Payload logger that receives a summary of each Chat Completions request (model, message
+   * count, whether tools were sent, temperature, max tokens) for debugging — not prompt or
+   * response content. Not called on the Responses API surface.
    *
    * Use different implementations based on your environment:
    * - FilePayloadLogger: Node.js file-based logging

package/dist/node/payload-logger-BaW0K8yI.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"payload-logger-BaW0K8yI.d.cts","names":[],"sources":["../../src/openai/types/api-types.ts","../../src/openai/interfaces/payload-logger.ts"],"mappings":";;;;;;UAwGiB;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;UCpGe;;;;;EAKf;;;;;;EAOA,WAAW,SAAS,gBAAgB,0BAA0B;;;;;UAM/C;;;;;EAKf;;;;;EAMA;;;;;EAMA,SAAS"}

package/dist/node/payload-logger-BaW0K8yI.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"payload-logger-BaW0K8yI.d.ts","names":[],"sources":["../../src/openai/types/api-types.ts","../../src/openai/interfaces/payload-logger.ts"],"mappings":";;;;;;UAwGiB;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;UCpGe;;;;;EAKf;;;;;;EAOA,WAAW,SAAS,gBAAgB,0BAA0B;;;;;UAM/C;;;;;EAKf;;;;;EAMA;;;;;EAMA,SAAS"}