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

package/src/openai/model-effort-verification-config.ts

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+
+export const VERCEL_AI_GATEWAY_BASE_URL = 'https://ai-gateway.vercel.sh/v1';
+export const VERCEL_AI_GATEWAY_MODEL = 'openai/gpt-5';
+
+export interface IVercelAiGatewayModelEffortConfig {
+  apiKey: string;
+  baseURL: string;
+  model: string;
+}
+
+export function resolveVercelAiGatewayModelEffortConfig(
+  environment: Readonly<Record<string, string | undefined>>,
+): IVercelAiGatewayModelEffortConfig {
+  const apiKey = environment.AI_GATEWAY_API_KEY;
+  if (apiKey === undefined || apiKey.length === 0) {
+    throw new Error('AI_GATEWAY_API_KEY is required');
+  }
+
+  return {
+    apiKey,
+    baseURL: VERCEL_AI_GATEWAY_BASE_URL,
+    model: VERCEL_AI_GATEWAY_MODEL,
+  };
+}
+
+export function loadVercelAiGatewayModelEffortConfig(
+  environment: Record<string, string | undefined>,
+  environmentFilePath: string,
+  environmentFileExists: (path: string) => boolean = existsSync,
+  loadEnvironmentFile: (path: string) => void = process.loadEnvFile,
+): IVercelAiGatewayModelEffortConfig {
+  if (environmentFileExists(environmentFilePath)) loadEnvironmentFile(environmentFilePath);
+  return resolveVercelAiGatewayModelEffortConfig(environment);
+}

package/src/openai/openai-request-format.ts

@@ -0,0 +1,116 @@
+import type {
+  IOpenAIResponsesTextConfig,
+  IOpenAIResponsesTextFormatJsonSchema,
+} from './responses-types';
+import type { IOpenAIProviderOptions, TOpenAIProviderOptionValue } from './types';
+import type { IChatOptions } from '@robota-sdk/agent-core';
+
+export interface IOpenAIChatTextFormatText {
+  type: 'text';
+}
+
+export interface IOpenAIChatTextFormatJsonObject {
+  type: 'json_object';
+}
+
+export interface IOpenAIChatTextFormatJsonSchema {
+  type: 'json_schema';
+  json_schema: {
+    name: string;
+    schema: Record<string, TOpenAIProviderOptionValue>;
+    description?: string;
+    strict?: boolean;
+  };
+}
+
+export type TOpenAIChatResponseFormat =
+  IOpenAIChatTextFormatText | IOpenAIChatTextFormatJsonObject | IOpenAIChatTextFormatJsonSchema;
+
+/**
+ * Merge a per-call `IChatOptions.responseFormat` onto the provider options (CORE-015).
+ * A `json_schema` chat option carries its schema payload into `jsonSchema`; the
+ * provider-level `jsonSchema` option remains as-is for `text`/`json_object`.
+ */
+export function mergeChatResponseFormat(
+  providerOptions: IOpenAIProviderOptions,
+  responseFormat: IChatOptions['responseFormat'],
+): IOpenAIProviderOptions {
+  if (responseFormat?.type === undefined) {
+    return providerOptions;
+  }
+  if (responseFormat.type === 'json_schema') {
+    return {
+      ...providerOptions,
+      responseFormat: 'json_schema',
+      jsonSchema: {
+        name: responseFormat.name ?? 'structured_output',
+        schema: responseFormat.schema as Record<string, TOpenAIProviderOptionValue>,
+      },
+    };
+  }
+  return { ...providerOptions, responseFormat: responseFormat.type };
+}
+
+export function buildOpenAIChatResponseFormat(
+  options: IOpenAIProviderOptions,
+): TOpenAIChatResponseFormat | undefined {
+  if (options.responseFormat === undefined || options.responseFormat === 'text') {
+    return undefined;
+  }
+  if (options.responseFormat === 'json_object') {
+    return { type: 'json_object' };
+  }
+
+  const schema = requireJsonSchema(options);
+  return {
+    type: 'json_schema',
+    json_schema: {
+      name: schema.name,
+      schema: schema.schema,
+      ...(schema.description !== undefined && { description: schema.description }),
+      ...(schema.strict !== undefined && { strict: schema.strict }),
+    },
+  };
+}
+
+export function buildOpenAIResponsesTextConfig(
+  options: IOpenAIProviderOptions,
+): IOpenAIResponsesTextConfig | undefined {
+  if (options.responseFormat === undefined || options.responseFormat === 'text') {
+    return undefined;
+  }
+  if (options.responseFormat === 'json_object') {
+    return { format: { type: 'json_object' } };
+  }
+
+  const schema = requireJsonSchema(options);
+  const format: IOpenAIResponsesTextFormatJsonSchema = {
+    type: 'json_schema',
+    name: schema.name,
+    schema: schema.schema,
+    ...(schema.description !== undefined && { description: schema.description }),
+    ...(schema.strict !== undefined && { strict: schema.strict }),
+  };
+  return { format };
+}
+
+function requireJsonSchema(input: IOpenAIProviderOptions): {
+  name: string;
+  schema: Record<string, TOpenAIProviderOptionValue>;
+  description?: string;
+  strict?: boolean;
+} {
+  const schema = input.jsonSchema;
+  if (input.responseFormat !== 'json_schema') {
+    throw new Error(`Unsupported OpenAI response format: ${input.responseFormat}`);
+  }
+  if (!schema?.schema) {
+    throw new Error('OpenAI jsonSchema.schema is required when responseFormat is json_schema');
+  }
+  return {
+    name: schema.name,
+    schema: schema.schema,
+    ...(schema.description !== undefined && { description: schema.description }),
+    ...(schema.strict !== undefined && { strict: schema.strict }),
+  };
+}

