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

package/src/openai/reasoning-effort.ts

@@ -0,0 +1,49 @@
+import type { IOpenAIResponsesReasoningOptions } from './types';
+import type { IModelEffortResolution, TModelEffort } from '@robota-sdk/agent-core';
+
+/**
+ * Map the framework's per-call reasoning-effort dial onto the OpenAI Responses API
+ * `reasoning.effort` parameter.
+ *
+ * Per-model support and downward clamping are resolved by the Core table before this boundary.
+ * This function only serializes the verified concrete value, without reinterpreting it.
+ */
+export function mapEffortToOpenAIReasoningEffort(
+  effort: TModelEffort,
+): IOpenAIResponsesReasoningOptions['effort'] {
+  return effort;
+}
+
+/**
+ * Merge the per-call effort dial into the provider's static reasoning options.
+ *
+ * A verified concrete resolution takes precedence over static native control; a conflicting static
+ * control is rejected rather than silently overwritten. `auto` and `not-applied` resolutions leave
+ * the provider default untouched and never manufacture a native effort field.
+ */
+export function resolveOpenAIReasoningOptions(
+  staticReasoning: IOpenAIResponsesReasoningOptions | undefined,
+  resolution: IModelEffortResolution | undefined,
+): IOpenAIResponsesReasoningOptions | undefined {
+  if (resolution === undefined) {
+    return staticReasoning;
+  }
+  if (resolution.effective === null || resolution.disposition === 'model-default') {
+    if (staticReasoning?.effort !== undefined) {
+      throw new Error(
+        `Static reasoning.effort ${staticReasoning.effort} conflicts with ${resolution.disposition === 'model-default' ? 'provider-default selection' : 'an effort resolution that does not apply a native control'}.`,
+      );
+    }
+    return staticReasoning;
+  }
+  const effort = mapEffortToOpenAIReasoningEffort(resolution.effective);
+  if (staticReasoning?.effort !== undefined && staticReasoning.effort !== effort) {
+    throw new Error(
+      `Resolved effort ${effort} conflicts with static reasoning.effort ${staticReasoning.effort}.`,
+    );
+  }
+  return {
+    ...staticReasoning,
+    effort,
+  };
+}

package/src/openai/request-id.ts

