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

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

@@ -0,0 +1,47 @@
+import type OpenAI from 'openai';
+import type { ILogger, TUniversalMessage } from '@robota-sdk/agent-core';
+import { OpenAICompatibleResponseParser } from '../../shared/openai-compatible/index.js';
+
+/**
+ * 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,75 @@
+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',
+    });
+    expect(typeof definition.refreshModelCatalog).toBe('function');
+  });
+
+  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.',
+    );
+  });
+});

package/src/openai/provider-definition.ts

@@ -0,0 +1,132 @@
+import type { IProviderDefinition, TUniversalValue } from '@robota-sdk/agent-core';
+import { probeOpenAICompatibleProfile } from '../shared/openai-compatible/index.js';
+import { refreshOpenAIModelCatalog } from './model-catalog-refresh';
+import { OpenAIProvider } from './provider';
+import type { IOpenAINativeWebToolsOptions, TOpenAIApiSurface } from './types';
+
+export const DEFAULT_OPENAI_PROVIDER_MODEL: string | undefined = undefined;
+export const DEFAULT_OPENAI_PROVIDER_API_KEY_REFERENCE = '$ENV:OPENAI_API_KEY';
+const OPENAI_API_KEY_URL = 'https://platform.openai.com/api-keys';
+const OPENAI_SETUP_SOURCE_URL =
+  'https://developers.openai.com/api/reference/overview#authentication';
+const OPENAI_SETUP_LAST_VERIFIED_AT = '2026-05-08';
+const OPENAI_SETUP_HELP_LINKS: NonNullable<IProviderDefinition['setupHelpLinks']> = [
+  {
+    kind: 'api-key',
+    label: 'OpenAI API keys',
+    url: OPENAI_API_KEY_URL,
+    sourceUrl: OPENAI_SETUP_SOURCE_URL,
+    lastVerifiedAt: OPENAI_SETUP_LAST_VERIFIED_AT,
+  },
+];
+
+export function createOpenAIProviderDefinition(): IProviderDefinition {
+  return {
+    type: 'openai',
+    displayName: 'OpenAI',
+    description: 'Official OpenAI Responses API provider',
+    defaults: {
+      apiKey: DEFAULT_OPENAI_PROVIDER_API_KEY_REFERENCE,
+    },
+    modelCatalog: {
+      status: 'unavailable',
+      sourceUrl: 'https://platform.openai.com/docs/api-reference/models/list',
+      message: 'OpenAI model availability should be discovered live from GET /v1/models.',
+    },
+    setupHelpLinks: OPENAI_SETUP_HELP_LINKS,
+    setupSteps: [
+      {
+        key: 'model',
+        title: 'OpenAI model',
+        required: true,
+      },
+      {
+        key: 'apiKey',
+        title: 'OpenAI API key',
+        defaultValue: DEFAULT_OPENAI_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+    ],
+    requiresApiKey: true,
+    probeProfile: probeOpenAICompatibleProfile,
+    refreshModelCatalog: ({ profile }) => refreshOpenAIModelCatalog(profile),
+    modelCatalogCacheTtlSeconds: 86400,
+    createProvider: (config) => {
+      const apiSurface = readApiSurface(config.options);
+      const nativeWebTools = readNativeWebTools(config.options);
+      validateOpenAINativeWebTools(config.baseURL, apiSurface, nativeWebTools);
+      return new OpenAIProvider({
+        apiKey: requireApiKey(config.apiKey),
+        ...(config.baseURL !== undefined && { baseURL: config.baseURL }),
+        ...(config.timeout !== undefined && { timeout: config.timeout }),
+        ...(apiSurface !== undefined && { apiSurface }),
+        ...(nativeWebTools !== undefined && { nativeWebTools }),
+        defaultModel: config.model,
+      });
+    },
+  };
+}
+
+function requireApiKey(apiKey: string | undefined): string {
+  if (!apiKey) {
+    throw new Error('Provider openai requires apiKey');
+  }
+  return apiKey;
+}
+
+function readApiSurface(
+  options: Record<string, TUniversalValue> | undefined,
+): TOpenAIApiSurface | undefined {
+  const apiSurface = options?.['apiSurface'];
+  if (apiSurface === 'responses' || apiSurface === 'chat-completions') {
+    return apiSurface;
+  }
+  return undefined;
+}
+
+function readNativeWebTools(
+  options: Record<string, TUniversalValue> | undefined,
+): IOpenAINativeWebToolsOptions | undefined {
+  const nativeWebTools =
+    readNativeWebToolsRecord(options?.['nativeWebTools']) ??
+    readNativeWebToolsRecord(options?.['builtInWebTools']);
+  if (nativeWebTools === undefined) {
+    return undefined;
+  }
+  return nativeWebTools;
+}
+
+function readNativeWebToolsRecord(
+  value: TUniversalValue | undefined,
+): IOpenAINativeWebToolsOptions | undefined {
+  if (value === null || value === undefined || value instanceof Date || Array.isArray(value)) {
+    return undefined;
+  }
+  if (typeof value !== 'object') {
+    return undefined;
+  }
+  const webSearch = value['webSearch'];
+  const webFetch = value['webFetch'];
+  return {
+    ...(typeof webSearch === 'boolean' && { webSearch }),
+    ...(typeof webFetch === 'boolean' && { webFetch }),
+  };
+}
+
+function validateOpenAINativeWebTools(
+  baseURL: string | undefined,
+  apiSurface: TOpenAIApiSurface | undefined,
+  nativeWebTools: IOpenAINativeWebToolsOptions | undefined,
+): void {
+  if (nativeWebTools?.webSearch !== true && nativeWebTools?.webFetch !== true) {
+    return;
+  }
+  if (baseURL !== undefined || apiSurface === 'chat-completions') {
+    throw new Error(
+      'Provider openai profile uses an OpenAI-compatible Chat Completions endpoint; native web search/fetch is not supported for this profile. Use Robota local WebSearch/WebFetch tools or a provider with documented hosted web support.',
+    );
+  }
+  throw new Error(
+    'Provider openai native web search/fetch is not wired in this Robota provider version. Use Robota local WebSearch/WebFetch tools or a provider with documented hosted web support.',
+  );
+}