agent-accelerator 0.5.5 → 0.5.7

package/src/providers/openai-compat.ts

@@ -52,7 +52,6 @@ import type { ProviderContext, ContentPart } from "../types/message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "../types/tool.ts";
 import type { TokenUsage, ThinkingConfig } 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, shouldEchoSignature } from "../utils/headers.ts";
@@ -68,7 +67,14 @@ import {
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
-  hasTruncatedToolArguments,
+  hasUnfinishedToolCall,
+  linkStreamAbort,
+  withAbortTimer,
+  readSseData,
+  incompleteStreamCheck,
+  failStream,
+  toolArgumentsJson,
+  toolTurnFinishReason,
   combinedSignal,
   timeoutFor,
   hasAuthHeader,
@@ -186,10 +192,12 @@ interface ChatResponse {
 // Request building (canonical -> Chat Completions)
 // ---------------------------------------------------------------------------
 
+// Env-variable prefix of a custom provider (`my-llm` becomes `MY_LLM`); in: key and URL lookups, out: the prefix.
 function envPrefixOf(prefix: string): string {
   return prefix.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 }
 
+// Endpoint from the option, the provider's configuration or {PREFIX}_BASE_URL; throws ConfigError when none (never another vendor's URL); in: each request, out: the base URL.
 function resolveBaseUrl(
   prefix: string,
   configuredBaseUrl: string | undefined,
@@ -215,6 +223,7 @@ function resolveBaseUrl(
   return resolved.replace(/\/+$/, "");
 }
 
+// Key from the option, the provider's configuration or {PREFIX}_API_KEY, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(
   prefix: string,
   configuredApiKey: string | undefined,
@@ -276,6 +285,7 @@ function cleanModelId(prefix: string, model: string | ModelSpec): string {
   return rawId.replace(new RegExp(`^${escaped}/`, "i"), "");
 }
 
+// Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toCompatTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -303,6 +313,7 @@ function warnThinkingDropped(prefix: string, thinking: ThinkingConfig | undefine
   });
 }
 
+// `wav` or `mp3`, the only formats Chat audio input takes here; in: contentPartsToBlocks, out: input_audio.format.
 function audioFormatFor(mimeType?: string): string {
   const mime = (mimeType || "").toLowerCase();
   if (mime.includes("wav")) return "wav";
@@ -348,6 +359,7 @@ function assertNoVideoOrFileParts(
   throw err;
 }
 
+// Text, image (link or data URL) and audio parts as Chat content blocks; in: a user message's parts, out: fullHistoryMessages.
 async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPart[]> {
   const blocks: ChatContentPart[] = [];
   for (const part of parts) {
@@ -382,6 +394,7 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
   return blocks;
 }
 
+// A tool result as the text of a tool message; in: fullHistoryMessages, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
@@ -450,7 +463,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
           } = {
             id: clampToolCallId(part.callId || part.id),
             type: "function",
-            function: { name: part.name, arguments: JSON.stringify(part.arguments || {}) },
+            function: { name: part.name, arguments: toolArgumentsJson(part.arguments) },
           };
           // Echo provider-issued thought signatures verbatim so endpoints
           // that minted them (Gemini behind a compat proxy) keep working.
@@ -496,6 +509,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
 // Response mapping (Chat Completions -> canonical)
 // ---------------------------------------------------------------------------
 
+// Chat usage as TokenUsage, clamping cache reads to input; in: a reply or the last stream chunk, out: TokenUsage.
 function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
   const input = raw?.prompt_tokens ?? 0;
   const output = raw?.completion_tokens ?? 0;
@@ -511,12 +525,14 @@ function mapUsage(raw?: ChatResponse["usage"]): TokenUsage {
     cacheWriteTokens: raw?.prompt_tokens_details?.cache_write_tokens ?? 0,
     thinkingTokens: raw?.completion_tokens_details?.reasoning_tokens ?? 0,
   };
+  // `cost` is an OpenRouter extension. A generic endpoint that sends it may use 0 for "not computed", so only a positive value counts as known (OpenRouter's adapter accepts an explicit 0).
   if (typeof raw?.cost === "number" && raw.cost > 0) {
     usage.cost = { totalCost: raw.cost };
   }
   return usage;
 }
 
