@purista/harness-openai 1.2.6 → 1.5.0

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,21 +93,23 @@ 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);
@@ -114,6 +119,7 @@ class OpenAiModelProvider extends BaseModelProvider {
                 ...(providerItems ? { providerItems } : {}),
                 usage: toResponsesUsage(response.usage),
                 finishReason: toResponsesFinishReason(response),
+                outcome: toResponsesOutcome(response),
                 raw: response
             };
         }
@@ -123,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
         };
     }
@@ -133,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;
@@ -142,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)
@@ -152,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();
@@ -178,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
     };
 }
@@ -463,6 +475,7 @@ function mapResponsesTextResponse(response, req) {
         ...(providerItems ? { providerItems } : {}),
         usage: toResponsesUsage(response.usage),
         finishReason: toResponsesFinishReason(response),
+        outcome: toResponsesOutcome(response),
         raw: response
     };
 }
@@ -484,6 +497,7 @@ 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) {
@@ -503,10 +517,18 @@ 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' || 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, 'textStream');
+        }
+        else if (event.type === 'response.incomplete') {
+            usage = toResponsesUsage(event.response?.usage);
+            finishReason = toResponsesFinishReason(event.response);
+            outcome = toResponsesOutcome(event.response);
         }
     }
     const toolCalls = finalizeResponsesStreamToolCalls(toolState, req, 'textStream');
@@ -514,13 +536,14 @@ async function* streamResponsesText(client, req) {
         yield { kind: 'tool_call', call };
     }
     const providerItems = toResponsesProviderItems(completedOutput, toolCalls);
-    yield { kind: 'finish', usage, finishReason, ...(providerItems ? { providerItems } : {}) };
+    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) {
@@ -541,10 +564,18 @@ 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);
         }
     }
     const toolCalls = finalizeResponsesStreamToolCalls(toolState, req, 'objectStream');
@@ -553,7 +584,7 @@ async function* streamResponsesObject(client, req) {
     }
     const object = parseJson(partial || '{}', req, 'objectStream');
     const providerItems = toResponsesProviderItems(completedOutput, toolCalls);
-    yield { kind: 'finish', object, usage, finishReason, ...(providerItems ? { providerItems } : {}) };
+    yield { kind: 'finish', object, usage, finishReason, outcome, ...(providerItems ? { providerItems } : {}) };
 }
 function extractResponsesText(response) {
     if (typeof response.output_text === 'string')
@@ -618,7 +649,7 @@ function finalizeResponsesStreamToolCalls(state, req, method) {
         .filter(([, call]) => call.name)
         .map(([, call]) => {
         if (!call.id) {
-            throw malformedResponseError(req, method, 'OpenAI streamed a function call without a call_id.', call, undefined);
+            throw malformedResponseError(callContext(req, method), 'OpenAI streamed a function call without a call_id.', call, undefined);
         }
         return {
             id: call.id,
@@ -627,75 +658,46 @@ function finalizeResponsesStreamToolCalls(state, 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);
-    }
+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 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)
-    }));
-}
-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);
-    }
-}
-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) {
@@ -704,6 +706,8 @@ function toFinishReason(value) {
         case 'tool_calls':
         case 'content_filter':
             return value;
+        case 'function_call':
+            return 'tool_calls';
         default:
             return 'error';
     }
@@ -713,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';
@@ -722,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.6",
+  "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"