@robota-sdk/agent-provider-openai 3.0.0-beta.63 → 3.0.0-beta.81

package/src/openai/chat-completions-chat.ts

@@ -0,0 +1,225 @@
+import { toProviderError } from '@robota-sdk/agent-core';
+import {
+  observeProviderNativeRawPayloadStream,
+  toOpenAICompatibleToolChoice,
+} from '@robota-sdk/agent-provider-openai-compatible/shared';
+
+import { convertToOpenAIMessages, convertToOpenAITools } from './message-converter';
+import { buildOpenAIChatResponseFormat, mergeChatResponseFormat } from './openai-request-format';
+import {
+  awaitWithProviderRequestId,
+  readOpenAIRequestId,
+  withProviderRequestId,
+} from './request-id';
+import { openAIRequestOptions } from './request-options';
+import { assembleOpenAIStream } from './streaming/stream-assembler';
+
+import type { IPayloadLogger } from './interfaces/payload-logger';
+import type { OpenAIResponseParser } from './parsers/response-parser';
+import type { IOpenAIProviderOptions } from './types';
+import type { IOpenAILogData } from './types/api-types';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import type OpenAI from 'openai';
+
+export interface IOpenAIChatCompletionsOptions {
+  client?: OpenAI;
+  messages: TUniversalMessage[];
+  chatOptions?: IChatOptions;
+  providerOptions: IOpenAIProviderOptions;
+  payloadLogger?: IPayloadLogger;
+  responseParser: OpenAIResponseParser;
+  onTextDelta?: TTextDeltaCallback;
+  /** Per-request headers (trusted `traceparent`), sent after the raw request payload is captured. */
+  requestHeaders?: Readonly<Record<string, string>>;
+}
+
+export async function chatWithOpenAIChatCompletions(
+  input: IOpenAIChatCompletionsOptions,
+): Promise<TUniversalMessage> {
+  const client = requireClient(input.client);
+
+  try {
+    const requestParams = buildChatRequestParams(input);
+    const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+    if (textDeltaCb) {
+      return await chatWithStreamingAssembly(client, input, {
+        ...requestParams,
+        stream: true,
+        ...buildStreamOptions(input),
+      });
+    }
+
+    await logPayload(input, requestParams, 'chat');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const requestOptions = openAIRequestOptions(undefined, input.requestHeaders);
+    const response = requestOptions
+      ? await client.chat.completions.create(requestParams, requestOptions)
+      : await client.chat.completions.create(requestParams);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'response',
+      payload: response,
+    });
+    return withProviderRequestId(
+      input.responseParser.parseResponse(response),
+      readOpenAIRequestId(response),
+    );
+  } catch (error) {
+    throw toProviderError(error, 'openai', 'OpenAI chat failed');
+  }
+}
+
+export async function* chatStreamWithOpenAIChatCompletions(
+  input: IOpenAIChatCompletionsOptions,
+): AsyncIterable<TUniversalMessage> {
+  const client = requireClient(input.client);
+
+  try {
+    const requestParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming = {
+      ...buildChatRequestParams(input),
+      stream: true,
+      ...buildStreamOptions(input),
+    };
+
+    await logPayload(input, requestParams, 'stream');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const { data: stream, providerRequestId } = await awaitWithProviderRequestId(
+      client.chat.completions.create(
+        requestParams,
+        openAIRequestOptions(input.chatOptions?.signal, input.requestHeaders),
+      ),
+    );
+
+    for await (const chunk of observeProviderNativeRawPayloadStream(stream, {
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+    })) {
+      const universalMessage = input.responseParser.parseStreamingChunk(chunk);
+      if (universalMessage) {
+        yield withProviderRequestId(universalMessage, providerRequestId);
+      }
+    }
+  } catch (error) {
+    throw toProviderError(error, 'openai', 'OpenAI stream failed');
+  }
+}
+
+/**
+ * Streaming requests opt into token usage via `stream_options: { include_usage: true }`
+ * unless the provider sets `includeStreamUsage: false`. Only ever sent on streaming requests.
+ */
+function buildStreamOptions(
+  input: IOpenAIChatCompletionsOptions,
+): { stream_options: { include_usage: true } } | Record<string, never> {
+  if (input.providerOptions.includeStreamUsage === false) {
+    return {};
+  }
+  return { stream_options: { include_usage: true } };
+}
+
+function buildChatRequestParams(
+  input: IOpenAIChatCompletionsOptions,
+): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+  const openaiMessages = convertToOpenAIMessages(input.messages);
+  const model = input.chatOptions?.model ?? input.providerOptions.defaultModel;
+  if (!model) {
+    throw new Error(
+      'Model is required in chat options. Please specify a model in defaultModel configuration.',
+    );
+  }
+
+  const responseFormat = buildOpenAIChatResponseFormat(
+    mergeChatResponseFormat(input.providerOptions, input.chatOptions?.responseFormat),
+  );
+  return {
+    model,
+    messages: openaiMessages,
+    ...(input.chatOptions?.temperature !== undefined && {
+      temperature: input.chatOptions.temperature,
+    }),
+    ...(input.chatOptions?.maxTokens !== undefined && { max_tokens: input.chatOptions.maxTokens }),
+    ...(input.chatOptions?.tools && {
+      tools: convertToOpenAITools(input.chatOptions.tools),
+      tool_choice: toOpenAICompatibleToolChoice(input.chatOptions.toolChoice),
+    }),
+    ...(responseFormat !== undefined && { response_format: responseFormat }),
+  } as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming;
+}
+
+async function chatWithStreamingAssembly(
+  client: OpenAI,
+  input: IOpenAIChatCompletionsOptions,
+  requestParams: OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+): Promise<TUniversalMessage> {
+  try {
+    await logPayload(input, requestParams, 'stream');
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'chat-completions',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const { data: stream, providerRequestId } = await awaitWithProviderRequestId(
+      client.chat.completions.create(
+        requestParams,
+        openAIRequestOptions(input.chatOptions?.signal, input.requestHeaders),
+      ),
+    );
+
+    const assembled = await assembleOpenAIStream({
+      stream: observeProviderNativeRawPayloadStream(stream, {
+        provider: 'openai',
+        apiSurface: 'chat-completions',
+        onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+      }),
+      onTextDelta: input.chatOptions?.onTextDelta ?? input.onTextDelta,
+      signal: input.chatOptions?.signal,
+    });
+    return withProviderRequestId(assembled, providerRequestId);
+  } catch (error) {
+    throw toProviderError(error, 'openai', 'OpenAI stream failed');
+  }
+}
+
+async function logPayload(
+  input: IOpenAIChatCompletionsOptions,
+  requestParams:
+    | OpenAI.Chat.ChatCompletionCreateParamsNonStreaming
+    | OpenAI.Chat.ChatCompletionCreateParamsStreaming,
+  type: 'chat' | 'stream',
+): Promise<void> {
+  if (!input.payloadLogger?.isEnabled()) {
+    return;
+  }
+
+  const logData: IOpenAILogData = {
+    model: requestParams.model,
+    messagesCount: requestParams.messages.length,
+    hasTools: !!requestParams.tools,
+    temperature: requestParams.temperature ?? undefined,
+    maxTokens: requestParams.max_tokens ?? undefined,
+    timestamp: new Date().toISOString(),
+  };
+  await input.payloadLogger.logPayload(logData, type);
+}
+
+function requireClient(client: OpenAI | undefined): OpenAI {
+  if (!client) {
+    throw new Error(
+      'OpenAI client not available. Either provide a client/apiKey or use an executor.',
+    );
+  }
+  return client;
+}

