@purista/harness-openai 1.2.3 → 1.2.4

package/README.md

@@ -12,6 +12,37 @@ Configure the provider with an OpenAI API key in your application environment.
 The adapter is designed for use through the typed `@purista/harness` model
 provider port.
 
+```ts
+import { openai } from '@purista/harness-openai'
+
+const provider = openai({
+  apiKey: process.env.OPENAI_API_KEY!,
+  baseURL: process.env.OPENAI_BASE_URL
+})
+```
+
+By default, generation uses Chat Completions for compatibility with
+OpenAI-compatible endpoints:
+
+```ts
+openai({ apiKey: process.env.OPENAI_API_KEY! })
+```
+
+Use the Responses API for OpenAI reasoning models that require function tools
+and reasoning effort on `/v1/responses`, such as `gpt-5.5`:
+
+```ts
+openai({
+  apiKey: process.env.OPENAI_API_KEY!,
+  api: 'responses'
+})
+```
+
+When Chat Completions is used with tools and `providerOptions.reasoning_effort`,
+the adapter drops `reasoning_effort` and emits a warning instead of sending a
+request that OpenAI rejects. Use `api: 'responses'` when you need reasoning
+effort and tool calls together.
+
 ## Package Format
 
 This package is ESM-only and ships compiled JavaScript plus TypeScript

package/dist/index.d.ts

@@ -4,6 +4,14 @@ import { type ClientOptions } from 'openai';
  * Configuration for the OpenAI model provider factory.
  */
 export interface OpenAiFactoryOptions extends ClientOptions {
+    /**
+     * OpenAI API surface used for text/object generation.
+     *
+     * Use `responses` for reasoning models that require the Responses API for
+     * function tools with reasoning effort, such as `gpt-5.5`. The default keeps
+     * existing OpenAI-compatible chat-completions endpoints working.
+     */
+    api?: 'chat_completions' | 'responses';
     /** Optional injected client for tests or custom transport behavior. */
     client?: OpenAiClient;
     /** Optional adapter-level logger override. Defaults to the harness logger when registered. */
@@ -18,7 +26,7 @@ export interface OpenAiFactoryOptions extends ClientOptions {
  *
  * Execution model:
  * - In-process adapter code
- * - External network calls to OpenAI-compatible chat completions endpoint
+ * - External network calls to OpenAI chat completions or responses endpoint
  * - AsyncIterable streaming for `textStream` and `objectStream`
  *
  * @example
@@ -63,6 +71,11 @@ export type OpenAiClient = {
             }): Promise<any>;
         };
     };
