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

package/src/openai/model-catalog-refresh.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  IOpenAIModelCatalogFetchInit,
+  IOpenAIModelCatalogFetchResponse,
+} from './model-catalog-refresh';
+import { refreshOpenAIModelCatalog } from './model-catalog-refresh';
+
+function createModelCatalogResponse(
+  body: IOpenAIModelCatalogFetchResponse['json'],
+): IOpenAIModelCatalogFetchResponse {
+  return {
+    ok: true,
+    status: 200,
+    json: body,
+  };
+}
+
+describe('refreshOpenAIModelCatalog', () => {
+  it('queries the OpenAI models endpoint and returns live catalog entries', async () => {
+    const requests: Array<{ url: string; init: IOpenAIModelCatalogFetchInit }> = [];
+    const catalog = await refreshOpenAIModelCatalog(
+      { type: 'openai', model: 'gpt-5.1', apiKey: 'sk-test' },
+      {
+        now: () => new Date('2026-05-05T00:00:00.000Z'),
+        fetcher: async (url, init) => {
+          requests.push({ url, init });
+          return createModelCatalogResponse(async () => ({
+            data: [{ id: 'gpt-5.1' }, { id: 'gpt-5.1-mini' }, { id: '' }],
+          }));
+        },
+      },
+    );
+
+    expect(requests).toEqual([
+      {
+        url: 'https://api.openai.com/v1/models',
+        init: { headers: { Authorization: 'Bearer sk-test' } },
+      },
+    ]);
+    expect(catalog).toMatchObject({
+      status: 'live',
+      lastVerifiedAt: '2026-05-05T00:00:00.000Z',
+      sourceUrl: 'https://platform.openai.com/docs/api-reference/models/list',
+    });
+    expect(catalog.entries?.map((entry) => entry.id)).toEqual(['gpt-5.1', 'gpt-5.1-mini']);
+  });
+
+  it('uses profile baseURL for OpenAI-compatible model discovery', async () => {
+    const requestedUrls: string[] = [];
+
+    await refreshOpenAIModelCatalog(
+      {
+        type: 'openai',
+        model: 'local-model',
+        apiKey: 'local-key',
+        baseURL: 'http://localhost:1234/v1/',
+      },
+      {
+        fetcher: async (url) => {
+          requestedUrls.push(url);
+          return createModelCatalogResponse(async () => ({ data: [] }));
+        },
+      },
+    );
+
+    expect(requestedUrls).toEqual(['http://localhost:1234/v1/models']);
+  });
+
+  it('returns unavailable catalog state when credentials are missing', async () => {
+    const catalog = await refreshOpenAIModelCatalog({ type: 'openai', model: 'gpt-5.1' });
+
+    expect(catalog.status).toBe('unavailable');
+    expect(catalog.message).toBe('OpenAI model catalog refresh requires apiKey.');
+  });
+
+  it('returns unavailable catalog state when the endpoint rejects discovery', async () => {
+    const catalog = await refreshOpenAIModelCatalog(
+      { type: 'openai', model: 'gpt-5.1', apiKey: 'sk-test' },
+      {
+        fetcher: async () => ({
+          ok: false,
+          status: 401,
+          statusText: 'Unauthorized',
+          json: async () => ({ data: [] }),
+        }),
+      },
+    );
+
+    expect(catalog.status).toBe('unavailable');
+    expect(catalog.message).toBe('OpenAI model catalog refresh failed: HTTP 401 Unauthorized');
+  });
+});

package/src/openai/model-catalog-refresh.ts