package/src/openai/executor-integration.test.ts

@@ -0,0 +1,213 @@
+import { OpenAIProvider } from './provider';
+import { LocalExecutor } from '@robota-sdk/agent-core';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+describe('OpenAI Provider Executor Integration', () => {
+  let localExecutor: LocalExecutor;
+  let provider: OpenAIProvider;
+
+  beforeEach(() => {
+    localExecutor = new LocalExecutor();
+
+    // Create a mock provider to register with the executor
+    const mockProvider = {
+      name: 'openai',
+      async chat(messages: TUniversalMessage[]): Promise<TUniversalMessage> {
+        return {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'assistant' as const,
+          content: `Mock response: ${messages[messages.length - 1]?.content}`,
+          timestamp: new Date(),
+        };
+      },
+      async *chatStream(messages: TUniversalMessage[]): AsyncIterable<TUniversalMessage> {
+        const chunks = ['Mock', ' streaming', ' response'];
+        for (const chunk of chunks) {
+          yield {
+            id: 'msg-1',
+            state: 'complete' as const,
+            role: 'assistant' as const,
+            content: chunk,
+            timestamp: new Date(),
+          };
+        }
+      },
+      supportsTools: () => true,
+      validateConfig: () => true,
+      dispose: async () => {},
+    };
+
+    localExecutor.registerProvider('openai', mockProvider);
+
+    // Create provider with executor (no API key needed)
+    provider = new OpenAIProvider({
+      executor: localExecutor,
+    });
+  });
+
+  afterEach(async () => {
+    await provider.dispose();
+  });
+
+  describe('Provider with Executor', () => {
+    it('should use executor for chat requests', async () => {
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      const options = {
+        model: 'gpt-4',
+        temperature: 0.7,
+      };
+
+      const response = await provider.chat(messages, options);
+
+      expect(response.role).toBe('assistant');
+      expect(response.content).toContain('Mock response: Hello!');
+    });
+
+    it('should use executor for streaming chat requests', async () => {
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Tell me a story',
+          timestamp: new Date(),
+        },
+      ];
+
+      const options = {
+        model: 'gpt-4',
+        temperature: 0.7,
+      };
+
+      const chunks: string[] = [];
+      for await (const chunk of provider.chatStream(messages, options)) {
+        if (chunk.content) {
+          chunks.push(chunk.content);
+        }
+      }
+
+      expect(chunks).toEqual(['Mock', ' streaming', ' response']);
+    });
+
+    it('should handle executor errors gracefully', async () => {
+      // Create provider with executor that doesn't have registered provider
+      const errorExecutor = new LocalExecutor();
+      const errorProvider = new OpenAIProvider({
+        executor: errorExecutor,
+      });
+
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      await expect(errorProvider.chat(messages, { model: 'gpt-4' })).rejects.toThrow(
+        'Provider "openai" not registered with LocalExecutor',
+      );
+
+      await errorProvider.dispose();
+    });
+
+    it('should support tools when executor supports tools', () => {
+      expect(provider.supportsTools()).toBe(true);
+    });
+
+    it('should validate configuration with executor', () => {
+      // Provider with executor should validate successfully
+      expect(provider.supportsTools()).toBe(true);
+    });
+
+    it('does not dispose an INJECTED executor, whose lifecycle its creator owns', async () => {
+      // HARNESS-052. This test previously read `should clean up executor when provider is
+      // disposed` and asserted `expect(true).toBe(true)` — a claim the assertion could not check
+      // and which `OpenAIProvider.dispose()` does not in fact make: it is empty. The executor is
+      // constructor-injected, so disposing it here would tear down a dependency the caller still
+      // owns and may share with other providers. This asserts the real contract, and goes RED if
+      // provider disposal ever starts reaching into the injected executor.
+      const executorDispose = vi.spyOn(localExecutor, 'dispose');
+
+      await provider.dispose();
+
+      expect(executorDispose).not.toHaveBeenCalled();
+      // The executor stays usable after the provider that borrowed it is gone.
+      expect(localExecutor.getProvider('openai')).toBeDefined();
+    });
+  });
+
+  describe('Provider without Executor', () => {
+    it('should require either client, apiKey, or executor', () => {
+      expect(() => {
+        new OpenAIProvider({});
+      }).toThrow('Either OpenAI client, apiKey, or executor is required');
+    });
+
+    it('should work with API key (traditional mode)', () => {
+      const apiKeyProvider = new OpenAIProvider({
+        apiKey: 'sk-test-key',
+      });
+
+      expect(apiKeyProvider.name).toBe('openai');
+      expect(apiKeyProvider.version).toBe('1.0.0');
+    });
+
+    it('should work with client (traditional mode)', () => {
+      const mockClient = {} as any; // Mock OpenAI client
+      const clientProvider = new OpenAIProvider({
+        client: mockClient,
+      });
+
+      expect(clientProvider.name).toBe('openai');
+      expect(clientProvider.version).toBe('1.0.0');
+    });
+  });
+
+  describe('Mixed Mode Validation', () => {
+    it('should prioritize executor over direct API when both are provided', async () => {
+      const mixedProvider = new OpenAIProvider({
+        apiKey: 'sk-test-key',
+        executor: localExecutor,
+      });
+
+      // Should use executor, not direct API
+      const messages: TUniversalMessage[] = [
+        {
+          id: 'msg-1',
+          state: 'complete' as const,
+          role: 'user',
+          content: 'Hello!',
+          timestamp: new Date(),
+        },
+      ];
+
+      const response = await mixedProvider.chat(messages, { model: 'gpt-4' });
+      expect(response.content).toContain('Mock response:');
+
+      await mixedProvider.dispose();
+    });
+
+    it('should handle executor initialization properly', () => {
+      const provider = new OpenAIProvider({
+        executor: localExecutor,
+      });
+
+      // Check that executor was set correctly
+      expect((provider as any).executor).toBe(localExecutor);
+      expect((provider as any).client).toBeUndefined();
+    });
+  });
+});

