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

package/src/shared/openai-compatible/message-converter.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import type { IToolSchema, TUniversalMessage } from '@robota-sdk/agent-core';
+import { convertToOpenAICompatibleMessages, convertToOpenAICompatibleTools } from './index';
+
+const timestamp = new Date('2026-05-01T00:00:00.000Z');
+
+describe('OpenAI-compatible message converter', () => {
+  it('converts universal chat messages to Chat Completions messages', () => {
+    const messages: TUniversalMessage[] = [
+      {
+        id: 'system-1',
+        role: 'system',
+        content: 'You are concise.',
+        state: 'complete',
+        timestamp,
+      },
+      {
+        id: 'user-1',
+        role: 'user',
+        content: 'Search docs',
+        state: 'complete',
+        timestamp,
+      },
+      {
+        id: 'assistant-1',
+        role: 'assistant',
+        content: '',
+        state: 'complete',
+        timestamp,
+        toolCalls: [
+          {
+            id: 'call-1',
+            type: 'function',
+            function: { name: 'search', arguments: '{"q":"docs"}' },
+          },
+        ],
+      },
+      {
+        id: 'tool-1',
+        role: 'tool',
+        content: 'result',
+        state: 'complete',
+        timestamp,
+        toolCallId: 'call-1',
+      },
+    ];
+
+    expect(convertToOpenAICompatibleMessages(messages)).toEqual([
+      { role: 'system', content: 'You are concise.' },
+      { role: 'user', content: 'Search docs' },
+      {
+        role: 'assistant',
+        content: null,
+        tool_calls: [
+          {
+            id: 'call-1',
+            type: 'function',
+            function: { name: 'search', arguments: '{"q":"docs"}' },
+          },
+        ],
+      },
+      { role: 'tool', content: 'result', tool_call_id: 'call-1' },
+    ]);
+  });
+
+  it('rejects tool messages without a toolCallId', () => {
+    const messages: TUniversalMessage[] = [
+      {
+        id: 'tool-1',
+        role: 'tool',
+        content: 'result',
+        state: 'complete',
+        timestamp,
+        toolCallId: '',
+      },
+    ];
+
+    expect(() => convertToOpenAICompatibleMessages(messages)).toThrow(
+      'Tool message missing toolCallId',
+    );
+  });
+
+  it('converts universal tool schemas to OpenAI-compatible function tools', () => {
+    const tools: IToolSchema[] = [
+      {
+        name: 'read_file',
+        description: 'Read a file',
+        parameters: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+        },
+      },
+    ];
+
+    expect(convertToOpenAICompatibleTools(tools)).toEqual([
+      {
+        type: 'function',
+        function: {
+          name: 'read_file',
+          description: 'Read a file',
+          parameters: {
+            type: 'object',
+            properties: { path: { type: 'string' } },
+            required: ['path'],
+          },
+        },
+      },
+    ]);
+  });
+});

package/src/shared/openai-compatible/message-converter.ts

