agent-accelerator 0.5.5 → 0.5.7

package/src/providers/openai.ts

@@ -44,7 +44,6 @@ import type { ProviderContext, ContentPart } from "../types/message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "../types/tool.ts";
 import type { TokenUsage } from "../types/core.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
-import { SSEParser } from "../streaming/sse-parser.ts";
 import { AgentResponse } from "../types/response.ts";
 import { getApiKey, getEnv } from "../utils/env.ts";
 import { buildSessionHeaders, setHeaderCaseInsensitive } from "../utils/headers.ts";
@@ -60,7 +59,14 @@ import {
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
-  hasTruncatedToolArguments,
+  hasUnfinishedToolCall,
+  linkStreamAbort,
+  withAbortTimer,
+  readSseData,
+  incompleteStreamCheck,
+  failStream,
+  toolArgumentsJson,
+  toolTurnFinishReason,
   combinedSignal,
   timeoutFor,
   hasAuthHeader,
@@ -161,6 +167,7 @@ const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 // Request building (canonical -> Responses)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, OPENAI_BASE_URL/OPENAI_API_BASE, else api.openai.com; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -172,6 +179,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// Key from the option or env, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
   const key = getApiKey("openai", options?.apiKey, options?.env);
   if (key) return key;
@@ -185,6 +193,7 @@ function cleanModelId(model: string | ModelSpec): string {
   return rawId.replace(/^openai\//i, "");
 }
 
+// Canonical tool declarations as Responses function tools; in: options.tools, out: request `tools`.
 function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -196,6 +205,7 @@ function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string,
   }));
 }
 
+// Text and media parts as input_text, input_image and input_file blocks; web links pass through, the rest is inlined as data URLs; in: a user message's parts, out: fullHistoryInput.
 async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseContentPart[]> {
   const blocks: ResponseContentPart[] = [];
   for (const part of parts) {
@@ -252,17 +262,20 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseConte
   return blocks;
 }
 
+// A tool result as the text of a function_call_output item; in: fullHistoryInput, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
 }
 
+// Makes an id safe for the Responses wire (allowed characters, at most 64, no trailing underscores); in: fullHistoryInput, out: the id.
 function normalizeResponsesIdPart(part: string): string {
   const sanitized = String(part ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
   const truncated = sanitized.length > 64 ? sanitized.slice(0, 64) : sanitized;
   return truncated.replace(/_+$/, "") || "fc_unknown";
 }
 
+// Gives a function-call item id the required `fc_` prefix; in: fullHistoryInput, out: the id.
 function normalizeResponsesItemId(itemId: string): string {
   let norm = normalizeResponsesIdPart(itemId);
   if (!norm.startsWith("fc_")) {
@@ -340,7 +353,7 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
             id: normalizeResponsesItemId(itemId),
             call_id: normalizeResponsesIdPart(callId),
             name: part.name,
-            arguments: JSON.stringify(part.arguments || {}),
+            arguments: toolArgumentsJson(part.arguments),
           });
         } else if (part.type === "text" && part.text) {
           texts.push(part.text);
@@ -384,6 +397,7 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
 // Response mapping (Responses -> canonical)
 // ---------------------------------------------------------------------------
 
+// Responses usage as TokenUsage, clamping cache reads to input; in: a response or the completed event, out: TokenUsage.
 function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   const input = raw?.input_tokens ?? 0;
   const output = raw?.output_tokens ?? 0;
@@ -400,6 +414,7 @@ function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   };
 }
 
