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

package/src/openai/responses-parser.ts

@@ -0,0 +1,297 @@
+import { randomUUID } from 'node:crypto';
+
+import { streamWithAbort } from './responses-stream-utils';
+
+import type {
+  IOpenAIResponsesErrorEvent,
+  IOpenAIResponsesFunctionCallOutputItem,
+  IOpenAIResponsesMessageOutputItem,
+  IOpenAIResponsesReasoningOutputItem,
+  IOpenAIResponsesResponse,
+  IOpenAIResponsesUsage,
+  TOpenAIResponsesOutputContent,
+  TOpenAIResponsesOutputItem,
+  TOpenAIResponsesStreamEvent,
+} from './responses-types';
+import type { IToolCall, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+
+interface IOpenAIResponsesStreamAssemblyOptions {
+  stream: AsyncIterable<TOpenAIResponsesStreamEvent>;
+  onTextDelta?: TTextDeltaCallback;
+  signal?: AbortSignal;
+}
+
+interface IOpenAIResponsesReasoningMetadata {
+  reasoningSummaryCount: number;
+  reasoningSummaries: string[];
+  hasEncryptedReasoning: boolean;
+}
+
+interface IOpenAIResponseUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+interface IOpenAIResponsesStreamState {
+  textParts: string[];
+  toolCalls: IToolCall[];
+  completedResponse?: IOpenAIResponsesResponse;
+  reasoning: IOpenAIResponsesReasoningMetadata;
+}
+
+export function parseOpenAIResponsesResponse(
+  response: IOpenAIResponsesResponse,
+): TUniversalMessage {
+  assertUsableResponse(response);
+  const output = response.output ?? [];
+  const content = response.output_text ?? extractMessageText(output);
+  return buildAssistantMessage({
+    content,
+    toolCalls: extractFunctionToolCalls(output),
+    response,
+    reasoning: collectReasoningMetadata(output),
+  });
+}
+
+export async function assembleOpenAIResponsesStream(
+  options: IOpenAIResponsesStreamAssemblyOptions,
+): Promise<TUniversalMessage> {
+  const state: IOpenAIResponsesStreamState = {
+    textParts: [],
+    toolCalls: [],
+    reasoning: createEmptyReasoningMetadata(),
+  };
+
+  for await (const event of streamWithAbort(options.stream, options.signal)) {
+    applyStreamEvent(state, event, options.onTextDelta);
+  }
+
+  if (state.completedResponse !== undefined) {
+    return buildMessageFromCompletedResponse(state);
+  }
+
+  return buildAssistantMessage({
+    content: state.textParts.join(''),
+    toolCalls: state.toolCalls,
+    reasoning: state.reasoning,
+  });
+}
+
+function applyStreamEvent(
+  state: IOpenAIResponsesStreamState,
+  event: TOpenAIResponsesStreamEvent,
+  onTextDelta: TTextDeltaCallback | undefined,
+): void {
+  if (event.type === 'response.output_text.delta') {
+    state.textParts.push(event.delta);
+    onTextDelta?.(event.delta);
+    return;
+  }
+
+  if (event.type === 'response.completed') {
+    state.completedResponse = event.response;
+    mergeReasoningMetadata(state.reasoning, collectReasoningMetadata(event.response.output ?? []));
+    return;
+  }
+
+  if (event.type === 'response.output_item.done') {
+    applyOutputItem(state, event.item);
+    return;
+  }
+
+  if (
+    event.type === 'response.error' ||
+    event.type === 'response.failed' ||
+    event.type === 'response.incomplete'
+  ) {
+    throw new Error(`OpenAI Responses API failed: ${extractErrorMessage(event)}`);
+  }
+}
+
+function applyOutputItem(
+  state: IOpenAIResponsesStreamState,
+  item: TOpenAIResponsesOutputItem,
+): void {
+  if (isFunctionCallOutputItem(item)) {
+    state.toolCalls.push(convertFunctionCall(item));
+    return;
+  }
+  if (isReasoningOutputItem(item)) {
+    mergeReasoningMetadata(state.reasoning, collectReasoningMetadata([item]));
+  }
+}
+
+function buildMessageFromCompletedResponse(state: IOpenAIResponsesStreamState): TUniversalMessage {
+  const response = state.completedResponse;
+  if (response === undefined) {
+    throw new Error('OpenAI Responses stream completed without response metadata');
+  }
+
+  assertUsableResponse(response);
+  const output = response.output ?? [];
+  const responseToolCalls = extractFunctionToolCalls(output);
+  const content =
+    state.textParts.length > 0
+      ? state.textParts.join('')
+      : (response.output_text ?? extractMessageText(output));
+  const reasoning = collectReasoningMetadata(output);
+  mergeReasoningMetadata(reasoning, state.reasoning);
+
+  return buildAssistantMessage({
+    content,
+    toolCalls: responseToolCalls.length > 0 ? responseToolCalls : state.toolCalls,
+    response,
+    reasoning,
+  });
+}
+
+function buildAssistantMessage(input: {
+  content: string;
+  toolCalls: IToolCall[];
+  response?: IOpenAIResponsesResponse;
+  reasoning: IOpenAIResponsesReasoningMetadata;
+}): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: input.content,
+    state: 'complete',
+    timestamp: new Date(),
+    ...(input.toolCalls.length > 0 && { toolCalls: input.toolCalls }),
+    ...(input.response?.usage !== undefined && { usage: mapUsage(input.response.usage) }),
+    metadata: {
+      ...buildMetadata(input.response, input.reasoning),
+      ...(input.response?.usage !== undefined && {
+        usageProvenance:
+          input.response.usage.input_tokens !== undefined &&
+          input.response.usage.output_tokens !== undefined &&
+          input.response.usage.total_tokens !== undefined
+            ? 'complete'
+            : 'partial',
+      }),
+    },
+  };
+}
+
+function buildMetadata(
+  response: IOpenAIResponsesResponse | undefined,
+  reasoning: IOpenAIResponsesReasoningMetadata,
+): NonNullable<TUniversalMessage['metadata']> {
+  return {
+    providerApiSurface: 'responses',
+    ...(response?.id !== undefined && { responseId: response.id }),
+    ...(response?.model !== undefined && { model: response.model }),
+    ...(response?.status !== undefined && { finishReason: response.status }),
+    ...(reasoning.reasoningSummaryCount > 0 && {
+      reasoningSummaryCount: reasoning.reasoningSummaryCount,
+      reasoningSummaries: reasoning.reasoningSummaries,
+    }),
+    ...(reasoning.hasEncryptedReasoning && { hasEncryptedReasoning: true }),
+  };
+}
+
+function mapUsage(usage: IOpenAIResponsesUsage): IOpenAIResponseUsage {
+  return {
+    promptTokens: usage.input_tokens ?? 0,
+    completionTokens: usage.output_tokens ?? 0,
+    totalTokens: usage.total_tokens ?? 0,
+  };
+}
+
+function extractFunctionToolCalls(output: readonly TOpenAIResponsesOutputItem[]): IToolCall[] {
+  return output.filter(isFunctionCallOutputItem).map((item) => convertFunctionCall(item));
+}
+
+function isFunctionCallOutputItem(
+  item: TOpenAIResponsesOutputItem,
+): item is IOpenAIResponsesFunctionCallOutputItem {
+  return (
+    item.type === 'function_call' && 'call_id' in item && 'name' in item && 'arguments' in item
+  );
+}
+
+function convertFunctionCall(item: IOpenAIResponsesFunctionCallOutputItem): IToolCall {
+  return {
+    id: item.call_id,
+    type: 'function',
+    function: {
+      name: item.name,
+      arguments: item.arguments,
+    },
+  };
+}
+
+function extractMessageText(output: readonly TOpenAIResponsesOutputItem[]): string {
+  return output
+    .filter(isMessageOutputItem)
+    .flatMap((item) => item.content)
+    .map(extractTextContent)
+    .join('');
+}
+
+function extractTextContent(content: TOpenAIResponsesOutputContent): string {
+  if (content.type === 'refusal') {
+    return content.refusal;
+  }
+  return content.text;
+}
+
+function isMessageOutputItem(
+  item: TOpenAIResponsesOutputItem,
+): item is IOpenAIResponsesMessageOutputItem {
+  return item.type === 'message' && 'content' in item && Array.isArray(item.content);
+}
+
+function collectReasoningMetadata(
+  output: readonly TOpenAIResponsesOutputItem[],
+): IOpenAIResponsesReasoningMetadata {
+  const metadata = createEmptyReasoningMetadata();
+  for (const item of output) {
+    if (!isReasoningOutputItem(item)) {
+      continue;
+    }
+    const summaries = item.summary?.map((summary) => summary.text).filter(isString) ?? [];
+    metadata.reasoningSummaryCount += summaries.length;
+    metadata.reasoningSummaries.push(...summaries);
+    metadata.hasEncryptedReasoning = metadata.hasEncryptedReasoning || !!item.encrypted_content;
+  }
+  return metadata;
+}
+
+function isReasoningOutputItem(
+  item: TOpenAIResponsesOutputItem,
+): item is IOpenAIResponsesReasoningOutputItem {
+  return item.type === 'reasoning';
+}
+
+function createEmptyReasoningMetadata(): IOpenAIResponsesReasoningMetadata {
+  return {
+    reasoningSummaryCount: 0,
+    reasoningSummaries: [],
+    hasEncryptedReasoning: false,
+  };
+}
+
+function mergeReasoningMetadata(
+  target: IOpenAIResponsesReasoningMetadata,
+  source: IOpenAIResponsesReasoningMetadata,
+): void {
+  target.reasoningSummaryCount += source.reasoningSummaryCount;
+  target.reasoningSummaries.push(...source.reasoningSummaries);
+  target.hasEncryptedReasoning = target.hasEncryptedReasoning || source.hasEncryptedReasoning;
+}
+
+function isString(value: string | undefined): value is string {
+  return value !== undefined;
+}
+
+function assertUsableResponse(response: IOpenAIResponsesResponse): void {
+  if (response.status === 'failed' || response.status === 'incomplete') {
+    throw new Error(`OpenAI Responses API failed: ${response.error?.message ?? response.status}`);
+  }
+}
+
+function extractErrorMessage(event: IOpenAIResponsesErrorEvent): string {
+  return event.message ?? event.error?.message ?? event.response?.error?.message ?? 'unknown error';
+}

