@robota-sdk/agent-provider 3.0.0-beta.64

package/src/openai/provider.ts

@@ -0,0 +1,237 @@
+import OpenAI from 'openai';
+import type { IOpenAIProviderOptions, TOpenAIApiSurface } from './types';
+import { AbstractAIProvider } from '@robota-sdk/agent-core';
+import type {
+  TUniversalMessage,
+  IChatOptions,
+  IAssistantMessage,
+  IProviderCapabilities,
+  TTextDeltaCallback,
+} from '@robota-sdk/agent-core';
+import type { IPayloadLogger } from './interfaces/payload-logger';
+import { OpenAIResponseParser } from './parsers/response-parser';
+import { SilentLogger } from '@robota-sdk/agent-core';
+import {
+  chatStreamWithOpenAIChatCompletions,
+  chatWithOpenAIChatCompletions,
+} from './chat-completions-chat';
+import { chatStreamWithOpenAIResponsesApi, chatWithOpenAIResponsesApi } from './responses-chat';
+
+/**
+ * OpenAI provider implementation for Robota
+ *
+ * Provides integration with OpenAI models through the Robota provider contract.
+ * Uses OpenAI SDK native types internally for optimal performance and feature support.
+ *
+ * @public
+ */
+export class OpenAIProvider extends AbstractAIProvider {
+  override readonly name = 'openai';
+  override readonly version = '1.0.0';
+
+  private readonly client?: OpenAI;
+  private readonly options: IOpenAIProviderOptions;
+  private readonly apiSurface: TOpenAIApiSurface;
+  private readonly payloadLogger: IPayloadLogger | undefined;
+  private readonly responseParser: OpenAIResponseParser;
+
+  /**
+   * Optional callback for text deltas during streaming.
+   * Set by the consumer (e.g., Session) to receive real-time text chunks.
+   * When set, chat() uses streaming internally while still returning
+   * the complete assembled message.
+   */
+  onTextDelta?: TTextDeltaCallback;
+
+  constructor(options: IOpenAIProviderOptions) {
+    super(options.logger || SilentLogger);
+    this.options = options;
+    this.apiSurface = resolveApiSurface(options);
+    validateOpenAIProviderNativeWebTools(this.apiSurface, options.nativeWebTools);
+
+    if (options.executor) {
+      this.executor = options.executor;
+    }
+
+    if (!this.executor) {
+      if (options.client) {
+        this.client = options.client;
+      } else if (options.apiKey) {
+        this.client = new OpenAI({
+          apiKey: options.apiKey,
+          ...(options.organization && { organization: options.organization }),
+          ...(options.timeout && { timeout: options.timeout }),
+          ...(options.baseURL && { baseURL: options.baseURL }),
+        });
+      } else {
+        throw new Error('Either OpenAI client, apiKey, or executor is required');
+      }
+    }
+
+    this.responseParser = new OpenAIResponseParser(this.logger);
+    this.payloadLogger = options.payloadLogger;
+  }
+
+  override async chat(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      try {
+        return await this.executeViaExecutorOrDirect(messages, options);
+      } catch (error) {
+        this.logger.error(
+          'OpenAI Provider executor chat error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    if (this.apiSurface === 'responses') {
+      return chatWithOpenAIResponsesApi({
+        client: this.client,
+        messages,
+        chatOptions: options,
+        providerOptions: this.options,
+        onTextDelta: this.onTextDelta,
+      });
+    }
+
+    return chatWithOpenAIChatCompletions({
+      client: this.client,
+      messages,
+      chatOptions: options,
+      providerOptions: this.options,
+      payloadLogger: this.payloadLogger,
+      responseParser: this.responseParser,
+      onTextDelta: this.onTextDelta,
+    });
+  }
+
+  override async *chatStream(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): AsyncIterable<TUniversalMessage> {
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    if (this.executor) {
+      try {
+        yield* this.executeStreamViaExecutorOrDirect(messages, options);
+        return;
+      } catch (error) {
+        this.logger.error(
+          'OpenAI Provider executor stream error:',
+          error instanceof Error ? error.message : String(error),
+        );
+        throw error;
+      }
+    }
+
+    if (this.apiSurface === 'responses') {
+      yield* chatStreamWithOpenAIResponsesApi({
+        client: this.client,
+        messages,
+        chatOptions: options,
+        providerOptions: this.options,
+        onTextDelta: this.onTextDelta,
+      });
+      return;
+    }
+
+    yield* chatStreamWithOpenAIChatCompletions({
+      client: this.client,
+      messages,
+      chatOptions: options,
+      providerOptions: this.options,
+      payloadLogger: this.payloadLogger,
+      responseParser: this.responseParser,
+      onTextDelta: this.onTextDelta,
+    });
+  }
+
+  override supportsTools(): boolean {
+    return true;
+  }
+
+  override getCapabilities(): IProviderCapabilities {
+    const source =
+      this.apiSurface === 'chat-completions'
+        ? 'openai-compatible-chat-completions'
+        : 'openai-responses';
+    return {
+      functionCalling: { supported: true },
+      nativeWebTools: {
+        webSearch: {
+          supported: false,
+          enabled: false,
+          source,
+          reason: getOpenAIUnsupportedNativeWebReason(this.apiSurface, 'search'),
+        },
+        webFetch: {
+          supported: false,
+          enabled: false,
+          source,
+          reason: getOpenAIUnsupportedNativeWebReason(this.apiSurface, 'fetch'),
+        },
+      },
+    };
+  }
+
+  override validateConfig(): boolean {
+    return !!this.client && !!this.options;
+  }
+
+  override async dispose(): Promise<void> {
+    // OpenAI client doesn't need explicit cleanup
+  }
+
+  protected override validateMessages(messages: TUniversalMessage[]): void {
+    super.validateMessages(messages);
+
+    for (const message of messages) {
+      if (message.role === 'assistant') {
+        const assistantMsg = message as IAssistantMessage;
+        if (
+          assistantMsg.toolCalls &&
+          assistantMsg.toolCalls.length > 0 &&
+          assistantMsg.content === ''
+        ) {
+          continue;
+        }
+      }
+    }
+  }
+}
+
+function resolveApiSurface(options: IOpenAIProviderOptions): TOpenAIApiSurface {
+  if (options.apiSurface !== undefined) {
+    return options.apiSurface;
+  }
+  return options.baseURL ? 'chat-completions' : 'responses';
+}
+
+function getOpenAIUnsupportedNativeWebReason(
+  apiSurface: TOpenAIApiSurface,
+  toolKind: 'search' | 'fetch',
+): string {
+  if (apiSurface === 'chat-completions') {
+    return `OpenAI-compatible Chat Completions endpoints support declared function tools, not provider-native web ${toolKind}.`;
+  }
+  return `OpenAI Responses native web ${toolKind} is not wired in this Robota provider version.`;
+}
+
+function validateOpenAIProviderNativeWebTools(
+  apiSurface: TOpenAIApiSurface,
+  nativeWebTools: IOpenAIProviderOptions['nativeWebTools'],
+): void {
+  if (nativeWebTools?.webSearch !== true && nativeWebTools?.webFetch !== true) {
+    return;
+  }
+  throw new Error(
+    `Provider openai native web search/fetch is not supported for apiSurface ${apiSurface} in this Robota provider version.`,
+  );
+}

package/src/openai/responses-chat.ts

@@ -0,0 +1,258 @@
+import { randomUUID } from 'node:crypto';
+import type OpenAI from 'openai';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import { observeProviderNativeRawPayloadStream } from '../shared/openai-compatible/index.js';
+import type { IOpenAIError } from './types/api-types';
+import type { IOpenAIProviderOptions } from './types';
+import { buildOpenAIResponsesTextConfig } from './openai-request-format';
+import {
+  convertToOpenAIResponsesInput,
+  convertToOpenAIResponsesTools,
+} from './responses-converter';
+import { assembleOpenAIResponsesStream, parseOpenAIResponsesResponse } from './responses-parser';
+import type {
+  IOpenAIResponsesRequestNonStreaming,
+  IOpenAIResponsesRequestStreaming,
+  TOpenAIResponsesStreamEvent,
+} from './responses-types';
+
+export interface IOpenAIResponsesChatOptions {
+  client?: OpenAI;
+  messages: TUniversalMessage[];
+  chatOptions?: IChatOptions;
+  providerOptions: IOpenAIProviderOptions;
+  onTextDelta?: TTextDeltaCallback;
+}
+
+interface IResponsesStreamMessageQueue {
+  deltas: TUniversalMessage[];
+  finalMessage?: TUniversalMessage;
+  error?: Error;
+  wake?: () => void;
+}
+
+export async function chatWithOpenAIResponsesApi(
+  input: IOpenAIResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+  if (textDeltaCb) {
+    return chatWithOpenAIResponsesStreamingAssembly({
+      ...input,
+      chatOptions: {
+        ...input.chatOptions,
+        onTextDelta: textDeltaCb,
+      },
+    });
+  }
+
+  if (!input.client) {
+    throw new Error('OpenAI Responses client not available.');
+  }
+
+  try {
+    const requestParams = buildResponsesRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const response = await input.client.responses.create(
+      requestParams as OpenAI.Responses.ResponseCreateParamsNonStreaming,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'response',
+      payload: response,
+    });
+    return parseOpenAIResponsesResponse(response);
+  } catch (error) {
+    const openaiError = error as IOpenAIError;
+    const errorMessage = openaiError.message || 'OpenAI Responses API request failed';
+    throw new Error(`OpenAI responses failed: ${errorMessage}`);
+  }
+}
+
+export async function* chatStreamWithOpenAIResponsesApi(
+  input: IOpenAIResponsesChatOptions,
+): AsyncIterable<TUniversalMessage> {
+  const queue: IResponsesStreamMessageQueue = { deltas: [] };
+  const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+  const assembly = chatWithOpenAIResponsesStreamingAssembly({
+    ...input,
+    chatOptions: {
+      ...input.chatOptions,
+      onTextDelta: (delta) => {
+        textDeltaCb?.(delta);
+        enqueueStreamDelta(queue, createStreamDeltaMessage(delta));
+      },
+    },
+  })
+    .then((result) => finishStreamQueue(queue, result))
+    .catch((error) => failStreamQueue(queue, toError(error)));
+
+  yield* drainResponsesStreamQueue(queue);
+  await assembly;
+}
+
+async function chatWithOpenAIResponsesStreamingAssembly(
+  input: IOpenAIResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  if (!input.client) {
+    throw new Error('OpenAI Responses client not available.');
+  }
+
+  try {
+    const requestParams = buildResponsesStreamingRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const stream = await input.client.responses.create(
+      requestParams as OpenAI.Responses.ResponseCreateParamsStreaming,
+      input.chatOptions?.signal ? { signal: input.chatOptions.signal } : undefined,
+    );
+    return assembleOpenAIResponsesStream({
+      stream: observeProviderNativeRawPayloadStream(
+        stream as AsyncIterable<TOpenAIResponsesStreamEvent>,
+        {
+          provider: 'openai',
+          apiSurface: 'responses',
+          onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+        },
+      ),
+      onTextDelta: input.chatOptions?.onTextDelta,
+      signal: input.chatOptions?.signal,
+    });
+  } catch (error) {
+    const openaiError = error as IOpenAIError;
+    const errorMessage = openaiError.message || 'OpenAI Responses streaming request failed';
+    throw new Error(`OpenAI responses stream failed: ${errorMessage}`);
+  }
+}
+
+function buildResponsesRequestParams(
+  input: IOpenAIResponsesChatOptions,
+): IOpenAIResponsesRequestNonStreaming {
+  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 tools = convertToOpenAIResponsesTools(
+    input.chatOptions?.tools,
+    input.providerOptions.strictTools,
+  );
+  const textConfig = buildOpenAIResponsesTextConfig(input.providerOptions);
+  return {
+    model,
+    input: convertToOpenAIResponsesInput(input.messages),
+    ...(tools !== undefined && { tools, tool_choice: 'auto' }),
+    ...(input.chatOptions?.temperature !== undefined && {
+      temperature: input.chatOptions.temperature,
+    }),
+    ...(input.chatOptions?.maxTokens !== undefined && {
+      max_output_tokens: input.chatOptions.maxTokens,
+    }),
+    ...(textConfig !== undefined && { text: textConfig }),
+    ...(input.providerOptions.reasoning !== undefined && {
+      reasoning: input.providerOptions.reasoning,
+    }),
+    ...(input.providerOptions.includeEncryptedReasoning === true && {
+      include: ['reasoning.encrypted_content'],
+    }),
+    ...(input.providerOptions.store !== undefined && { store: input.providerOptions.store }),
+  };
+}
+
+function buildResponsesStreamingRequestParams(
+  input: IOpenAIResponsesChatOptions,
+): IOpenAIResponsesRequestStreaming {
+  return {
+    ...buildResponsesRequestParams(input),
+    stream: true,
+  };
+}
+
+function createStreamDeltaMessage(delta: string): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: delta,
+    state: 'complete',
+    timestamp: new Date(),
+    metadata: {
+      providerApiSurface: 'responses',
+      isStreamChunk: true,
+      isComplete: false,
+    },
+  };
+}
+
+async function* drainResponsesStreamQueue(
+  queue: IResponsesStreamMessageQueue,
+): AsyncIterable<TUniversalMessage> {
+  while (true) {
+    const next = queue.deltas.shift();
+    if (next !== undefined) {
+      yield next;
+      continue;
+    }
+    if (queue.error !== undefined) {
+      throw queue.error;
+    }
+    if (queue.finalMessage !== undefined) {
+      yield createFinalStreamMessage(queue.finalMessage);
+      return;
+    }
+    await waitForStreamQueue(queue);
+  }
+}
+
+function enqueueStreamDelta(queue: IResponsesStreamMessageQueue, message: TUniversalMessage): void {
+  queue.deltas.push(message);
+  wakeStreamQueue(queue);
+}
+
+function finishStreamQueue(queue: IResponsesStreamMessageQueue, result: TUniversalMessage): void {
+  queue.finalMessage = result;
+  wakeStreamQueue(queue);
+}
+
+function failStreamQueue(queue: IResponsesStreamMessageQueue, error: Error): void {
+  queue.error = error;
+  wakeStreamQueue(queue);
+}
+
+function waitForStreamQueue(queue: IResponsesStreamMessageQueue): Promise<void> {
+  return new Promise((resolve) => {
+    queue.wake = resolve;
+  });
+}
+
+function wakeStreamQueue(queue: IResponsesStreamMessageQueue): void {
+  queue.wake?.();
+  queue.wake = undefined;
+}
+
+function createFinalStreamMessage(result: TUniversalMessage): TUniversalMessage {
+  return {
+    ...result,
+    content: '',
+    metadata: {
+      ...result.metadata,
+      isStreamChunk: true,
+      isComplete: true,
+    },
+  };
+}
+
+function toError(error: Error | string): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/openai/responses-converter.ts