package/src/openai/parsers/response-parser.test.ts

@@ -0,0 +1,407 @@
+import { describe, it, expect, vi } from 'vitest';
+import { OpenAIResponseParser } from './response-parser';
+import type { ILogger } from '@robota-sdk/agent-core';
+import type OpenAI from 'openai';
+
+function createMockLogger(): ILogger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    log: vi.fn(),
+  };
+}
+
+function createChatCompletion(
+  overrides: Partial<OpenAI.Chat.ChatCompletion> = {},
+): OpenAI.Chat.ChatCompletion {
+  return {
+    id: 'chatcmpl-test',
+    object: 'chat.completion',
+    created: Date.now(),
+    model: 'gpt-4',
+    choices: [
+      {
+        index: 0,
+        message: {
+          role: 'assistant',
+          content: 'Hello!',
+          refusal: null,
+        },
+        finish_reason: 'stop',
+        logprobs: null,
+      },
+    ],
+    ...overrides,
+  } as OpenAI.Chat.ChatCompletion;
+}
+
+function createStreamChunk(
+  overrides: Record<string, unknown> = {},
+): OpenAI.Chat.ChatCompletionChunk {
+  return {
+    id: 'chatcmpl-chunk',
+    object: 'chat.completion.chunk',
+    created: Date.now(),
+    model: 'gpt-4',
+    choices: [
+      {
+        index: 0,
+        delta: { content: 'Hi' },
+        finish_reason: null,
+        logprobs: null,
+      },
+    ],
+    ...overrides,
+  } as OpenAI.Chat.ChatCompletionChunk;
+}
+
+describe('OpenAIResponseParser', () => {
+  describe('constructor', () => {
+    it('should use SilentLogger when no logger is provided', () => {
+      const parser = new OpenAIResponseParser();
+      // Parser should work without throwing
+      const response = createChatCompletion();
+      const result = parser.parseResponse(response);
+      expect(result.role).toBe('assistant');
+    });
+
+    it('should accept a custom logger', () => {
+      const logger = createMockLogger();
+      const parser = new OpenAIResponseParser(logger);
+      const response = createChatCompletion();
+      const result = parser.parseResponse(response);
+      expect(result.role).toBe('assistant');
+    });
+  });
+
+  describe('parseResponse', () => {
+    it('should parse a simple text response', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion();
+      const result = parser.parseResponse(response);
+
+      expect(result.role).toBe('assistant');
+      expect(result.content).toBe('Hello!');
+      expect(result.timestamp).toBeInstanceOf(Date);
+    });
+
+    it('should parse response with empty content as empty string', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion({
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: null, refusal: null },
+            finish_reason: 'stop',
+            logprobs: null,
+          },
+        ],
+      });
+      const result = parser.parseResponse(response);
+      expect(result.content).toBe('');
+    });
+
+    it('should parse response with tool calls', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion({
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: null,
+              refusal: null,
+              tool_calls: [
+                {
+                  id: 'call_abc',
+                  type: 'function',
+                  function: {
+                    name: 'calculate',
+                    arguments: '{"a":1,"b":2}',
+                  },
+                },
+              ],
+            },
+            finish_reason: 'tool_calls',
+            logprobs: null,
+          },
+        ],
+      });
+
+      const result = parser.parseResponse(response);
+      expect(result.role).toBe('assistant');
+      expect(result.content).toBe('');
+      expect(result).toHaveProperty('toolCalls');
+      const assistantResult = result as {
+        toolCalls: Array<{
+          id: string;
+          type: string;
+          function: { name: string; arguments: string };
+        }>;
+      };
+      expect(assistantResult.toolCalls).toHaveLength(1);
+      expect(assistantResult.toolCalls[0].id).toBe('call_abc');
+      expect(assistantResult.toolCalls[0].function.name).toBe('calculate');
+      expect(assistantResult.toolCalls[0].function.arguments).toBe('{"a":1,"b":2}');
+    });
+
+    it('should parse response with usage information', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion({
+        usage: {
+          prompt_tokens: 10,
+          completion_tokens: 20,
+          total_tokens: 30,
+        },
+      });
+
+      const result = parser.parseResponse(response);
+      expect(result).toHaveProperty('usage');
+      const withUsage = result as unknown as {
+        usage: { promptTokens: number; completionTokens: number; totalTokens: number };
+      };
+      expect(withUsage.usage.promptTokens).toBe(10);
+      expect(withUsage.usage.completionTokens).toBe(20);
+      expect(withUsage.usage.totalTokens).toBe(30);
+    });
+
+    it('should include finishReason in metadata', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion();
+      const result = parser.parseResponse(response);
+      expect(result.metadata?.finishReason).toBe('stop');
+    });
+
+    it('should throw when response has no choices', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion({ choices: [] });
+
+      expect(() => parser.parseResponse(response)).toThrow('OpenAI response parsing failed');
+    });
+
+    it('should throw with descriptive error and log on parsing failure', () => {
+      const logger = createMockLogger();
+      const parser = new OpenAIResponseParser(logger);
+      const response = createChatCompletion({ choices: [] });
+
+      expect(() => parser.parseResponse(response)).toThrow(
+        'OpenAI response parsing failed: No choices found in OpenAI response',
+      );
+      expect(logger.error).toHaveBeenCalled();
+    });
+
+    it('should handle response without usage field', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion();
+      // Default createChatCompletion has no usage
+      const result = parser.parseResponse(response);
+      expect(result).not.toHaveProperty('usage');
+    });
+
+    it('should parse response with multiple tool calls', () => {
+      const parser = new OpenAIResponseParser();
+      const response = createChatCompletion({
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: null,
+              refusal: null,
+              tool_calls: [
+                {
+                  id: 'call_1',
+                  type: 'function',
+                  function: { name: 'fn1', arguments: '{}' },
+                },
+                {
+                  id: 'call_2',
+                  type: 'function',
+                  function: { name: 'fn2', arguments: '{"x":1}' },
+                },
+              ],
+            },
+            finish_reason: 'tool_calls',
+            logprobs: null,
+          },
+        ],
+      });
+
+      const result = parser.parseResponse(response);
+      const assistantResult = result as { toolCalls: Array<{ id: string }> };
+      expect(assistantResult.toolCalls).toHaveLength(2);
+      expect(assistantResult.toolCalls[0].id).toBe('call_1');
+      expect(assistantResult.toolCalls[1].id).toBe('call_2');
+    });
+  });
+
+  describe('parseStreamingChunk', () => {
+    it('should parse a chunk with content', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk();
+      const result = parser.parseStreamingChunk(chunk);
+
+      expect(result).not.toBeNull();
+      expect(result!.role).toBe('assistant');
+      expect(result!.content).toBe('Hi');
+      expect(result!.metadata?.isStreamChunk).toBe(true);
+      expect(result!.metadata?.isComplete).toBe(false);
+    });
+
+    it('should return null when chunk has no choices', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({ choices: [] });
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result).toBeNull();
+    });
+
+    it('should handle chunk with empty content', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: { content: '' },
+            finish_reason: null,
+          },
+        ],
+      });
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result).not.toBeNull();
+      expect(result!.content).toBe('');
+    });
+
+    it('should mark chunk as complete when finish_reason is stop', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: { content: '' },
+            finish_reason: 'stop',
+          },
+        ],
+      });
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result!.metadata?.isComplete).toBe(true);
+    });
+
+    it('should mark chunk as complete when finish_reason is tool_calls', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: { content: '' },
+            finish_reason: 'tool_calls',
+          },
+        ],
+      });
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result!.metadata?.isComplete).toBe(true);
+    });
+
+    it('should parse chunk with tool calls', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  id: 'call_stream_1',
+                  type: 'function',
+                  function: {
+                    name: 'search',
+                    arguments: '{"q":"test"}',
+                  },
+                },
+              ],
+            },
+            finish_reason: null,
+          },
+        ],
+      });
+
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result).not.toBeNull();
+      expect(result!.role).toBe('assistant');
+      expect(result!.content).toBe('');
+      const withToolCalls = result as unknown as {
+        toolCalls: Array<{ id: string; function: { name: string; arguments: string } }>;
+      };
+      expect(withToolCalls.toolCalls).toHaveLength(1);
+      expect(withToolCalls.toolCalls[0].id).toBe('call_stream_1');
+      expect(withToolCalls.toolCalls[0].function.name).toBe('search');
+    });
+
+    it('should handle chunk with tool calls missing optional fields', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  index: 0,
+                  // Missing id, function.name, function.arguments
+                },
+              ],
+            },
+            finish_reason: null,
+          },
+        ],
+      });
+
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result).not.toBeNull();
+      const withToolCalls = result as unknown as {
+        toolCalls: Array<{ id: string; function: { name: string; arguments: string } }>;
+      };
+      expect(withToolCalls.toolCalls[0].id).toBe('');
+      expect(withToolCalls.toolCalls[0].function.name).toBe('');
+      expect(withToolCalls.toolCalls[0].function.arguments).toBe('');
+    });
+
+    it('should handle chunk with no delta content (undefined)', () => {
+      const parser = new OpenAIResponseParser();
+      const chunk = createStreamChunk({
+        choices: [
+          {
+            index: 0,
+            delta: {},
+            finish_reason: null,
+          },
+        ],
+      });
+      const result = parser.parseStreamingChunk(chunk);
+      expect(result).not.toBeNull();
+      expect(result!.content).toBe('');
+    });
+
+    it('should throw with descriptive error on parsing failure', () => {
+      const logger = createMockLogger();
+      const parser = new OpenAIResponseParser(logger);
+
+      // Force an error by passing a chunk that causes internal error
+      const badChunk = {
+        choices: [
+          {
+            get delta(): never {
+              throw new Error('Access error');
+            },
+            finish_reason: null,
+          },
+        ],
+      } as unknown as OpenAI.Chat.ChatCompletionChunk;
+
+      expect(() => parser.parseStreamingChunk(badChunk)).toThrow('OpenAI chunk parsing failed');
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+});