@@ -0,0 +1,39 @@
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+/** The subset of the OpenAI SDK's `APIPromise` this module depends on. */
+interface IWithResponseCapable<T> {
+  withResponse?: () => Promise<{ data: T; request_id?: string | null }>;
+}
+
+/**
+ * Await an OpenAI `create()` call, reading the server's own request ID off `.withResponse()` when
+ * the client exposes it. A test double or older client that resolves to a plain value has no
+ * `withResponse`, so this falls back to the awaited value with no ID — never a fabricated one.
+ */
+export async function awaitWithProviderRequestId<T>(
+  call: PromiseLike<T> & IWithResponseCapable<T>,
+): Promise<{ data: T; providerRequestId?: string }> {
+  if (typeof call.withResponse === 'function') {
+    const { data, request_id } = await call.withResponse();
+    return {
+      data,
+      ...(typeof request_id === 'string' && request_id.length > 0 && { providerRequestId: request_id }),
+    };
+  }
+  return { data: await call };
+}
+
+/** The non-stream response shape the SDK attaches its own request ID to directly. */
+export function readOpenAIRequestId(response: unknown): string | undefined {
+  const id = (response as { _request_id?: string | null } | null | undefined)?._request_id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
+/** Merge a provider-returned request ID into a message's metadata; a no-op when there isn't one. */
+export function withProviderRequestId<T extends TUniversalMessage>(
+  message: T,
+  providerRequestId: string | undefined,
+): T {
+  if (providerRequestId === undefined) return message;
+  return { ...message, metadata: { ...message.metadata, providerRequestId } };
+}

package/src/openai/request-options.ts

@@ -0,0 +1,14 @@
+import type OpenAI from 'openai';
+
+/**
+ * Per-request SDK options, or none at all when there is neither a signal nor a header to send, so
+ * a call without either keeps the exact shape it always had.
+ */
+export function openAIRequestOptions(
+  signal: AbortSignal | undefined,
+  headers: Readonly<Record<string, string>> | undefined,
+): OpenAI.RequestOptions | undefined {
+  const hasHeaders = headers !== undefined && Object.keys(headers).length > 0;
+  if (!signal && !hasHeaders) return undefined;
+  return { ...(signal ? { signal } : {}), ...(hasHeaders ? { headers: { ...headers } } : {}) };
+}

package/src/openai/responses-chat.ts

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto';
+
+import { toProviderError } from '@robota-sdk/agent-core';
+
+import {
+  observeProviderNativeRawPayloadStream,
+  toOpenAIResponsesToolChoice,
+} from '@robota-sdk/agent-provider-openai-compatible/shared';
+
+import { buildOpenAIResponsesTextConfig } from './openai-request-format';
+import { resolveOpenAIReasoningOptions } from './reasoning-effort';
+import {
+  awaitWithProviderRequestId,
+  readOpenAIRequestId,
+  withProviderRequestId,
+} from './request-id';
+import {
+  convertToOpenAIResponsesInput,
+  convertToOpenAIResponsesTools,
+} from './responses-converter';
+import { openAIRequestOptions } from './request-options';
+import { assembleOpenAIResponsesStream, parseOpenAIResponsesResponse } from './responses-parser';
+
+import type {
+  IOpenAIResponsesRequestNonStreaming,
+  IOpenAIResponsesRequestStreaming,
+  TOpenAIResponsesStreamEvent,
+} from './responses-types';
+import type { IOpenAIProviderOptions } from './types';
+import type { IChatOptions, TTextDeltaCallback, TUniversalMessage } from '@robota-sdk/agent-core';
+import type OpenAI from 'openai';
+
+export interface IOpenAIResponsesChatOptions {
+  client?: OpenAI;
+  messages: TUniversalMessage[];
+  chatOptions?: IChatOptions;
+  providerOptions: IOpenAIProviderOptions;
+  onTextDelta?: TTextDeltaCallback;
+  /** Per-request headers (trusted `traceparent`), sent after the raw request payload is captured. */
+  requestHeaders?: Readonly<Record<string, string>>;
+}
+
+interface IResponsesStreamMessageQueue {
+  deltas: TUniversalMessage[];
+  finalMessage?: TUniversalMessage;
+  error?: Error;
+  wake?: () => void;
+}
+
+export async function chatWithOpenAIResponsesApi(
+  input: IOpenAIResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+  if (textDeltaCb) {
+    return chatWithOpenAIResponsesStreamingAssembly({
+      ...input,
+      chatOptions: {
+        ...input.chatOptions,
+        onTextDelta: textDeltaCb,
+      },
+    });
+  }
+
+  if (!input.client) {
+    throw new Error('OpenAI Responses client not available.');
+  }
+
+  try {
+    const requestParams = buildResponsesRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const response = await input.client.responses.create(
+      requestParams as OpenAI.Responses.ResponseCreateParamsNonStreaming,
+      openAIRequestOptions(input.chatOptions?.signal, input.requestHeaders),
+    );
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'response',
+      payload: response,
+    });
+    return withProviderRequestId(
+      parseOpenAIResponsesResponse(response),
+      readOpenAIRequestId(response),
+    );
+  } catch (error) {
+    throw toProviderError(error, 'openai', 'OpenAI responses failed');
+  }
+}
+
+export async function* chatStreamWithOpenAIResponsesApi(
+  input: IOpenAIResponsesChatOptions,
+): AsyncIterable<TUniversalMessage> {
+  const queue: IResponsesStreamMessageQueue = { deltas: [] };
+  const textDeltaCb = input.chatOptions?.onTextDelta ?? input.onTextDelta;
+  const assembly = chatWithOpenAIResponsesStreamingAssembly({
+    ...input,
+    chatOptions: {
+      ...input.chatOptions,
+      onTextDelta: (delta) => {
+        textDeltaCb?.(delta);
+        enqueueStreamDelta(queue, createStreamDeltaMessage(delta));
+      },
+    },
+  })
+    .then((result) => finishStreamQueue(queue, result))
+    .catch((error) => failStreamQueue(queue, toError(error)));
+
+  yield* drainResponsesStreamQueue(queue);
+  await assembly;
+}
+
+async function chatWithOpenAIResponsesStreamingAssembly(
+  input: IOpenAIResponsesChatOptions,
+): Promise<TUniversalMessage> {
+  if (!input.client) {
+    throw new Error('OpenAI Responses client not available.');
+  }
+
+  try {
+    const requestParams = buildResponsesStreamingRequestParams(input);
+    input.chatOptions?.onProviderNativeRawPayload?.({
+      provider: 'openai',
+      apiSurface: 'responses',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const { data: stream, providerRequestId } = await awaitWithProviderRequestId(
+      input.client.responses.create(
+        requestParams as OpenAI.Responses.ResponseCreateParamsStreaming,
+        openAIRequestOptions(input.chatOptions?.signal, input.requestHeaders),
+      ),
+    );
+    const assembled = await assembleOpenAIResponsesStream({
+      stream: observeProviderNativeRawPayloadStream(
+        stream as AsyncIterable<TOpenAIResponsesStreamEvent>,
+        {
+          provider: 'openai',
+          apiSurface: 'responses',
+          onProviderNativeRawPayload: input.chatOptions?.onProviderNativeRawPayload,
+        },
+      ),
+      onTextDelta: input.chatOptions?.onTextDelta,
+      signal: input.chatOptions?.signal,
+    });
+    return withProviderRequestId(assembled, providerRequestId);
+  } catch (error) {
+    throw toProviderError(error, 'openai', 'OpenAI responses stream failed');
+  }
+}
+
+function buildResponsesRequestParams(
+  input: IOpenAIResponsesChatOptions,
+): IOpenAIResponsesRequestNonStreaming {
+  const model = input.chatOptions?.model ?? input.providerOptions.defaultModel;
+  if (!model) {
+    throw new Error(
+      'Model is required in chat options. Please specify a model in defaultModel configuration.',
+    );
+  }
+
+  const tools = convertToOpenAIResponsesTools(
+    input.chatOptions?.tools,
+    input.providerOptions.strictTools,
+  );
+  const textConfig = buildOpenAIResponsesTextConfig(input.providerOptions);
+  // Native effort mapping: thread the per-call reasoning-effort dial onto the Responses
+  // API `reasoning.effort` parameter, merged with any static reasoning options.
+  const reasoning = resolveOpenAIReasoningOptions(
+    input.providerOptions.reasoning,
+    input.chatOptions?.effortResolution,
+  );
+  return {
+    model,
+    input: convertToOpenAIResponsesInput(input.messages),
+    ...(tools !== undefined && {
+      tools,
+      tool_choice: toOpenAIResponsesToolChoice(input.chatOptions?.toolChoice),
+    }),
+    ...(input.chatOptions?.temperature !== undefined && {
+      temperature: input.chatOptions.temperature,
+    }),
+    ...(input.chatOptions?.maxTokens !== undefined && {
+      max_output_tokens: input.chatOptions.maxTokens,
+    }),
+    ...(textConfig !== undefined && { text: textConfig }),
+    ...(reasoning !== undefined && {
+      reasoning,
+    }),
+    ...(input.providerOptions.includeEncryptedReasoning === true && {
+      include: ['reasoning.encrypted_content'],
+    }),
+    ...(input.providerOptions.store !== undefined && { store: input.providerOptions.store }),
+  };
+}
+
+function buildResponsesStreamingRequestParams(
+  input: IOpenAIResponsesChatOptions,
+): IOpenAIResponsesRequestStreaming {
+  return {
+    ...buildResponsesRequestParams(input),
+    stream: true,
+  };
+}
+
+function createStreamDeltaMessage(delta: string): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content: delta,
+    state: 'complete',
+    timestamp: new Date(),
+    metadata: {
+      providerApiSurface: 'responses',
+      isStreamChunk: true,
+      isComplete: false,
+    },
+  };
+}
+
+async function* drainResponsesStreamQueue(
+  queue: IResponsesStreamMessageQueue,
+): AsyncIterable<TUniversalMessage> {
+  while (true) {
+    const next = queue.deltas.shift();
+    if (next !== undefined) {
+      yield next;
+      continue;
+    }
+    if (queue.error !== undefined) {
+      throw queue.error;
+    }
+    if (queue.finalMessage !== undefined) {
+      yield createFinalStreamMessage(queue.finalMessage);
+      return;
+    }
+    await waitForStreamQueue(queue);
+  }
+}
+
+function enqueueStreamDelta(queue: IResponsesStreamMessageQueue, message: TUniversalMessage): void {
+  queue.deltas.push(message);
+  wakeStreamQueue(queue);
+}
+
+function finishStreamQueue(queue: IResponsesStreamMessageQueue, result: TUniversalMessage): void {
+  queue.finalMessage = result;
+  wakeStreamQueue(queue);
+}
+
+function failStreamQueue(queue: IResponsesStreamMessageQueue, error: Error): void {
+  queue.error = error;
+  wakeStreamQueue(queue);
+}
+
+function waitForStreamQueue(queue: IResponsesStreamMessageQueue): Promise<void> {
+  return new Promise((resolve) => {
+    queue.wake = resolve;
+  });
+}
+
+function wakeStreamQueue(queue: IResponsesStreamMessageQueue): void {
+  queue.wake?.();
+  queue.wake = undefined;
+}
+
+function createFinalStreamMessage(result: TUniversalMessage): TUniversalMessage {
+  return {
+    ...result,
+    content: '',
+    metadata: {
+      ...result.metadata,
+      isStreamChunk: true,
+      isComplete: true,
+    },
+  };
+}
+
+function toError(error: Error | string): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/openai/responses-converter.ts