@@ -0,0 +1,84 @@
+import type OpenAI from 'openai';
+import type {
+  IAssistantMessage,
+  IToolCall,
+  IToolSchema,
+  TUniversalMessage,
+} from '@robota-sdk/agent-core';
+
+export function convertToOpenAICompatibleMessages(
+  messages: TUniversalMessage[],
+): OpenAI.Chat.ChatCompletionMessageParam[] {
+  return messages.map((message) => convertMessage(message));
+}
+
+export function convertToOpenAICompatibleTools(
+  tools: IToolSchema[],
+): OpenAI.Chat.ChatCompletionTool[] {
+  return tools.map((tool) => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  }));
+}
+
+function convertMessage(message: TUniversalMessage): OpenAI.Chat.ChatCompletionMessageParam {
+  if (message.role === 'user') {
+    return {
+      role: 'user',
+      content: message.content || '',
+    };
+  }
+
+  if (message.role === 'assistant') {
+    return convertAssistantMessage(message);
+  }
+
+  if (message.role === 'system') {
+    return {
+      role: 'system',
+      content: 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 {
+      role: 'tool',
+      content: message.content || '',
+      tool_call_id: message.toolCallId,
+    };
+  }
+
+  const exhaustive: never = message;
+  throw new Error(`Unsupported message role: ${JSON.stringify(exhaustive)}`);
+}
+
+function convertAssistantMessage(
+  message: IAssistantMessage,
+): OpenAI.Chat.ChatCompletionAssistantMessageParam {
+  if (message.toolCalls && message.toolCalls.length > 0) {
+    return {
+      role: 'assistant',
+      content: message.content === '' ? null : message.content || null,
+      tool_calls: message.toolCalls.map((toolCall: IToolCall) => ({
+        id: toolCall.id,
+        type: 'function',
+        function: {
+          name: toolCall.function.name,
+          arguments: toolCall.function.arguments,
+        },
+      })),
+    };
+  }
+
+  return {
+    role: 'assistant',
+    content: message.content === null ? null : message.content || '',
+  };
+}

package/src/shared/openai-compatible/native-payload-observer.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { observeProviderNativeRawPayloadStream } from './native-payload-observer';
+import type { IProviderNativeRawPayloadEvent } from '@robota-sdk/agent-core';
+
+async function* asyncIterableFrom<T extends object>(items: T[]): AsyncIterable<T> {
+  for (const item of items) {
+    yield item;
+  }
+}
+
+describe('observeProviderNativeRawPayloadStream', () => {
+  it('emits ordered stream_event payloads and yields original chunks unchanged', async () => {
+    const chunks = [{ id: 'chunk-1' }, { id: 'chunk-2' }];
+    const events: IProviderNativeRawPayloadEvent[] = [];
+    const yielded: object[] = [];
+
+    for await (const chunk of observeProviderNativeRawPayloadStream(asyncIterableFrom(chunks), {
+      provider: 'provider',
+      apiSurface: 'chat-completions',
+      onProviderNativeRawPayload: (event) => events.push(event),
+    })) {
+      yielded.push(chunk);
+    }
+
+    expect(yielded).toEqual(chunks);
+    expect(events).toEqual([
+      expect.objectContaining({
+        provider: 'provider',
+        apiSurface: 'chat-completions',
+        payloadKind: 'stream_event',
+        sequence: 0,
+        payload: chunks[0],
+      }),
+      expect.objectContaining({
+        provider: 'provider',
+        apiSurface: 'chat-completions',
+        payloadKind: 'stream_event',
+        sequence: 1,
+        payload: chunks[1],
+      }),
+    ]);
+  });
+});

package/src/shared/openai-compatible/native-payload-observer.ts

@@ -0,0 +1,26 @@
+import type { TProviderNativeRawPayloadCallback } from '@robota-sdk/agent-core';
+
+export interface IObserveProviderNativeRawPayloadStreamOptions {
+  provider: string;
+  apiSurface?: string;
+  onProviderNativeRawPayload?: TProviderNativeRawPayloadCallback;
+  initialSequence?: number;
+}
+
+export async function* observeProviderNativeRawPayloadStream<TPayload extends object>(
+  stream: AsyncIterable<TPayload>,
+  options: IObserveProviderNativeRawPayloadStreamOptions,
+): AsyncIterable<TPayload> {
+  let sequence = options.initialSequence ?? 0;
+  for await (const payload of stream) {
+    options.onProviderNativeRawPayload?.({
+      provider: options.provider,
+      ...(options.apiSurface !== undefined && { apiSurface: options.apiSurface }),
+      payloadKind: 'stream_event',
+      sequence,
+      payload,
+    });
+    sequence++;
+    yield payload;
+  }
+}

package/src/shared/openai-compatible/response-parser.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest';
+import type OpenAI from 'openai';
+import { OpenAICompatibleResponseParser } from './index';
+
+describe('OpenAICompatibleResponseParser', () => {
+  it('parses full chat completion responses into universal assistant messages', () => {
+    const parser = new OpenAICompatibleResponseParser();
+    const response: OpenAI.Chat.ChatCompletion = {
+      id: 'chatcmpl-test',
+      object: 'chat.completion',
+      created: 1,
+      model: 'local-model',
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: 'Visible answer',
+            refusal: null,
+          },
+          finish_reason: 'stop',
+          logprobs: null,
+        },
+      ],
+      usage: {
+        prompt_tokens: 3,
+        completion_tokens: 4,
+        total_tokens: 7,
+      },
+    };
+
+    const result = parser.parseResponse(response);
+
+    expect(result.role).toBe('assistant');
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.content).toBe('Visible answer');
+    expect(result).toHaveProperty('usage');
+    const withUsage = result as unknown as {
+      usage: { promptTokens: number; completionTokens: number; totalTokens: number };
+    };
+    expect(withUsage.usage).toEqual({
+      promptTokens: 3,
+      completionTokens: 4,
+      totalTokens: 7,
+    });
+    expect(result.metadata?.['finishReason']).toBe('stop');
+  });
+
+  it('applies an injected provider-owned text tool-call projector to full responses', () => {
+    const parser = new OpenAICompatibleResponseParser({
+      toolCallTextProjector: {
+        project: (text: string) => ({
+          visibleText: text === 'provider native payload' ? '' : text,
+          toolCalls:
+            text === 'provider native payload'
+              ? [
+                  {
+                    id: 'projected-call-1',
+                    type: 'function' as const,
+                    function: { name: 'InjectedTool', arguments: '{"value":"ok"}' },
+                  },
+                ]
+              : [],
+          removedToolCallText: text === 'provider native payload',
+          ...(text === 'provider native payload' && { rawToolCallText: text }),
+        }),
+        flush: () => ({
+          visibleText: '',
+          toolCalls: [],
+          removedToolCallText: false,
+        }),
+      },
+    });
+    const response: OpenAI.Chat.ChatCompletion = {
+      id: 'chatcmpl-test',
+      object: 'chat.completion',
+      created: 1,
+      model: 'local-model',
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: 'provider native payload',
+            refusal: null,
+          },
+          finish_reason: 'tool_calls',
+          logprobs: null,
+        },
+      ],
+    };
+
+    const result = parser.parseResponse(response);
+
+    expect(result.content).toBe('');
+    expect(result.metadata?.['toolCallTextProjected']).toBe(true);
+    expect(result.metadata?.['rawToolCallText']).toBe('provider native payload');
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'projected-call-1',
+        type: 'function',
+        function: { name: 'InjectedTool', arguments: '{"value":"ok"}' },
+      },
+    ]);
+  });
+
+  it('passes native tool calls through so core can return a normal tool-result error', () => {
+    const parser = new OpenAICompatibleResponseParser();
+    const response: OpenAI.Chat.ChatCompletion = {
+      id: 'chatcmpl-test',
+      object: 'chat.completion',
+      created: 1,
+      model: 'local-model',
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: null,
+            refusal: null,
+            tool_calls: [
+              {
+                id: 'call-1',
+                type: 'function',
+                function: { name: 'UndeclaredTool', arguments: '{}' },
+              },
+            ],
+          },
+          finish_reason: 'tool_calls',
+          logprobs: null,
+        },
+      ],
+    };
+
+    const result = parser.parseResponse(response);
+
+    if (result.role !== 'assistant') throw new Error('Expected assistant message');
+    expect(result.toolCalls).toEqual([
+      {
+        id: 'call-1',
+        type: 'function',
+        function: { name: 'UndeclaredTool', arguments: '{}' },
+      },
+    ]);
+  });
+
+  it('applies text projection while parsing streaming chunks', () => {
+    const parser = new OpenAICompatibleResponseParser({
+      textProjector: (text) => text.replace('[hidden]', ''),
+    });
+    const chunk: OpenAI.Chat.ChatCompletionChunk = {
+      id: 'chunk-1',
+      object: 'chat.completion.chunk',
+      created: 1,
+      model: 'local-model',
+      choices: [
+        {
+          index: 0,
+          delta: { content: '[hidden]Visible' },
+          finish_reason: null,
+          logprobs: null,
+        },
+      ],
+    };
+
+    const result = parser.parseStreamingChunk(chunk);
+
+    expect(result?.content).toBe('Visible');
+    expect(result?.metadata?.['isStreamChunk']).toBe(true);
+  });
+});