package/src/openai/parsers/response-parser.ts

@@ -0,0 +1,48 @@
+import { OpenAICompatibleResponseParser } from '@robota-sdk/agent-provider-openai-compatible/shared';
+
+import type { ILogger, TUniversalMessage } from '@robota-sdk/agent-core';
+import type OpenAI from 'openai';
+
+/**
+ * OpenAI response parser compatibility wrapper.
+ *
+ * The implementation delegates to the shared OpenAI-compatible parser while
+ * preserving the OpenAI-branded error messages that are part of this package's
+ * current test contract.
+ */
+export class OpenAIResponseParser {
+  private readonly parser: OpenAICompatibleResponseParser;
+
+  constructor(logger?: ILogger) {
+    this.parser = new OpenAICompatibleResponseParser({ logger });
+  }
+
+  parseResponse(response: OpenAI.Chat.ChatCompletion): TUniversalMessage {
+    try {
+      return this.parser.parseResponse(response);
+    } catch (error) {
+      const message = normalizeParserMessage(
+        error instanceof Error ? error.message : 'OpenAI response parsing failed',
+      );
+      throw new Error(`OpenAI response parsing failed: ${message}`);
+    }
+  }
+
+  parseStreamingChunk(chunk: OpenAI.Chat.ChatCompletionChunk): TUniversalMessage | null {
+    try {
+      return this.parser.parseStreamingChunk(chunk);
+    } catch (error) {
+      const message = normalizeParserMessage(
+        error instanceof Error ? error.message : 'OpenAI chunk parsing failed',
+      );
+      throw new Error(`OpenAI chunk parsing failed: ${message}`);
+    }
+  }
+}
+
+function normalizeParserMessage(message: string): string {
+  return message
+    .replace(/^OpenAI-compatible response parsing failed: /, '')
+    .replace(/^OpenAI-compatible chunk parsing failed: /, '')
+    .replace('OpenAI-compatible response', 'OpenAI response');
+}