package/src/openai/responses-stream-utils.ts

@@ -0,0 +1,45 @@
+export async function* streamWithAbort<T>(
+  source: AsyncIterable<T>,
+  signal?: AbortSignal,
+): AsyncGenerator<T> {
+  const iterator = source[Symbol.asyncIterator]();
+  try {
+    while (!signal?.aborted) {
+      const item = await nextStreamItem(iterator, signal);
+      if (item.done || signal?.aborted) {
+        break;
+      }
+      yield item.value;
+    }
+  } finally {
+    if (signal?.aborted) {
+      await iterator.return?.();
+    }
+  }
+}
+
+async function nextStreamItem<T>(
+  iterator: AsyncIterator<T>,
+  signal?: AbortSignal,
+): Promise<IteratorResult<T>> {
+  if (!signal) {
+    return iterator.next();
+  }
+  if (signal.aborted) {
+    return { done: true, value: undefined as T };
+  }
+
+  let abortListener: (() => void) | undefined;
+  const aborted = new Promise<IteratorResult<T>>((resolve) => {
+    abortListener = (): void => resolve({ done: true, value: undefined as T });
+    signal.addEventListener('abort', abortListener, { once: true });
+  });
+
+  try {
+    return await Promise.race([iterator.next(), aborted]);
+  } finally {
+    if (abortListener) {
+      signal.removeEventListener('abort', abortListener);
+    }
+  }
+}

