@purista/harness-openai 1.2.5 → 1.5.0

package/README.md

@@ -43,6 +43,14 @@ 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.
 
+On the Responses API, tool-call responses carry the turn's raw output items
+(including reasoning items) as `providerItems`. The harness agent loop passes
+them back on the follow-up round and the adapter echoes them verbatim, as
+OpenAI recommends for reasoning models with manually managed conversation
+state. For stateless requests (`store: false`), additionally set
+`providerOptions: { store: false, include: ['reasoning.encrypted_content'] }`
+so the encrypted reasoning content rides along in the replayed items.
+
 ## Package Format
 
 This package is ESM-only and ships compiled JavaScript plus TypeScript

package/dist/index.d.ts

@@ -53,6 +53,7 @@ export interface OpenAiFactoryOptions extends ClientOptions {
  *     summarize: {
  *       input: z.string(),
  *       output: z.string(),
+ *       delegation: { agents: ['assistant'] },
  *       handler: (ctx) => ctx.agents.assistant(ctx.input)
  *     }
  *   })

package/dist/index.js

@@ -1,4 +1,4 @@
-import { BaseModelProvider, ModelError } from '@purista/harness';
+import { BaseModelProvider, ModelError, accumulateStreamToolCallDeltas, createStreamToolCallState, finalizeStreamToolCalls, malformedResponseError, parseProviderJson, safePartialJson, sanitizeProviderMessage, toTokenUsage } from '@purista/harness';
 import OpenAI, {} from 'openai';
 /**
  * Creates an OpenAI-backed harness `ModelProvider`.
@@ -32,6 +32,7 @@ import OpenAI, {} from 'openai';
  *     summarize: {
  *       input: z.string(),
  *       output: z.string(),
+ *       delegation: { agents: ['assistant'] },
  *       handler: (ctx) => ctx.agents.assistant(ctx.input)
  *     }
  *   })
@@ -62,6 +63,7 @@ class OpenAiModelProvider extends BaseModelProvider {
         req.signal.throwIfAborted();
         if (this.options.api === 'responses') {
             const response = await createResponse(this.client, req, false);
+            throwIfResponsesFailure(response, req, 'text');
             return mapResponsesTextResponse(response, req);
         }
         const response = await createChatCompletion(this.client, req, false, this.getLogger());
@@ -76,12 +78,13 @@ class OpenAiModelProvider extends BaseModelProvider {
         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();
+        let providerFinishReason;
+        const toolState = createStreamToolCallState();
         for await (const chunk of stream) {
             req.signal.throwIfAborted();
             // The usage chunk arrives with an empty choices array, so read it first.
             if (chunk.usage) {
-                usage = toUsage(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
+                usage = toTokenUsage(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
             }
             const choice = chunk.choices?.[0];
             if (!choice)
@@ -90,28 +93,33 @@ class OpenAiModelProvider extends BaseModelProvider {
                 yield { kind: 'delta', text: choice.delta.content };
             }
             if (choice.delta?.tool_calls) {
-                accumulateToolCallDeltas(toolState, choice.delta.tool_calls);
+                accumulateStreamToolCallDeltas(toolState, choice.delta.tool_calls);
             }
             if (choice.finish_reason) {
-                finishReason = toFinishReason(choice.finish_reason);
+                providerFinishReason = choice.finish_reason;
+                finishReason = toFinishReason(providerFinishReason);
             }
         }
-        for (const call of finalizeStreamToolCalls(toolState, req, 'textStream')) {
+        for (const call of finalizeStreamToolCalls(toolState, callContext(req, 'textStream'), MALFORMED_TOOL_ARGS_MESSAGE)) {
             yield { kind: 'tool_call', call };
         }
-        yield { kind: 'finish', usage, finishReason };
+        yield { kind: 'finish', usage, finishReason, outcome: toOutcome(finishReason, providerFinishReason) };
     }
     async doObject(req) {
         req.signal.throwIfAborted();
         if (this.options.api === 'responses') {
             const response = await createResponse(this.client, req, false);
+            throwIfResponsesFailure(response, req, 'object');
             const content = extractResponsesText(response);
             const toolCalls = extractResponsesToolCalls(response, req, 'object');
+            const providerItems = toResponsesProviderItems(response.output, toolCalls);
             return {
                 object: parseJson(content || '{}', req, 'object'),
                 ...(toolCalls ? { toolCalls } : {}),
+                ...(providerItems ? { providerItems } : {}),
                 usage: toResponsesUsage(response.usage),
                 finishReason: toResponsesFinishReason(response),
+                outcome: toResponsesOutcome(response),
                 raw: response
             };
         }
@@ -121,8 +129,9 @@ class OpenAiModelProvider extends BaseModelProvider {
         return {
             object: parseJson(textContent, req, 'object'),
             ...(toolCalls ? { toolCalls } : {}),
-            usage: toUsage(response.usage?.prompt_tokens, response.usage?.completion_tokens),
+            usage: toTokenUsage(response.usage?.prompt_tokens, response.usage?.completion_tokens),
             finishReason: toFinishReason(response.choices[0]?.finish_reason),
+            outcome: toOutcome(toFinishReason(response.choices[0]?.finish_reason), response.choices[0]?.finish_reason),
             raw: response
         };
     }
@@ -131,7 +140,8 @@ class OpenAiModelProvider extends BaseModelProvider {
         let partial = '';
         let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = 'stop';
-        const toolState = new Map();
+        let providerFinishReason;
+        const toolState = createStreamToolCallState();
         if (this.options.api === 'responses') {
             yield* streamResponsesObject(this.client, req);
             return;
@@ -140,7 +150,7 @@ class OpenAiModelProvider extends BaseModelProvider {
         for await (const chunk of stream) {
             req.signal.throwIfAborted();
             if (chunk.usage) {
-                usage = toUsage(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
+                usage = toTokenUsage(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
             }
             const choice = chunk.choices?.[0];
             if (!choice)
@@ -150,17 +160,18 @@ class OpenAiModelProvider extends BaseModelProvider {
                 yield { kind: 'partial', partial: safePartialJson(partial) };
             }
             if (choice.delta?.tool_calls) {
-                accumulateToolCallDeltas(toolState, choice.delta.tool_calls);
+                accumulateStreamToolCallDeltas(toolState, choice.delta.tool_calls);
             }
             if (choice.finish_reason) {
-                finishReason = toFinishReason(choice.finish_reason);
+                providerFinishReason = choice.finish_reason;
+                finishReason = toFinishReason(providerFinishReason);
             }
         }
-        for (const call of finalizeStreamToolCalls(toolState, req, 'objectStream')) {
+        for (const call of finalizeStreamToolCalls(toolState, callContext(req, 'objectStream'), MALFORMED_TOOL_ARGS_MESSAGE)) {
             yield { kind: 'tool_call', call };
         }
         const object = parseJson(partial || '{}', req, 'objectStream');
-        yield { kind: 'finish', object, usage, finishReason };
+        yield { kind: 'finish', object, usage, finishReason, outcome: toOutcome(finishReason, providerFinishReason) };
     }
     async doEmbed(req) {
         req.signal.throwIfAborted();
@@ -176,22 +187,25 @@ class OpenAiModelProvider extends BaseModelProvider {
         }, { ...requestOptions, signal: req.signal });
         return {
             embeddings: response.data.map((item) => ({ index: item.index, vector: item.embedding })),
-            usage: toUsage(response.usage?.prompt_tokens, 0),
+            usage: toTokenUsage(response.usage?.prompt_tokens, 0),
             raw: response
         };
     }
 }
 function toClientOptions(options) {
     const { api: _api, client: _client, harnessLogger: _harnessLogger, telemetry: _telemetry, harnessTimeoutMs: _harnessTimeoutMs, ...clientOptions } = options;
-    return clientOptions;
+    return { maxRetries: 0, ...clientOptions };
 }
 function mapChatTextResponse(response, req) {
     const toolCalls = extractChatToolCalls(response, req, 'text');
+    const providerFinishReason = response.choices[0]?.finish_reason;
+    const finishReason = toFinishReason(providerFinishReason);
     return {
         content: response.choices[0]?.message?.content ?? '',
         ...(toolCalls ? { toolCalls } : {}),
-        usage: toUsage(response.usage?.prompt_tokens, response.usage?.completion_tokens),
-        finishReason: toFinishReason(response.choices[0]?.finish_reason),
+        usage: toTokenUsage(response.usage?.prompt_tokens, response.usage?.completion_tokens),
+        finishReason,
+        outcome: toOutcome(finishReason, providerFinishReason),
         raw: response
     };
 }
@@ -368,6 +382,13 @@ function toResponsesInput(messages) {
             });
             continue;
         }
+        if (message.role === 'assistant' && message.providerItems?.providerId === 'openai' && message.providerItems.items.length > 0) {
+            // Echo the captured turn (reasoning, message, and function_call items)
+            // verbatim, as the Responses API expects for manually managed state.
+            // Foreign provider items fall through to provider-neutral reconstruction.
+            input.push(...message.providerItems.items);
+            continue;
+        }
         if (message.role === 'assistant' && message.toolCalls && message.toolCalls.length > 0) {
             if (typeof message.content === 'string' && message.content.length > 0) {
                 input.push({
@@ -377,9 +398,11 @@ function toResponsesInput(messages) {
                 });
             }
             for (const call of message.toolCalls) {
+                // The Responses API only accepts an `fc_…` item id on `function_call`
+                // input items; the harness tool-call id is the `call_…` value, so the
+                // optional item id is omitted, mirroring `function_call_output`.
                 input.push({
                     type: 'function_call',
-                    id: call.id,
                     call_id: call.id,
                     name: call.name,
                     arguments: JSON.stringify(call.arguments)
@@ -445,18 +468,37 @@ function toResponsesTools(tools) {
 }
 function mapResponsesTextResponse(response, req) {
     const toolCalls = extractResponsesToolCalls(response, req, 'text');
+    const providerItems = toResponsesProviderItems(response.output, toolCalls);
     return {
         content: extractResponsesText(response),
         ...(toolCalls ? { toolCalls } : {}),
+        ...(providerItems ? { providerItems } : {}),
         usage: toResponsesUsage(response.usage),
         finishReason: toResponsesFinishReason(response),
+        outcome: toResponsesOutcome(response),
         raw: response
     };
 }
+/**
+ * Captures the turn's raw Responses output items on tool-call responses so
+ * they can be replayed verbatim on the follow-up round. OpenAI requires
+ * reasoning items returned with tool calls to be passed back with the tool
+ * outputs for reasoning models; echoing `response.output` unchanged is the
+ * pattern documented in the Responses migration guide.
+ */
+function toResponsesProviderItems(output, toolCalls) {
+    if (!toolCalls || toolCalls.length === 0)
+        return undefined;
+    if (!Array.isArray(output) || output.length === 0)
+        return undefined;
+    return { providerId: 'openai', items: output };
+}
 async function* streamResponsesText(client, req) {
     const stream = await createResponse(client, req, true);
     let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
     let finishReason = 'stop';
+    let outcome = toOutcome('stop');
+    let completedOutput;
     const toolState = new Map();
     for await (const event of stream) {
         req.signal.throwIfAborted();
@@ -475,21 +517,34 @@ async function* streamResponsesText(client, req) {
         else if (event.type === 'response.completed') {
             usage = toResponsesUsage(event.response?.usage);
             finishReason = toResponsesFinishReason(event.response);
+            outcome = toResponsesOutcome(event.response);
+            completedOutput = event.response?.output;
+        }
+        else if (event.type === 'response.failed') {
+            // A genuine provider failure must surface as an error so base retry and
+            // normalization apply, matching the chat-completions path.
+            throw responsesFailureError(event.response, req, 'textStream');
         }
-        else if (event.type === 'response.failed' || event.type === 'response.incomplete') {
-            finishReason = 'error';
+        else if (event.type === 'response.incomplete') {
+            usage = toResponsesUsage(event.response?.usage);
+            finishReason = toResponsesFinishReason(event.response);
+            outcome = toResponsesOutcome(event.response);
         }
     }
-    for (const call of finalizeResponsesStreamToolCalls(toolState, req, 'textStream')) {
+    const toolCalls = finalizeResponsesStreamToolCalls(toolState, req, 'textStream');
+    for (const call of toolCalls) {
         yield { kind: 'tool_call', call };
     }
-    yield { kind: 'finish', usage, finishReason };
+    const providerItems = toResponsesProviderItems(completedOutput, toolCalls);
+    yield { kind: 'finish', usage, finishReason, outcome, ...(providerItems ? { providerItems } : {}) };
 }
 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';
+    let outcome = toOutcome('stop');
+    let completedOutput;
     const toolState = new Map();
     for await (const event of stream) {
         req.signal.throwIfAborted();
@@ -509,16 +564,27 @@ async function* streamResponsesObject(client, req) {
         else if (event.type === 'response.completed') {
             usage = toResponsesUsage(event.response?.usage);
             finishReason = toResponsesFinishReason(event.response);
+            outcome = toResponsesOutcome(event.response);
+            completedOutput = event.response?.output;
         }
-        else if (event.type === 'response.failed' || event.type === 'response.incomplete') {
-            finishReason = 'error';
+        else if (event.type === 'response.failed') {
+            // A genuine provider failure must surface as an error so base retry and
+            // normalization apply, matching the chat-completions path.
+            throw responsesFailureError(event.response, req, 'objectStream');
+        }
+        else if (event.type === 'response.incomplete') {
+            usage = toResponsesUsage(event.response?.usage);
+            finishReason = toResponsesFinishReason(event.response);
+            outcome = toResponsesOutcome(event.response);
         }
     }
-    for (const call of finalizeResponsesStreamToolCalls(toolState, req, 'objectStream')) {
+    const toolCalls = finalizeResponsesStreamToolCalls(toolState, req, 'objectStream');
+    for (const call of toolCalls) {
         yield { kind: 'tool_call', call };
     }
     const object = parseJson(partial || '{}', req, 'objectStream');
-    yield { kind: 'finish', object, usage, finishReason };
+    const providerItems = toResponsesProviderItems(completedOutput, toolCalls);
+    yield { kind: 'finish', object, usage, finishReason, outcome, ...(providerItems ? { providerItems } : {}) };
 }
 function extractResponsesText(response) {
     if (typeof response.output_text === 'string')
@@ -568,8 +634,11 @@ function accumulateResponsesToolCallDelta(state, event) {
 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);
+    // `event.item_id` is the `fc_…` item id, not the `call_…` id required for
+    // `function_call_output`, so the call id only ever comes from the
+    // `response.output_item.added`/`done` events.
+    if (event.name)
+        existing.name = String(event.name);
     if (typeof event.arguments === 'string')
         existing.args = event.arguments;
     state.set(index, existing);
@@ -577,82 +646,58 @@ function accumulateResponsesToolCallDone(state, event) {
 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;
-        const existing = state.get(index) ?? { args: '' };
-        if (delta?.id)
-            existing.id = String(delta.id);
-        if (delta?.function?.name)
-            existing.name = String(delta.function.name);
-        if (typeof delta?.function?.arguments === 'string')
-            existing.args += delta.function.arguments;
-        state.set(index, existing);
-    }
-}
-function finalizeStreamToolCalls(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)
-    }));
+        .filter(([, call]) => call.name)
+        .map(([, call]) => {
+        if (!call.id) {
+            throw malformedResponseError(callContext(req, method), 'OpenAI streamed a function call without a call_id.', call, undefined);
+        }
+        return {
+            id: call.id,
+            name: call.name,
+            arguments: parseToolArgs(call.args || undefined, req, method)
+        };
+    });
 }
-function parseToolArgs(argumentsText, req, method) {
-    if (!argumentsText)
-        return {};
-    try {
-        return JSON.parse(argumentsText);
-    }
-    catch (error) {
-        throw malformedResponseError(req, method, 'OpenAI returned malformed tool-call argument JSON.', argumentsText, error);
-    }
+const MALFORMED_TOOL_ARGS_MESSAGE = 'OpenAI returned malformed tool-call argument JSON.';
+const MALFORMED_OBJECT_MESSAGE = 'OpenAI returned malformed structured object JSON.';
+function callContext(req, method) {
+    return { provider: 'openai', model: req.model, method };
 }
-function parseJson(content, req, method) {
-    try {
-        return JSON.parse(content);
-    }
-    catch (error) {
-        throw malformedResponseError(req, method, 'OpenAI returned malformed structured object JSON.', content, error);
+/** Throws when a non-streaming Responses result reports a provider failure. */
+function throwIfResponsesFailure(response, req, method) {
+    if (response?.status === 'failed' || response?.error) {
+        throw responsesFailureError(response, req, method);
     }
 }
-function malformedResponseError(req, method, message, body, cause) {
-    return new ModelError(message, {
+/**
+ * Maps a failed Responses-API result into a `ModelError` so the base
+ * provider's retry classification and normalization apply.
+ */
+function responsesFailureError(response, req, method) {
+    const providerCode = typeof response?.error?.code === 'string' ? response.error.code : undefined;
+    const rawMessage = typeof response?.error?.message === 'string' ? response.error.message : undefined;
+    const reason = providerCode === 'rate_limit_exceeded'
+        ? 'rate_limited'
+        : providerCode === 'server_error'
+            ? 'provider_unavailable'
+            : 'http_error';
+    return new ModelError('OpenAI reported a failed response.', {
         provider: 'openai',
         model: req.model,
         method,
-        reason: 'malformed_response',
-        providerBody: body
-    }, cause);
+        reason,
+        ...(providerCode ? { providerCode } : {}),
+        ...(rawMessage ? { providerMessage: sanitizeProviderMessage(rawMessage) } : {})
+    });
 }
-function safePartialJson(content) {
-    try {
-        return JSON.parse(content);
-    }
-    catch {
-        return { _partial: content };
-    }
+function parseToolArgs(argumentsText, req, method) {
+    return parseProviderJson(argumentsText || '{}', callContext(req, method), MALFORMED_TOOL_ARGS_MESSAGE);
 }
-function toUsage(inputTokens, outputTokens) {
-    const input = inputTokens ?? 0;
-    const output = outputTokens ?? 0;
-    return {
-        inputTokens: input,
-        outputTokens: output,
-        totalTokens: input + output
-    };
+function parseJson(content, req, method) {
+    return parseProviderJson(content, callContext(req, method), MALFORMED_OBJECT_MESSAGE);
 }
 function toResponsesUsage(usage) {
-    return toUsage(usage?.input_tokens, usage?.output_tokens);
+    return toTokenUsage(usage?.input_tokens, usage?.output_tokens);
 }
 function toFinishReason(value) {
     switch (value) {
@@ -661,6 +706,8 @@ function toFinishReason(value) {
         case 'tool_calls':
         case 'content_filter':
             return value;
+        case 'function_call':
+            return 'tool_calls';
         default:
             return 'error';
     }
@@ -670,6 +717,11 @@ function toResponsesFinishReason(response) {
         return 'error';
     if ((response.output ?? []).some((item) => item?.type === 'function_call'))
         return 'tool_calls';
+    const incompleteReason = response.incomplete_details?.reason;
+    if (incompleteReason === 'max_output_tokens')
+        return 'length';
+    if (incompleteReason === 'content_filter')
+        return 'content_filter';
     switch (response.status) {
         case 'completed':
             return 'stop';
@@ -679,3 +731,24 @@ function toResponsesFinishReason(response) {
             return response.error ? 'error' : 'stop';
     }
 }
+function toOutcome(finishReason, providerFinishReason, details) {
+    return {
+        finishReason,
+        ...(typeof providerFinishReason === 'string' ? { providerFinishReason } : {}),
+        ...(details ? { details } : {})
+    };
+}
+function toResponsesOutcome(response) {
+    const finishReason = toResponsesFinishReason(response);
+    const details = response?.incomplete_details || response?.error
+        ? {
+            ...(response.incomplete_details ? { incompleteDetails: response.incomplete_details } : {}),
+            ...(response.error ? { error: response.error } : {})
+        }
+        : undefined;
+    return {
+        finishReason,
+        ...(typeof response?.status === 'string' ? { providerStatus: response.status, providerFinishReason: response.status } : {}),
+        ...(details ? { details } : {})
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness-openai",
-  "version": "1.2.5",
+  "version": "1.5.0",
   "description": "OpenAI model provider adapter for @purista/harness.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
     "vitest": "^4.1.8"
   },
   "peerDependencies": {
-    "@purista/harness": "*"
+    "@purista/harness": "^1.5.0"
   },
   "engines": {
     "node": ">=24.15.0"