@@ -0,0 +1,112 @@
+import type {
+  IAssistantMessage,
+  IToolSchema,
+  TUniversalMessage,
+  TUniversalMessagePart,
+} from '@robota-sdk/agent-core';
+import type {
+  IOpenAIResponsesFunctionTool,
+  IOpenAIResponsesMessageInput,
+  TOpenAIResponsesInputContent,
+  TOpenAIResponsesInputItem,
+} from './responses-types';
+
+export function convertToOpenAIResponsesInput(
+  messages: TUniversalMessage[],
+): TOpenAIResponsesInputItem[] {
+  return messages.flatMap((message) => convertMessage(message));
+}
+
+export function convertToOpenAIResponsesTools(
+  tools: IToolSchema[] | undefined,
+  strictTools: boolean | undefined,
+): IOpenAIResponsesFunctionTool[] | undefined {
+  const converted =
+    tools?.map((tool) => ({
+      type: 'function' as const,
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+      strict: strictTools ?? false,
+    })) ?? [];
+  return converted.length > 0 ? converted : undefined;
+}
+
+function convertMessage(message: TUniversalMessage): TOpenAIResponsesInputItem[] {
+  if (message.role === 'user') {
+    return [createMessageInput('user', getUserContent(message.content, message.parts))];
+  }
+  if (message.role === 'system') {
+    return [createMessageInput('system', message.content)];
+  }
+  if (message.role === 'tool') {
+    if (!message.toolCallId || message.toolCallId.trim().length === 0) {
+      throw new Error(`Tool message missing toolCallId: ${JSON.stringify(message)}`);
+    }
+    return [
+      {
+        type: 'function_call_output',
+        call_id: message.toolCallId,
+        output: message.content || '',
+      },
+    ];
+  }
+  return convertAssistantMessage(message);
+}
+
+function convertAssistantMessage(message: IAssistantMessage): TOpenAIResponsesInputItem[] {
+  const items: TOpenAIResponsesInputItem[] = [];
+  if (message.content && message.content.length > 0) {
+    items.push(createMessageInput('assistant', message.content));
+  }
+  for (const toolCall of message.toolCalls ?? []) {
+    items.push({
+      type: 'function_call',
+      call_id: toolCall.id,
+      name: toolCall.function.name,
+      arguments: toolCall.function.arguments,
+    });
+  }
+  if (items.length === 0) {
+    items.push(createMessageInput('assistant', ''));
+  }
+  return items;
+}
+
+function getUserContent(
+  content: string,
+  parts: TUniversalMessagePart[] | undefined,
+): string | TOpenAIResponsesInputContent[] {
+  if (!parts || parts.length === 0) {
+    return content;
+  }
+
+  const converted = parts.map((part) => convertPart(part));
+  if (content.length > 0 && !parts.some((part) => part.type === 'text')) {
+    return [{ type: 'input_text', text: content }, ...converted];
+  }
+  return converted;
+}
+
+function convertPart(part: TUniversalMessagePart): TOpenAIResponsesInputContent {
+  if (part.type === 'text') {
+    return { type: 'input_text', text: part.text };
+  }
+  if (part.type === 'image_uri') {
+    return { type: 'input_image', image_url: part.uri };
+  }
+  return {
+    type: 'input_image',
+    image_url: `data:${part.mimeType};base64,${part.data}`,
+  };
+}
+
+function createMessageInput(
+  role: IOpenAIResponsesMessageInput['role'],
+  content: string | TOpenAIResponsesInputContent[],
+): IOpenAIResponsesMessageInput {
+  return {
+    role,
+    content,
+  };
+}