package/src/openai/responses-types.ts

@@ -0,0 +1,193 @@
+import type {
+  IOpenAIJsonSchemaDefinition,
+  IOpenAIResponsesReasoningOptions,
+  TOpenAIProviderOptionValue,
+} from './types';
+import type { IToolSchema } from '@robota-sdk/agent-core';
+
+export type TOpenAIResponsesInputRole = 'user' | 'assistant' | 'system' | 'developer';
+
+export interface IOpenAIResponsesInputTextContent {
+  type: 'input_text';
+  text: string;
+}
+
+export interface IOpenAIResponsesInputImageContent {
+  type: 'input_image';
+  image_url: string;
+  detail?: 'auto' | 'low' | 'high';
+}
+
+export type TOpenAIResponsesInputContent =
+  IOpenAIResponsesInputTextContent | IOpenAIResponsesInputImageContent;
+
+export interface IOpenAIResponsesMessageInput {
+  type?: 'message';
+  role: TOpenAIResponsesInputRole;
+  content: string | TOpenAIResponsesInputContent[];
+}
+
+export interface IOpenAIResponsesFunctionCallInput {
+  type: 'function_call';
+  call_id: string;
+  name: string;
+  arguments: string;
+}
+
+export interface IOpenAIResponsesFunctionCallOutputInput {
+  type: 'function_call_output';
+  call_id: string;
+  output: string;
+}
+
+export type TOpenAIResponsesInputItem =
+  | IOpenAIResponsesMessageInput
+  | IOpenAIResponsesFunctionCallInput
+  | IOpenAIResponsesFunctionCallOutputInput;
+
+export interface IOpenAIResponsesFunctionTool {
+  type: 'function';
+  name: string;
+  parameters: IToolSchema['parameters'];
+  strict: boolean | null;
+  description?: string;
+}
+
+export type TOpenAIResponsesTool = IOpenAIResponsesFunctionTool;
+
+export interface IOpenAIResponsesTextFormatText {
+  type: 'text';
+}
+
+export interface IOpenAIResponsesTextFormatJsonObject {
+  type: 'json_object';
+}
+
+export interface IOpenAIResponsesTextFormatJsonSchema extends IOpenAIJsonSchemaDefinition {
+  type: 'json_schema';
+  schema: Record<string, TOpenAIProviderOptionValue>;
+}
+
+export type TOpenAIResponsesTextFormat =
+  | IOpenAIResponsesTextFormatText
+  | IOpenAIResponsesTextFormatJsonObject
+  | IOpenAIResponsesTextFormatJsonSchema;
+
+export interface IOpenAIResponsesTextConfig {
+  format: TOpenAIResponsesTextFormat;
+}
+
+export interface IOpenAIResponsesRequestBase {
+  model: string;
+  input: TOpenAIResponsesInputItem[];
+  tools?: TOpenAIResponsesTool[];
+  tool_choice?: 'auto' | 'none' | 'required' | { type: 'function'; name: string };
+  text?: IOpenAIResponsesTextConfig;
+  temperature?: number;
+  max_output_tokens?: number;
+  reasoning?: IOpenAIResponsesReasoningOptions;
+  include?: 'reasoning.encrypted_content'[];
+  store?: boolean;
+}
+
+export interface IOpenAIResponsesRequestNonStreaming extends IOpenAIResponsesRequestBase {
+  stream?: false;
+}
+
+export interface IOpenAIResponsesRequestStreaming extends IOpenAIResponsesRequestBase {
+  stream: true;
+}
+
+export interface IOpenAIResponsesTextOutputContent {
+  type: 'output_text' | 'text';
+  text: string;
+}
+
+export interface IOpenAIResponsesRefusalOutputContent {
+  type: 'refusal';
+  refusal: string;
+}
+
+export type TOpenAIResponsesOutputContent =
+  IOpenAIResponsesTextOutputContent | IOpenAIResponsesRefusalOutputContent;
+
+export interface IOpenAIResponsesMessageOutputItem {
+  type: 'message';
+  role?: 'assistant';
+  content: TOpenAIResponsesOutputContent[];
+}
+
+export interface IOpenAIResponsesFunctionCallOutputItem {
+  type: 'function_call';
+  call_id: string;
+  name: string;
+  arguments: string;
+  id?: string;
+  status?: string;
+}
+
+export interface IOpenAIResponsesReasoningOutputItem {
+  type: 'reasoning';
+  summary?: Array<{ text?: string }>;
+  encrypted_content?: string;
+}
+
+export interface IOpenAIResponsesGenericOutputItem {
+  type: string;
+  id?: string;
+  status?: string;
+}
+
+export type TOpenAIResponsesOutputItem =
+  | IOpenAIResponsesMessageOutputItem
+  | IOpenAIResponsesFunctionCallOutputItem
+  | IOpenAIResponsesReasoningOutputItem
+  | IOpenAIResponsesGenericOutputItem;
+
+export interface IOpenAIResponsesUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+}
+
+export interface IOpenAIResponsesErrorBody {
+  message?: string;
+}
+
+export interface IOpenAIResponsesResponse {
+  id?: string;
+  model?: string;
+  output_text?: string;
+  output?: TOpenAIResponsesOutputItem[];
+  usage?: IOpenAIResponsesUsage;
+  status?: string;
+  error?: IOpenAIResponsesErrorBody | null;
+}
+
+export interface IOpenAIResponsesTextDeltaEvent {
+  type: 'response.output_text.delta';
+  delta: string;
+}
+
+export interface IOpenAIResponsesCompletedEvent {
+  type: 'response.completed';
+  response: IOpenAIResponsesResponse;
+}
+
+export interface IOpenAIResponsesOutputItemDoneEvent {
+  type: 'response.output_item.done';
+  item: TOpenAIResponsesOutputItem;
+}
+
+export interface IOpenAIResponsesErrorEvent {
+  type: 'response.error' | 'response.failed' | 'response.incomplete';
+  message?: string;
+  error?: IOpenAIResponsesErrorBody;
+  response?: IOpenAIResponsesResponse;
+}
+
+export type TOpenAIResponsesStreamEvent =
+  | IOpenAIResponsesTextDeltaEvent
+  | IOpenAIResponsesCompletedEvent
+  | IOpenAIResponsesOutputItemDoneEvent
+  | IOpenAIResponsesErrorEvent;