@@ -0,0 +1,122 @@
+import type {
+  IOpenAIResponsesFunctionTool,
+  IOpenAIResponsesMessageInput,
+  TOpenAIResponsesInputContent,
+  TOpenAIResponsesInputItem,
+} from './responses-types';
+import type {
+  IAssistantMessage,
+  IToolSchema,
+  TUniversalMessage,
+  TUniversalMessagePart,
+} from '@robota-sdk/agent-core';
+
+export function convertToOpenAIResponsesInput(
+  messages: TUniversalMessage[],
+): TOpenAIResponsesInputItem[] {
+  return messages.flatMap((message) => convertMessage(message));
+}
+
+/**
+ * MCP-005: `tools` arrives ALREADY projected — `AbstractAIProvider.projectTools()` ran the strict or
+ * permissive profile (`STRICT_TOOL_SCHEMA_PROFILE` / `PERMISSIVE_TOOL_SCHEMA_PROFILE`) over every
+ * schema before this converter ever sees it, closing objects for strict mode where PROV-007's
+ * `closeObjectSchemas` used to run inline here. This function does no schema transformation of its
+ * own — it only shapes the already-projected `parameters` into the wire tool definition and keeps
+ * `strict: true` on the emitted field when `strictTools` is on (a request-field concern, not a schema
+ * one: the schema was already closed by the projection step).
+ */
+export function convertToOpenAIResponsesTools(
+  tools: IToolSchema[] | undefined,
+  strictTools: boolean | undefined,
+): IOpenAIResponsesFunctionTool[] | undefined {
+  const strict = strictTools ?? false;
+  const converted =
+    tools?.map((tool) => ({
+      type: 'function' as const,
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+      strict,
+    })) ?? [];
+  return converted.length > 0 ? converted : undefined;
+}
+
+function convertMessage(message: TUniversalMessage): TOpenAIResponsesInputItem[] {
+  if (message.role === 'user') {
+    return [createMessageInput('user', getUserContent(message.content, message.parts))];
+  }
+  if (message.role === 'system') {
+    return [createMessageInput('system', 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 [
+      {
+        type: 'function_call_output',
+        call_id: message.toolCallId,
+        output: message.content || '',
+      },
+    ];
+  }
+  return convertAssistantMessage(message);
+}
+
+function convertAssistantMessage(message: IAssistantMessage): TOpenAIResponsesInputItem[] {
+  const items: TOpenAIResponsesInputItem[] = [];
+  if (message.content && message.content.length > 0) {
+    items.push(createMessageInput('assistant', message.content));
+  }
+  for (const toolCall of message.toolCalls ?? []) {
+    items.push({
+      type: 'function_call',
+      call_id: toolCall.id,
+      name: toolCall.function.name,
+      arguments: toolCall.function.arguments,
+    });
+  }
+  if (items.length === 0) {
+    items.push(createMessageInput('assistant', ''));
+  }
+  return items;
+}
+
+function getUserContent(
+  content: string,
+  parts: TUniversalMessagePart[] | undefined,
+): string | TOpenAIResponsesInputContent[] {
+  if (!parts || parts.length === 0) {
+    return content;
+  }
+
+  const converted = parts.map((part) => convertPart(part));
+  if (content.length > 0 && !parts.some((part) => part.type === 'text')) {
+    return [{ type: 'input_text', text: content }, ...converted];
+  }
+  return converted;
+}
+
+function convertPart(part: TUniversalMessagePart): TOpenAIResponsesInputContent {
+  if (part.type === 'text') {
+    return { type: 'input_text', text: part.text };
+  }
+  if (part.type === 'image_uri') {
+    return { type: 'input_image', image_url: part.uri };
+  }
+  return {
+    type: 'input_image',
+    image_url: `data:${part.mimeType};base64,${part.data}`,
+  };
+}
+
+function createMessageInput(
+  role: IOpenAIResponsesMessageInput['role'],
+  content: string | TOpenAIResponsesInputContent[],
+): IOpenAIResponsesMessageInput {
+  return {
+    role,
+    content,
+  };
+}