+// Turns a Responses object into text, reasoning, tool calls and usage, mapping refusals and incomplete to finish reasons and throwing on failed; in: generate, out: ProviderGenerateResult.
 function parseResponse(
   response: ResponsesObject,
   modelId: string,
@@ -503,6 +518,7 @@ export class OpenAIResponsesProvider implements Provider {
     return getModelsForProvider("openai");
   }
 
+  // The catalog spec of a model, else a permissive generic one; in: the registry, out: a ModelSpec.
   getModel(modelId: string): ModelSpec | undefined {
     const clean = cleanModelId(modelId);
     return (
@@ -513,6 +529,7 @@ export class OpenAIResponsesProvider implements Provider {
     );
   }
 
+  // Builds the stateless Responses request (full history, store:false, tools, reasoning, tier, text.format, cache key and retention); in: generate/stream, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -614,6 +631,7 @@ export class OpenAIResponsesProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session-affinity headers, JSON content type and the Bearer key; in: doFetch and stream, out: RequestInit.
   private requestInit(
     body: ResponsesRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -634,6 +652,7 @@ export class OpenAIResponsesProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
+  // One HTTP call under the request timeout, returning status, headers and body text; in: generate, out: the raw reply.
   private async doFetch(
     url: string,
     body: ResponsesRequestBody,
@@ -656,6 +675,7 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key hint) for a non-2xx reply; in: generate and stream, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     url: string,
@@ -686,6 +706,7 @@ export class OpenAIResponsesProvider implements Provider {
     throw toConciseProviderError(err, "openai", modelId);
   }
 
+  // Non-streaming turn as one retried JSON request; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -767,6 +788,7 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
+  // Streaming turn over SSE: assembles text, reasoning, tool calls and usage, retrying only before the first byte; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -776,23 +798,7 @@ export class OpenAIResponsesProvider implements Provider {
     const startTime = Date.now();
     const clean = cleanModelId(model);
 
-    const linked = new AbortController();
-    const forwardUserAbort = () => {
-      try {
-        linked.abort((options?.signal as { reason?: unknown })?.reason);
-      } catch {
-        try {
-          linked.abort();
-        } catch {}
-      }
-    };
-    if (options?.signal?.aborted) forwardUserAbort();
-    else options?.signal?.addEventListener("abort", forwardUserAbort, { once: true });
-    const removeStreamCancel = eventStream.onCancel(() => {
-      try {
-        linked.abort();
-      } catch {}
-    });
+    const { linked, release } = linkStreamAbort(eventStream, options?.signal);
 
     (async () => {
       try {
@@ -803,7 +809,7 @@ export class OpenAIResponsesProvider implements Provider {
           );
         }
         assertModalitiesSupported(context, "openai", clean);
-    assertNoVideoPartsOnResponses(context, "openai", clean);
+        assertNoVideoPartsOnResponses(context, "openai", clean);
         const baseUrl = resolveBaseUrl(options);
         const url = `${baseUrl}/responses`;
         const sessionId = options?.sessionId;
@@ -827,21 +833,7 @@ export class OpenAIResponsesProvider implements Provider {
         // Transient failures (429/5xx/network) are retried here, before the
         // first byte; once the stream is live it is never retried.
         const res = await openStreamResponse({
-          fetchOnce: async () => {
-            const timer =
-              streamTimeoutMs && streamTimeoutMs > 0
-                ? setTimeout(() => {
-                    try {
-                      linked.abort();
-                    } catch {}
-                  }, streamTimeoutMs)
-                : undefined;
-            try {
-              return await (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, linked.signal));
-            } finally {
-              if (timer) clearTimeout(timer);
-            }
-          },
+          fetchOnce: () => withAbortTimer(linked, streamTimeoutMs, () => (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, linked.signal))),
           onHttpError: (r, text) => this.throwIfError(r.status, url, text, clean, headersToRecord(r.headers)),
           noBodyError: () => toConciseProviderError(new Error("OpenAI streaming response had no body"), "openai", clean),
           retry: retryOptionsFrom(options),
@@ -855,9 +847,6 @@ export class OpenAIResponsesProvider implements Provider {
         const responseMeta: Record<string, unknown> & { status: number; statusText: string; headers: Record<string, string> } = { status: res.status, statusText: res.statusText, headers: responseHeaders };
         eventStream.push({ type: "start", raw: { request: rawRequest } } as never);
 
-        const parser = new SSEParser();
-        const reader = res.body!.getReader(); // openStreamResponse guarantees a body
-        const decoder = new TextDecoder();
         let text = "";
         let thinking = "";
         // Tool calls keyed by output_index: { itemId, callId, name, startArgs, deltaArgs }.
@@ -871,18 +860,6 @@ export class OpenAIResponsesProvider implements Provider {
         let framesSeen = 0;
         let responseId: string | undefined;
         let completedBody: unknown = undefined;
-        let aborted = false;
-        linked.signal.addEventListener(
-          "abort",
-          () => {
-            aborted = true;
-            try {
-              void reader.cancel();
-            } catch {}
-          },
-          { once: true }
-        );
-
         const handleMessage = (data: string): void => {
           if (!data || data === "[DONE]") {
             if (data === "[DONE]") sawFinishReason = sawFinishReason || completedBody !== undefined || sawUsage;
@@ -1035,26 +1012,7 @@ export class OpenAIResponsesProvider implements Provider {
           }
         };
 
-        while (true) {
-          if (linked.signal.aborted || eventStream.isCancelled()) {
-            try {
-              await reader.cancel();
-            } catch {}
-            throw Object.assign(new Error("Stream aborted"), { name: "AbortError" });
-          }
-          const { done, value } = await reader.read();
-          if (done) break;
-          const chunk = decoder.decode(value, { stream: true });
-          for (const m of parser.feed(chunk)) handleMessage(m.data);
-        }
-        for (const m of parser.flush()) handleMessage(m.data);
-        try {
-          reader.releaseLock();
-        } catch {}
-
-        if (linked.signal.aborted || eventStream.isCancelled() || aborted) {
-          throw Object.assign(new Error("Stream aborted"), { name: "AbortError" });
-        }
+        await readSseData(res.body!, linked, eventStream, handleMessage); // openStreamResponse guarantees a body
 
         const toolCalls: ToolCallRecord[] = [];
         for (const c of calls.values()) {
@@ -1070,9 +1028,11 @@ export class OpenAIResponsesProvider implements Provider {
           eventStream.push({ type: "tool_call_complete", toolCall: record });
         }
 
+        // Did the stream really end? Read before the tool-call and refusal overrides below, which also set sawFinishReason.
+        const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
         noteProviderTurn(sessionId, "openai");
         if (toolCalls.length > 0) {
-          finishReason = "tool_calls";
+          finishReason = toolTurnFinishReason(finishReason, toolCalls);
           sawFinishReason = true;
         } else if (refusalSeen && finishReason !== "length") {
           finishReason = "refusal";
@@ -1085,26 +1045,21 @@ export class OpenAIResponsesProvider implements Provider {
         // Skipped for non-SSE payloads (e.g. JSON mocks in delegation tests)
         // where no SSE frames were ever seen — those preserve legacy empty
         // success rather than failing the caller on a mock artifact.
-        const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
-        const cleanThinkingEarly = thinking.replace(/\n{3,}/g, "\n\n").trim();
-        const ctEntry = Object.entries(responseHeaders).find(([k]) => k.toLowerCase() === "content-type");
-        const isSSEPayload =
-          (typeof ctEntry?.[1] === "string" && ((ctEntry[1] as string).includes("event-stream") || (ctEntry[1] as string).startsWith("text/"))) ||
-          framesSeen > 0 ||
-          badFrames > 0;
-        if (!hasTerminal && !text && !cleanThinkingEarly && toolCalls.length === 0 && isSSEPayload) {
-          eventStream.fail(incompleteStreamError("openai", clean));
-          return;
-        }
-        // Refuse unfinished tool calls whose args never parsed (output_item.done
-        // never arrived): truncated `{raw}` must not reach the executor (pi
-        // api/openai-responses-shared.ts:766 rule). Non-SSE mocks preserve legacy.
-        if (!hasTerminal && toolCalls.some((c) => hasTruncatedToolArguments(c.arguments)) && isSSEPayload) {
-          eventStream.fail(incompleteStreamError("openai", clean));
+        const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        const incomplete = incompleteStreamCheck({
+          provider: "openai",
+          modelId: clean,
+          hasTerminal,
+          empty: !text && !cleanThinking && toolCalls.length === 0,
+          unfinishedCall: hasUnfinishedToolCall(calls.values(), toolCalls),
+          responseHeaders,
+          framesSeen,
+          badFrames,
+        });
+        if (incomplete) {
+          eventStream.fail(incomplete);
           return;
         }
-
-        const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({
           text,
           thinking: cleanThinking || undefined,
@@ -1124,21 +1079,9 @@ export class OpenAIResponsesProvider implements Provider {
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });
         eventStream.end(finalResponse);
       } catch (err: unknown) {
-        const raw = err instanceof Error ? err : new Error(String(err));
-        const isAbort =
-          linked.signal.aborted ||
-          eventStream.isCancelled() ||
-          (raw as { name?: string }).name === "AbortError";
-        eventStream.fail(
-          isAbort ? Object.assign(new Error("Stream aborted"), { name: "AbortError" }) : raw
-        );
+        failStream(eventStream, linked, err);
       } finally {
-        try {
-          options?.signal?.removeEventListener("abort", forwardUserAbort);
-        } catch {}
-        try {
-          removeStreamCancel();
-        } catch {}
+        release();
       }
     })();