+    responses?: {
+        create(payload: unknown, options?: {
+            signal?: AbortSignal;
+        }): Promise<any>;
+    };
     embeddings: {
         create(payload: unknown, options?: {
             signal?: AbortSignal;

package/dist/index.js

@@ -5,7 +5,7 @@ import OpenAI, {} from 'openai';
  *
  * Execution model:
  * - In-process adapter code
- * - External network calls to OpenAI-compatible chat completions endpoint
+ * - External network calls to OpenAI chat completions or responses endpoint
  * - AsyncIterable streaming for `textStream` and `objectStream`
  *
  * @example
@@ -60,12 +60,20 @@ class OpenAiModelProvider extends BaseModelProvider {
     }
     async doText(req) {
         req.signal.throwIfAborted();
-        const response = await createChatCompletion(this.client, req, false);
-        return mapTextResponse(response, req);
+        if (this.options.api === 'responses') {
+            const response = await createResponse(this.client, req, false);
+            return mapResponsesTextResponse(response, req);
+        }
+        const response = await createChatCompletion(this.client, req, false, this.getLogger());
+        return mapChatTextResponse(response, req);
     }
     async *doTextStream(req) {
         req.signal.throwIfAborted();
-        const stream = await createChatCompletion(this.client, req, true);
+        if (this.options.api === 'responses') {
+            yield* streamResponsesText(this.client, req);
+            return;
+        }
+        const stream = await createChatCompletion(this.client, req, true, this.getLogger());
         let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = 'stop';
         const toolState = new Map();
@@ -95,9 +103,21 @@ class OpenAiModelProvider extends BaseModelProvider {
     }
     async doObject(req) {
         req.signal.throwIfAborted();
-        const response = await createChatCompletion(this.client, req, false);
+        if (this.options.api === 'responses') {
+            const response = await createResponse(this.client, req, false);
+            const content = extractResponsesText(response);
+            const toolCalls = extractResponsesToolCalls(response, req, 'object');
+            return {
+                object: parseJson(content || '{}', req, 'object'),
+                ...(toolCalls ? { toolCalls } : {}),
+                usage: toResponsesUsage(response.usage),
+                finishReason: toResponsesFinishReason(response),
+                raw: response
+            };
+        }
+        const response = await createChatCompletion(this.client, req, false, this.getLogger());
         const textContent = response.choices[0]?.message?.content ?? '{}';
-        const toolCalls = extractToolCalls(response, req, 'object');
+        const toolCalls = extractChatToolCalls(response, req, 'object');
         return {
             object: parseJson(textContent, req, 'object'),
             ...(toolCalls ? { toolCalls } : {}),
@@ -112,7 +132,11 @@ class OpenAiModelProvider extends BaseModelProvider {
         let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = 'stop';
         const toolState = new Map();
-        const stream = await createChatCompletion(this.client, req, true);
+        if (this.options.api === 'responses') {
+            yield* streamResponsesObject(this.client, req);
+            return;
+        }
+        const stream = await createChatCompletion(this.client, req, true, this.getLogger());
         for await (const chunk of stream) {
             req.signal.throwIfAborted();
             if (chunk.usage) {
@@ -158,11 +182,11 @@ class OpenAiModelProvider extends BaseModelProvider {
     }
 }
 function toClientOptions(options) {
-    const { client: _client, harnessLogger: _harnessLogger, telemetry: _telemetry, harnessTimeoutMs: _harnessTimeoutMs, ...clientOptions } = options;
+    const { api: _api, client: _client, harnessLogger: _harnessLogger, telemetry: _telemetry, harnessTimeoutMs: _harnessTimeoutMs, ...clientOptions } = options;
     return clientOptions;
 }
-function mapTextResponse(response, req) {
-    const toolCalls = extractToolCalls(response, req, 'text');
+function mapChatTextResponse(response, req) {
+    const toolCalls = extractChatToolCalls(response, req, 'text');
     return {
         content: response.choices[0]?.message?.content ?? '',
         ...(toolCalls ? { toolCalls } : {}),
@@ -171,7 +195,7 @@ function mapTextResponse(response, req) {
         raw: response
     };
 }
-function extractToolCalls(response, req, method) {
+function extractChatToolCalls(response, req, method) {
     const toolCalls = response.choices[0]?.message?.tool_calls;
     if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
         return undefined;
@@ -184,13 +208,14 @@ function extractToolCalls(response, req, method) {
         arguments: parseToolArgs(call.function.arguments, req, method)
     }));
 }
-async function createChatCompletion(client, req, stream) {
+async function createChatCompletion(client, req, stream, logger) {
     const messages = toOpenAiMessages(req.messages);
     const providerOptions = {
         ...(req.defaults?.providerOptions ?? {}),
         ...(req.call?.providerOptions ?? {})
     };
     const { requestOptions, ...bodyOptions } = providerOptions;
+    const normalizedBodyOptions = omitUnsupportedChatCompletionOptions(bodyOptions, req, logger);
     return client.chat.completions.create({
         model: req.model,
         messages,
@@ -204,9 +229,58 @@ async function createChatCompletion(client, req, stream) {
         stop: req.call?.stopSequences ?? req.defaults?.stopSequences,
         ...(req.tools && (req.call?.parallelToolCalls ?? req.defaults?.parallelToolCalls) !== undefined ? { parallel_tool_calls: req.call?.parallelToolCalls ?? req.defaults?.parallelToolCalls } : {}),
         response_format: toResponseFormat(req),
+        ...normalizedBodyOptions
+    }, { ...requestOptions, signal: req.signal });
+}
+async function createResponse(client, req, stream) {
+    if (!client.responses?.create) {
+        throw new ModelError('OpenAI client does not expose the Responses API.', {
+            provider: 'openai',
+            model: req.model,
+            method: stream ? ('schema' in req ? 'objectStream' : 'textStream') : ('schema' in req ? 'object' : 'text'),
+            reason: 'unstructured_response',
+            providerBody: { api: 'responses' }
+        });
+    }
+    const providerOptions = {
+        ...(req.defaults?.providerOptions ?? {}),
+        ...(req.call?.providerOptions ?? {})
+    };
+    const { requestOptions, ...bodyOptions } = toResponsesProviderOptions(providerOptions);
+    return client.responses.create({
+        model: req.model,
+        input: toResponsesInput(req.messages),
+        stream,
+        ...(stream ? { stream_options: { include_usage: true } } : {}),
+        tools: toResponsesTools(req.tools),
+        temperature: req.call?.temperature ?? req.defaults?.temperature,
+        max_output_tokens: req.call?.maxTokens ?? req.defaults?.maxTokens,
+        top_p: req.call?.topP ?? req.defaults?.topP,
+        parallel_tool_calls: req.tools && (req.call?.parallelToolCalls ?? req.defaults?.parallelToolCalls) !== undefined ? req.call?.parallelToolCalls ?? req.defaults?.parallelToolCalls : undefined,
+        text: toResponsesTextFormat(req),
         ...bodyOptions
     }, { ...requestOptions, signal: req.signal });
 }
+function omitUnsupportedChatCompletionOptions(bodyOptions, req, logger) {
+    if (!req.tools || req.tools.length === 0 || !('reasoning_effort' in bodyOptions))
+        return bodyOptions;
+    const { reasoning_effort: _reasoningEffort, ...rest } = bodyOptions;
+    logger?.warn('OpenAI reasoning_effort dropped for chat completions with tools.', {
+        provider: 'openai',
+        model: req.model,
+        api: 'chat_completions',
+        reason: 'reasoning_effort_not_supported_with_tools',
+        recommendation: "Use openai({ api: 'responses' }) for reasoning models that require tools with reasoning effort."
+    });
+    return rest;
+}
+function toResponsesProviderOptions(providerOptions) {
+    const { reasoning_effort: reasoningEffort, reasoning, ...rest } = providerOptions;
+    if (reasoningEffort !== undefined && reasoning === undefined) {
+        return { ...rest, reasoning: { effort: reasoningEffort } };
+    }
+    return { ...rest, ...(reasoning !== undefined ? { reasoning } : {}) };
+}
 function toResponseFormat(req) {
     if (!('schema' in req))
         return undefined;
@@ -219,6 +293,18 @@ function toResponseFormat(req) {
         }
     };
 }
+function toResponsesTextFormat(req) {
+    if (!('schema' in req))
+        return undefined;
+    return {
+        format: {
+            type: 'json_schema',
+            name: 'harness_response',
+            strict: false,
+            schema: req.schema
+        }
+    };
+}
 function toOpenAiMessages(messages) {
     return messages.map((message) => {
         if (message.role === 'assistant' && message.toolCalls && message.toolCalls.length > 0) {
@@ -272,6 +358,67 @@ function toOpenAiMessages(messages) {
         };
     });
 }
+function toResponsesInput(messages) {
+    const input = [];
+    for (const message of messages) {
+        if (message.role === 'tool') {
+            input.push({
+                type: 'function_call_output',
+                call_id: message.toolCallId,
+                output: message.content
+            });
+            continue;
+        }
+        if (message.role === 'assistant' && message.toolCalls && message.toolCalls.length > 0) {
+            if (typeof message.content === 'string' && message.content.length > 0) {
+                input.push({
+                    type: 'message',
+                    role: 'assistant',
+                    content: message.content
+                });
+            }
+            for (const call of message.toolCalls) {
+                input.push({
+                    type: 'function_call',
+                    id: call.id,
+                    call_id: call.id,
+                    name: call.name,
+                    arguments: JSON.stringify(call.arguments)
+                });
+            }
+            continue;
+        }
+        input.push({
+            type: 'message',
+            role: message.role,
+            content: toResponsesMessageContent(message)
+        });
+    }
+    return input;
+}
+function toResponsesMessageContent(message) {
+    if (typeof message.content === 'string') {
+        return message.content;
+    }
+    return message.content.map((part) => {
+        if (part.kind === 'text') {
+            return { type: 'input_text', text: part.text };
+        }
+        if (part.kind === 'image') {
+            return {
+                type: 'input_image',
+                image_url: `data:${part.mimeType};base64,${part.dataBase64}`
+            };
+        }
+        if (part.kind === 'image_url') {
+            return {
+                type: 'input_image',
+                image_url: part.url
+            };
+        }
+        return { type: 'input_text', text: `[unsupported ${part.kind} content omitted]` };
+    });
+}
 function toTools(tools) {
     if (!tools || tools.length === 0) {
         return undefined;
@@ -285,6 +432,159 @@ function toTools(tools) {
         }
     }));
 }
+function toResponsesTools(tools) {
+    if (!tools || tools.length === 0) {
+        return undefined;
+    }
+    return tools.map((tool) => ({
+        type: 'function',
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        strict: false
+    }));
+}
+function mapResponsesTextResponse(response, req) {
+    const toolCalls = extractResponsesToolCalls(response, req, 'text');
+    return {
+        content: extractResponsesText(response),
+        ...(toolCalls ? { toolCalls } : {}),
+        usage: toResponsesUsage(response.usage),
+        finishReason: toResponsesFinishReason(response),
+        raw: response
+    };
+}
+async function* streamResponsesText(client, req) {
+    const stream = await createResponse(client, req, true);
+    let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    let finishReason = 'stop';
+    const toolState = new Map();
+    for await (const event of stream) {
+        req.signal.throwIfAborted();
+        if (event.type === 'response.output_text.delta') {
+            yield { kind: 'delta', text: event.delta };
+        }
+        else if (event.type === 'response.output_item.added' || event.type === 'response.output_item.done') {
+            accumulateResponsesToolCallItem(toolState, event);
+        }
+        else if (event.type === 'response.function_call_arguments.delta') {
+            accumulateResponsesToolCallDelta(toolState, event);
+        }
+        else if (event.type === 'response.function_call_arguments.done') {
+            accumulateResponsesToolCallDone(toolState, event);
+        }
+        else if (event.type === 'response.completed') {
+            usage = toResponsesUsage(event.response?.usage);
+            finishReason = toResponsesFinishReason(event.response);
+        }
+        else if (event.type === 'response.failed' || event.type === 'response.incomplete') {
+            finishReason = 'error';
+        }
+    }
+    for (const call of finalizeResponsesStreamToolCalls(toolState, req, 'textStream')) {
+        yield { kind: 'tool_call', call };
+    }
+    yield { kind: 'finish', usage, finishReason };
+}
+async function* streamResponsesObject(client, req) {
+    const stream = await createResponse(client, req, true);
+    let partial = '';
+    let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    let finishReason = 'stop';
+    const toolState = new Map();
+    for await (const event of stream) {
+        req.signal.throwIfAborted();
+        if (event.type === 'response.output_text.delta') {
+            partial += event.delta;
+            yield { kind: 'partial', partial: safePartialJson(partial) };
+        }
+        else if (event.type === 'response.output_item.added' || event.type === 'response.output_item.done') {
+            accumulateResponsesToolCallItem(toolState, event);
+        }
+        else if (event.type === 'response.function_call_arguments.delta') {
+            accumulateResponsesToolCallDelta(toolState, event);
+        }
+        else if (event.type === 'response.function_call_arguments.done') {
+            accumulateResponsesToolCallDone(toolState, event);
+        }
+        else if (event.type === 'response.completed') {
+            usage = toResponsesUsage(event.response?.usage);
+            finishReason = toResponsesFinishReason(event.response);
+        }
+        else if (event.type === 'response.failed' || event.type === 'response.incomplete') {
+            finishReason = 'error';
+        }
+    }
+    for (const call of finalizeResponsesStreamToolCalls(toolState, req, 'objectStream')) {
+        yield { kind: 'tool_call', call };
+    }
+    const object = parseJson(partial || '{}', req, 'objectStream');
+    yield { kind: 'finish', object, usage, finishReason };
+}
+function extractResponsesText(response) {
+    if (typeof response.output_text === 'string')
+        return response.output_text;
+    const parts = [];
+    for (const item of response.output ?? []) {
+        if (item?.type !== 'message')
+            continue;
+        for (const content of item.content ?? []) {
+            if (content?.type === 'output_text' && typeof content.text === 'string') {
+                parts.push(content.text);
+            }
+        }
+    }
+    return parts.join('');
+}
+function extractResponsesToolCalls(response, req, method) {
+    const toolCalls = (response.output ?? []).filter((item) => item?.type === 'function_call' && item.call_id && item.name);
+    if (toolCalls.length === 0)
+        return undefined;
+    return toolCalls.map((call) => ({
+        id: String(call.call_id),
+        name: String(call.name),
+        arguments: parseToolArgs(call.arguments, req, method)
+    }));
+}
+function accumulateResponsesToolCallItem(state, event) {
+    if (event.item?.type !== 'function_call')
+        return;
+    const index = typeof event.output_index === 'number' ? event.output_index : 0;
+    const existing = state.get(index) ?? { args: '' };
+    if (event.item.call_id)
+        existing.id = String(event.item.call_id);
+    if (event.item.name)
+        existing.name = String(event.item.name);
+    if (typeof event.item.arguments === 'string')
+        existing.args = event.item.arguments;
+    state.set(index, existing);
+}
+function accumulateResponsesToolCallDelta(state, event) {
+    const index = typeof event.output_index === 'number' ? event.output_index : 0;
+    const existing = state.get(index) ?? { args: '' };
+    if (typeof event.delta === 'string')
+        existing.args += event.delta;
+    state.set(index, existing);
+}
+function accumulateResponsesToolCallDone(state, event) {
+    const index = typeof event.output_index === 'number' ? event.output_index : 0;
+    const existing = state.get(index) ?? { args: '' };
+    existing.id ??= String(event.item_id);
+    existing.name = String(event.name);
+    if (typeof event.arguments === 'string')
+        existing.args = event.arguments;
+    state.set(index, existing);
+}
+function finalizeResponsesStreamToolCalls(state, req, method) {
+    return [...state.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .filter(([, call]) => call.id && call.name)
+        .map(([, call]) => ({
+        id: call.id,
+        name: call.name,
+        arguments: parseToolArgs(call.args || undefined, req, method)
+    }));
+}
 function accumulateToolCallDeltas(state, deltas) {
     for (const delta of deltas) {
         const index = typeof delta?.index === 'number' ? delta.index : 0;
@@ -352,6 +652,9 @@ function toUsage(inputTokens, outputTokens) {
         totalTokens: input + output
     };
 }
+function toResponsesUsage(usage) {
+    return toUsage(usage?.input_tokens, usage?.output_tokens);
+}
 function toFinishReason(value) {
     switch (value) {
         case 'stop':
@@ -363,3 +666,17 @@ function toFinishReason(value) {
             return 'error';
     }
 }
+function toResponsesFinishReason(response) {
+    if (!response)
+        return 'error';
+    if ((response.output ?? []).some((item) => item?.type === 'function_call'))
+        return 'tool_calls';
+    switch (response.status) {
+        case 'completed':
+            return 'stop';
+        case 'incomplete':
+            return 'length';
+        default:
+            return response.error ? 'error' : 'stop';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness-openai",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "OpenAI model provider adapter for @purista/harness.",
   "type": "module",
   "main": "./dist/index.js",