package/src/shared/openai-compatible/response-parser.ts

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+import type OpenAI from 'openai';
+import type { ILogger, IToolCall, TUniversalMessage } from '@robota-sdk/agent-core';
+import { SilentLogger } from '@robota-sdk/agent-core';
+import type {
+  IOpenAICompatibleToolCallTextProjector,
+  IOpenAICompatibleToolCallTextProjection,
+  TOpenAICompatibleTextProjector,
+} from './types';
+
+export interface IOpenAICompatibleResponseParserOptions {
+  logger?: ILogger;
+  textProjector?: TOpenAICompatibleTextProjector;
+  toolCallTextProjector?: IOpenAICompatibleToolCallTextProjector;
+}
+
+export class OpenAICompatibleResponseParser {
+  private readonly logger: ILogger;
+  private readonly textProjector?: TOpenAICompatibleTextProjector;
+  private readonly toolCallTextProjector?: IOpenAICompatibleToolCallTextProjector;
+
+  constructor(options: IOpenAICompatibleResponseParserOptions = {}) {
+    this.logger = options.logger ?? SilentLogger;
+    this.textProjector = options.textProjector;
+    this.toolCallTextProjector = options.toolCallTextProjector;
+  }
+
+  parseResponse(response: OpenAI.Chat.ChatCompletion): TUniversalMessage {
+    try {
+      const choice = response.choices?.[0];
+      if (!choice) {
+        throw new Error('No choices found in OpenAI-compatible response');
+      }
+
+      return this.parseChoice(choice, response.usage);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'OpenAI-compatible response parsing failed';
+      this.logger.error('Response parsing failed', { error: message });
+      throw new Error(`OpenAI-compatible response parsing failed: ${message}`);
+    }
+  }
+
+  private parseChoice(
+    choice: OpenAI.Chat.ChatCompletion.Choice,
+    usage: OpenAI.CompletionUsage | undefined,
+  ): TUniversalMessage {
+    const message = choice.message;
+    const toolTextProjection = this.projectToolCallText(message.content || '');
+    const toolTextFlush = this.toolCallTextProjector?.flush();
+    const nativeToolCalls = this.parseNativeToolCalls(message);
+    const projectedToolCalls = [
+      ...toolTextProjection.toolCalls,
+      ...(toolTextFlush?.toolCalls ?? []),
+    ];
+    const toolCalls = [...nativeToolCalls, ...projectedToolCalls];
+
+    return {
+      id: randomUUID(),
+      state: 'complete',
+      role: 'assistant',
+      content: this.projectText(
+        toolTextProjection.visibleText + (toolTextFlush?.visibleText ?? ''),
+      ),
+      timestamp: new Date(),
+      ...(toolCalls.length > 0 && { toolCalls }),
+      ...(usage && { usage: this.parseUsage(usage) }),
+      metadata: {
+        finishReason: choice.finish_reason || undefined,
+        ...this.buildToolTextMetadata(toolTextProjection, toolTextFlush),
+      },
+    };
+  }
+
+  private parseNativeToolCalls(message: OpenAI.Chat.ChatCompletionMessage): IToolCall[] {
+    return (
+      message.tool_calls?.map((toolCall) => ({
+        id: toolCall.id,
+        type: 'function' as const,
+        function: {
+          name: toolCall.function.name,
+          arguments: toolCall.function.arguments,
+        },
+      })) || []
+    );
+  }
+
+  private parseUsage(usage: OpenAI.CompletionUsage): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  } {
+    return {
+      promptTokens: usage.prompt_tokens,
+      completionTokens: usage.completion_tokens,
+      totalTokens: usage.total_tokens,
+    };
+  }
+
+  parseStreamingChunk(chunk: OpenAI.Chat.ChatCompletionChunk): TUniversalMessage | null {
+    try {
+      const choice = chunk.choices?.[0];
+      if (!choice) {
+        return null;
+      }
+
+      const finishReason = choice.finish_reason;
+      const toolCalls = choice.delta.tool_calls?.map((toolCall) => ({
+        id: toolCall.id || '',
+        type: 'function' as const,
+        function: {
+          name: toolCall.function?.name || '',
+          arguments: toolCall.function?.arguments || '',
+        },
+      }));
+
+      if (toolCalls) {
+        return {
+          id: randomUUID(),
+          state: 'complete',
+          role: 'assistant',
+          content: '',
+          timestamp: new Date(),
+          toolCalls,
+          metadata: {
+            isStreamChunk: true,
+            isComplete: finishReason === 'stop' || finishReason === 'tool_calls',
+          },
+        };
+      }
+
+      return {
+        id: randomUUID(),
+        state: 'complete',
+        role: 'assistant',
+        content: this.projectText(choice.delta.content || ''),
+        timestamp: new Date(),
+        metadata: {
+          isStreamChunk: true,
+          isComplete: finishReason === 'stop' || finishReason === 'tool_calls',
+        },
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'OpenAI-compatible chunk parsing failed';
+      this.logger.error('Chunk parsing failed', { error: message });
+      throw new Error(`OpenAI-compatible chunk parsing failed: ${message}`);
+    }
+  }
+
+  private projectText(text: string): string {
+    return this.textProjector ? this.textProjector(text) : text;
+  }
+
+  private projectToolCallText(text: string): IOpenAICompatibleToolCallTextProjection {
+    return (
+      this.toolCallTextProjector?.project(text) ?? {
+        visibleText: text,
+        toolCalls: [],
+        removedToolCallText: false,
+      }
+    );
+  }
+
+  private buildToolTextMetadata(
+    projection: IOpenAICompatibleToolCallTextProjection,
+    flush: IOpenAICompatibleToolCallTextProjection | undefined,
+  ): Record<string, string | boolean | undefined> {
+    const rawToolCallText = [projection.rawToolCallText, flush?.rawToolCallText]
+      .filter((text): text is string => typeof text === 'string' && text.length > 0)
+      .join('');
+    const removedToolCallText =
+      projection.removedToolCallText || (flush?.removedToolCallText ?? false);
+
+    return {
+      ...(removedToolCallText && { toolCallTextProjected: true }),
+      ...(rawToolCallText.length > 0 && { rawToolCallText }),
+    };
+  }
+}