+// The Gemini thought signature a proxy put on a tool call, if any; in: parseResponse, out: a string or undefined.
 function extractSignature(rawTc: {
   extra_content?: { google?: { thought_signature?: string } };
 }): string | undefined {
@@ -530,6 +546,7 @@ function withCompatSignature(sig: string | undefined): { thoughtSignature?: stri
   return { thoughtSignature: sig, thoughtSignatureProvider: "google" };
 }
 
+// Throws a concise error for an HTTP 200 reply that carries only `error`; in: parseResponse, out: a thrown error.
 function throwResponseError(
   response: ChatResponse,
   prefix: string,
@@ -544,6 +561,7 @@ function throwResponseError(
   throw toConciseProviderError(failure, prefix, modelId);
 }
 
+// Turns a Chat Completions JSON reply into text, thinking, tool calls and usage; in: generate, out: ProviderGenerateResult.
 function parseResponse(
   response: ChatResponse,
   prefix: string,
@@ -658,6 +676,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     this.configuredApiKey = opts?.apiKey;
   }
 
+  // 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(this.prefix, modelId);
     return (
@@ -668,14 +687,17 @@ export class OpenAICompatibleChatProvider implements Provider {
     );
   }
 
+  // This provider's endpoint for one request; in: generate/stream, out: resolveBaseUrl.
   private baseUrl(options?: ProviderRequestOptions): string {
     return resolveBaseUrl(this.prefix, this.configuredBaseUrl, options);
   }
 
+  // This provider's key for one request; in: requireApiKey, out: resolveApiKey.
   private apiKey(options?: ProviderRequestOptions): string | undefined {
     return resolveApiKey(this.prefix, this.configuredApiKey, options);
   }
 
+  // The key, where a missing one only throws for non-local endpoints (loopback and LAN may omit it); in: generate/stream, out: the key or undefined.
   private requireApiKey(baseUrl: string, options?: ProviderRequestOptions): string | undefined {
     const key = this.apiKey(options);
     if (!key && !isLocalEndpoint(baseUrl)) {
@@ -686,6 +708,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     return key;
   }
 
+  // Builds the Chat request (messages, tools, tool_choice, generation controls, response_format, stream usage) and warns+drops what a strict endpoint cannot take; in: generate/stream, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -741,7 +764,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     const compatTools = toCompatTools(tools);
     if (compatTools) body.tools = compatTools;
     // Standard Chat Completions generation fields, only when the caller set them.
-    Object.assign(body, mapGenerationParamsToChat(options));
+    Object.assign(body, mapGenerationParamsToChat(options, this.prefix, `${this.prefix}/${modelId}`));
     const toolChoice = mapToolChoiceToOpenAI(
       options?.toolChoice as "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
     );
@@ -782,6 +805,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session-affinity headers (unless opted out), JSON content type and the Bearer key; in: doFetch and stream, out: RequestInit.
   private requestInit(
     body: ChatRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -817,6 +841,7 @@ export class OpenAICompatibleChatProvider 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: ChatRequestBody,
@@ -839,6 +864,7 @@ export class OpenAICompatibleChatProvider 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,
@@ -867,6 +893,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     throw toConciseProviderError(err, this.prefix, modelId);
   }
 
+  // Non-streaming turn as one retried JSON request; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -939,6 +966,7 @@ export class OpenAICompatibleChatProvider 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,
@@ -949,23 +977,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     const prefix = this.prefix;
     const clean = cleanModelId(this.prefix, 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 {
@@ -994,21 +1006,7 @@ export class OpenAICompatibleChatProvider 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-compatible streaming response had no body"), prefix, clean),
           retry: retryOptionsFrom(options),
@@ -1022,9 +1020,6 @@ export class OpenAICompatibleChatProvider 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 choice index: { id, name, startArgs, deltaArgs }.
@@ -1040,18 +1035,6 @@ export class OpenAICompatibleChatProvider 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) return;
           if (data === "[DONE]") {
@@ -1176,26 +1159,7 @@ export class OpenAICompatibleChatProvider 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 [index, c] of calls) {
@@ -1212,9 +1176,11 @@ export class OpenAICompatibleChatProvider 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, prefix);
         if (toolCalls.length > 0) {
-          finishReason = "tool_calls";
+          finishReason = toolTurnFinishReason(finishReason, toolCalls);
           sawFinishReason = true;
         } else if (refusalSeen) {
           finishReason = "refusal";
@@ -1224,26 +1190,21 @@ export class OpenAICompatibleChatProvider implements Provider {
         // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
-        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(prefix, 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(prefix, clean));
+        const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        const incomplete = incompleteStreamCheck({
+          provider: prefix,
+          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 finalThoughtSignature = toolCalls.map((c) => c.thoughtSignature).find(Boolean);
         const finalResponse = new AgentResponse({
           text,
@@ -1264,21 +1225,9 @@ export class OpenAICompatibleChatProvider 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();
       }
     })();