@@ -0,0 +1,115 @@
+import type {
+  IProviderModelCatalog,
+  IProviderModelCatalogEntry,
+  IProviderProfileConfig,
+} from '@robota-sdk/agent-core';
+
+const OPENAI_MODELS_ENDPOINT = 'https://api.openai.com/v1/models';
+const OPENAI_MODELS_SOURCE_URL = 'https://platform.openai.com/docs/api-reference/models/list';
+
+export interface IOpenAIModelCatalogResponse {
+  data?: readonly IOpenAIModelCatalogResource[];
+}
+
+export interface IOpenAIModelCatalogResource {
+  id?: string;
+}
+
+export interface IOpenAIModelCatalogFetchInit {
+  headers: Record<string, string>;
+}
+
+export interface IOpenAIModelCatalogFetchResponse {
+  ok: boolean;
+  status: number;
+  statusText?: string;
+  json: () => Promise<IOpenAIModelCatalogResponse>;
+}
+
+export type TOpenAIModelCatalogFetch = (
+  url: string,
+  init: IOpenAIModelCatalogFetchInit,
+) => Promise<IOpenAIModelCatalogFetchResponse>;
+
+export interface IRefreshOpenAIModelCatalogOptions {
+  fetcher?: TOpenAIModelCatalogFetch;
+  now?: () => Date;
+}
+
+export async function refreshOpenAIModelCatalog(
+  profile: IProviderProfileConfig,
+  options: IRefreshOpenAIModelCatalogOptions = {},
+): Promise<IProviderModelCatalog> {
+  if (!profile.apiKey) {
+    return createUnavailableCatalog('OpenAI model catalog refresh requires apiKey.');
+  }
+
+  const fetcher = options.fetcher ?? defaultOpenAIModelCatalogFetch;
+  const now = options.now ?? (() => new Date());
+  const url = resolveModelsEndpoint(profile.baseURL);
+
+  try {
+    const response = await fetcher(url, {
+      headers: { Authorization: `Bearer ${profile.apiKey}` },
+    });
+    if (!response.ok) {
+      return createUnavailableCatalog(formatHttpFailure(response));
+    }
+
+    const body = await response.json();
+    const entries = toModelCatalogEntries(body);
+    return {
+      status: 'live',
+      entries,
+      lastVerifiedAt: now().toISOString(),
+      sourceUrl: OPENAI_MODELS_SOURCE_URL,
+      message: `${entries.length} OpenAI model(s) discovered.`,
+    };
+  } catch (error) {
+    return createUnavailableCatalog(error instanceof Error ? error.message : String(error));
+  }
+}
+
+function resolveModelsEndpoint(baseURL: string | undefined): string {
+  if (!baseURL) return OPENAI_MODELS_ENDPOINT;
+  return `${baseURL.replace(/\/$/, '')}/models`;
+}
+
+function toModelCatalogEntries(
+  body: IOpenAIModelCatalogResponse,
+): readonly IProviderModelCatalogEntry[] {
+  return (body.data ?? [])
+    .map((model) => model.id)
+    .filter((id): id is string => id !== undefined && id.trim().length > 0)
+    .map((id) => ({
+      id,
+      displayName: id,
+      lifecycle: 'active',
+    }));
+}
+
+function formatHttpFailure(response: IOpenAIModelCatalogFetchResponse): string {
+  const statusText = response.statusText ? ` ${response.statusText}` : '';
+  return `OpenAI model catalog refresh failed: HTTP ${response.status}${statusText}`;
+}
+
+function createUnavailableCatalog(message: string): IProviderModelCatalog {
+  return {
+    status: 'unavailable',
+    sourceUrl: OPENAI_MODELS_SOURCE_URL,
+    message,
+  };
+}
+
+async function defaultOpenAIModelCatalogFetch(
+  url: string,
+  init: IOpenAIModelCatalogFetchInit,
+): Promise<IOpenAIModelCatalogFetchResponse> {
+  const response = await fetch(url, init);
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    json: () => response.json() as Promise<IOpenAIModelCatalogResponse>,
+  };
+}

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

@@ -0,0 +1,92 @@
+import type { IOpenAIProviderOptions, TOpenAIProviderOptionValue } from './types';
+import type {
+  IOpenAIResponsesTextConfig,
+  IOpenAIResponsesTextFormatJsonSchema,
+} from './responses-types';
+
+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;
+
+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();
+    });
+  });
+});