package/src/openai/streaming/stream-assembler.ts

@@ -0,0 +1,3 @@
+import { assembleOpenAICompatibleStream } from '@robota-sdk/agent-provider-openai-compatible/shared';
+
+export { assembleOpenAICompatibleStream as assembleOpenAIStream };

package/src/openai/types/api-types.ts

@@ -0,0 +1,113 @@
+import type OpenAI from 'openai';
+
+/**
+ * OpenAI API Request Parameters
+ * Replaces any types with specific OpenAI API structure
+ */
+export interface IOpenAIChatRequestParams {
+  model: string;
+  messages: OpenAI.Chat.ChatCompletionMessageParam[];
+  temperature?: number | undefined;
+  max_tokens?: number | undefined;
+  tools?: OpenAI.Chat.ChatCompletionTool[] | undefined;
+  tool_choice?: 'auto' | 'none' | OpenAI.Chat.ChatCompletionNamedToolChoice | undefined;
+  stream?: boolean | undefined;
+}
+
+/**
+ * OpenAI API streaming request parameters
+ */
+export interface IOpenAIStreamRequestParams extends Omit<IOpenAIChatRequestParams, 'stream'> {
+  stream: true;
+}
+
+/**
+ * OpenAI API tool call structure
+ */
+export interface IOpenAIToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+/**
+ * OpenAI API message structure with tool calls
+ */
+export interface IOpenAIAssistantMessage {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: IOpenAIToolCall[];
+}
+
+/**
+ * OpenAI API tool message structure
+ */
+export interface IOpenAIToolMessage {
+  role: 'tool';
+  content: string;
+  tool_call_id: string;
+}
+
+/**
+ * OpenAI streaming chunk delta structure
+ */
+export interface IOpenAIStreamDelta {
+  role?: 'assistant';
+  content?: string | null;
+  tool_calls?: Array<{
+    index: number;
+    id?: string;
+    type?: 'function';
+    function?: {
+      name?: string;
+      arguments?: string;
+    };
+  }>;
+}
+
+/**
+ * OpenAI streaming chunk structure
+ */
+export interface IOpenAIStreamChunk {
+  id: string;
+  object: 'chat.completion.chunk';
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: IOpenAIStreamDelta;
+    finish_reason?: string | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * OpenAI error structure for type-safe error handling
+ */
+export interface IOpenAIError {
+  message: string;
+  status?: number;
+  type?: string;
+  param?: string | null;
+  code?: string | null;
+}
+
+/**
+ * Payload logging data structure
+ */
+export interface IOpenAILogData {
+  model: string;
+  messagesCount: number;
+  hasTools: boolean;
+  temperature?: number | undefined;
+  maxTokens?: number | undefined;
+  timestamp: string;
+  requestId?: string | undefined;
+}