package/src/openai/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @robota-sdk/agent-provider (openai)
+ *
+ * Provides Provider implementation for using OpenAI API.
+ */
+
+// Export main provider (new architecture)
+export { OpenAIProvider } from './provider';
+
+// Export types and utilities
+export * from './types';
+export * from './adapter';
+export * from './provider-definition';
+
+// Export payload logging interfaces only (implementations are in separate subpaths)
+export type { IPayloadLogger, IPayloadLoggerOptions } from './interfaces/payload-logger';
+
+// Export modular components (optional - for advanced users)
+// export { OpenAIResponseParser } from './parsers/response-parser';

package/src/openai/interfaces/payload-logger.ts

@@ -0,0 +1,48 @@
+import type { IOpenAILogData } from '../types/api-types';
+import type { ILogger } from '@robota-sdk/agent-core';
+
+/**
+ * IPayloadLogger interface for logging OpenAI API payloads
+ *
+ * This interface provides a contract for different logging implementations:
+ * - FilePayloadLogger: Node.js file-based logging
+ * - ConsolePayloadLogger: Browser console-based logging
+ * - Custom implementations: User-defined loggers
+ */
+export interface IPayloadLogger {
+  /**
+   * Check if logging is enabled
+   * @returns true if logging is active, false otherwise
+   */
+  isEnabled(): boolean;
+
+  /**
+   * Log API payload data
+   * @param payload - The API request/response payload data
+   * @param type - Type of operation ('chat' or 'stream')
+   */
+  logPayload(payload: IOpenAILogData, type: 'chat' | 'stream'): Promise<void>;
+}
+
+/**
+ * Configuration options for payload loggers
+ */
+export interface IPayloadLoggerOptions {
+  /**
+   * Whether logging is enabled
+   * @defaultValue true
+   */
+  enabled?: boolean;
+
+  /**
+   * Include timestamp in log entries
+   * @defaultValue true
+   */
+  includeTimestamp?: boolean;
+
+  /**
+   * Logger instance for console output
+   * @defaultValue SilentLogger
+   */
+  logger?: ILogger;
+}

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

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ConsolePayloadLogger } from './console-payload-logger';
+import type { ILogger } from '@robota-sdk/agent-core';
+import type { IOpenAILogData } from '../types/api-types';
+
+function createMockLogger(): ILogger & {
+  group: ReturnType<typeof vi.fn>;
+  groupEnd: ReturnType<typeof vi.fn>;
+} {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    log: vi.fn(),
+    group: vi.fn(),
+    groupEnd: vi.fn(),
+  };
+}
+
+function createSamplePayload(): IOpenAILogData {
+  return {
+    model: 'gpt-4',
+    messagesCount: 3,
+    hasTools: true,
+    temperature: 0.7,
+    maxTokens: 1000,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  };
+}
+
+describe('ConsolePayloadLogger', () => {
+  describe('constructor', () => {
+    it('should default to enabled', () => {
+      const logger = new ConsolePayloadLogger();
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should respect enabled option set to false', () => {
+      const logger = new ConsolePayloadLogger({ enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+
+    it('should accept custom logger', () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      expect(logger.isEnabled()).toBe(true);
+    });
+  });
+
+  describe('isEnabled', () => {
+    it('should return true when enabled', () => {
+      const logger = new ConsolePayloadLogger({ enabled: true });
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should return false when disabled', () => {
+      const logger = new ConsolePayloadLogger({ enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+  });
+
+  describe('logPayload', () => {
+    it('should log payload to console with chat type', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('[OpenAI CHAT]'));
+      expect(mockLogger.info).toHaveBeenCalled();
+      expect(mockLogger.debug).toHaveBeenCalled();
+      expect(mockLogger.groupEnd).toHaveBeenCalled();
+    });
+
+    it('should log payload with stream type', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'stream');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('[OpenAI STREAM]'));
+    });
+
+    it('should include timestamp in group title when includeTimestamp is true', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        includeTimestamp: true,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining(payload.timestamp));
+    });
+
+    it('should not include timestamp when includeTimestamp is false', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        includeTimestamp: false,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const groupCall = mockLogger.group.mock.calls[0][0] as string;
+      expect(groupCall).not.toContain(payload.timestamp);
+    });
+
+    it('should skip logging when disabled', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({
+        logger: mockLogger,
+        enabled: false,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).not.toHaveBeenCalled();
+      expect(mockLogger.info).not.toHaveBeenCalled();
+      expect(mockLogger.debug).not.toHaveBeenCalled();
+    });
+
+    it('should not throw on internal error and log the error', async () => {
+      const mockLogger = createMockLogger();
+      // Make group throw an error
+      mockLogger.group.mockImplementation(() => {
+        throw new Error('Console error');
+      });
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      // Should not throw
+      await expect(logger.logPayload(payload, 'chat')).resolves.toBeUndefined();
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('[ConsolePayloadLogger]'),
+        expect.any(String),
+      );
+    });
+
+    it('should log request details with payload fields', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          model: 'gpt-4',
+          messagesCount: 3,
+          hasTools: true,
+        }),
+      );
+    });
+
+    it('should default type to chat', async () => {
+      const mockLogger = createMockLogger();
+      const logger = new ConsolePayloadLogger({ logger: mockLogger });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(mockLogger.group).toHaveBeenCalledWith(expect.stringContaining('CHAT'));
+    });
+  });
+});