package/src/openai/provider-definition.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createOpenAIProviderDefinition,
+  DEFAULT_OPENAI_PROVIDER_API_KEY_REFERENCE,
+  DEFAULT_OPENAI_PROVIDER_MODEL,
+} from './index';
+
+describe('createOpenAIProviderDefinition', () => {
+  it('uses official OpenAI setup defaults without a model-family default', () => {
+    const definition = createOpenAIProviderDefinition();
+    const modelStep = definition.setupSteps?.find((step) => step.key === 'model');
+    const apiKeyStep = definition.setupSteps?.find((step) => step.key === 'apiKey');
+
+    expect(DEFAULT_OPENAI_PROVIDER_MODEL).toBeUndefined();
+    expect(definition.defaults?.model).toBeUndefined();
+    expect(definition.defaults?.apiKey).toBe(DEFAULT_OPENAI_PROVIDER_API_KEY_REFERENCE);
+    expect(definition.defaults?.baseURL).toBeUndefined();
+    expect(definition.displayName).toBe('OpenAI');
+    expect(definition.setupHelpLinks).toEqual([
+      {
+        kind: 'api-key',
+        label: 'OpenAI API keys',
+        url: 'https://platform.openai.com/api-keys',
+        sourceUrl: 'https://developers.openai.com/api/reference/overview#authentication',
+        lastVerifiedAt: '2026-05-08',
+      },
+    ]);
+    expect(modelStep).toMatchObject({
+      key: 'model',
+      title: 'OpenAI model',
+      required: true,
+    });
+    expect(modelStep?.defaultValue).toBeUndefined();
+    expect(apiKeyStep).toMatchObject({
+      key: 'apiKey',
+      title: 'OpenAI API key',
+      defaultValue: '$ENV:OPENAI_API_KEY',
+    });
+  });
+
+  it('passes explicit apiSurface provider options into construction', () => {
+    const definition = createOpenAIProviderDefinition();
+
+    const provider = definition.createProvider({
+      name: 'openai',
+      model: 'gpt-4o',
+      apiKey: 'sk-test',
+      options: { apiSurface: 'chat-completions' },
+    });
+
+    expect(provider.name).toBe('openai');
+  });
+
+  it('rejects native web tools for OpenAI-compatible baseURL profiles', () => {
+    const definition = createOpenAIProviderDefinition();
+
+    expect(() =>
+      definition.createProvider({
+        name: 'openai',
+        model: 'local-model',
+        apiKey: 'lm-studio',
+        baseURL: 'http://localhost:1234/v1',
+        options: {
+          builtInWebTools: {
+            webSearch: true,
+            webFetch: true,
+          },
+        },
+      }),
+    ).toThrow(
+      'Provider openai profile uses an OpenAI-compatible Chat Completions endpoint; native web search/fetch is not supported for this profile.',
+    );
+  });
+});