agent-accelerator 0.4.0 → 0.5.0

package/src/providers/openai-compat.ts

@@ -12,7 +12,8 @@
  *
  * Strictness contract (differs from the old lenient passthrough on purpose):
  * - Requests carry ONLY standard Chat Completions fields (`model`, `messages`,
- *   `tools`, `tool_choice`, `stream`). No `reasoning`, `service_tier`,
+ *   `tools`, `tool_choice`, `stream`, plus `max_tokens`/
+ *   `stop`/`seed` when explicitly set). No `reasoning`, `service_tier`,
  *   `session_id`, `prompt_cache_key`, or other extras: strict endpoints
  *   (groq, ollama, …) fail unknown body properties, so anything unsupported
  *   is warn+drop, never sent.
@@ -60,6 +61,7 @@ import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
 import { withRetries } from "../utils/retry.ts";
+import { ConfigError } from "../types/errors.ts";
 import {
   parseArguments,
   normalizeThinkingParts,
@@ -67,16 +69,28 @@ import {
   redactedHeaders,
   readErrorPayload,
   incompleteStreamError,
+  hasTruncatedToolArguments,
   combinedSignal,
   timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
+  openStreamResponse,
+  retryOptionsFrom,
+  headersToRecord,
+  parseRetryAfterMs,
 } from "./shared.ts";
-import { getModelFromCatalog, createGenericModelSpec } from "../models/catalog.ts";
+import { getModelFromCatalog, createGenericModelSpec, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   applyCacheForCustom,
   mapToolChoiceToOpenAI,
   emitProviderWarning,
   noteProviderTurn,
   parseStreamedToolArguments,
+  selectRawArguments,
+  mapOutputToCompatChat,
+  mapGenerationParamsToChat,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -110,6 +124,7 @@ interface ChatRequestBody {
   messages: ChatMessage[];
   tools?: Array<Record<string, unknown>>;
   tool_choice?: string | { type: "function"; function: { name: string } };
+  response_format?: { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
   stream?: boolean;
   [k: string]: unknown;
 }
@@ -167,8 +182,6 @@ interface ChatResponse {
   [k: string]: unknown;
 }
 
-const DEFAULT_BASE_URL = "https://api.openai.com/v1";
-
 /** Headers that must never leak onto native REST requests. */
 const INTERNAL_HEADERS = new Set([
   "x-thought-signature-map",
@@ -190,7 +203,7 @@ function resolveBaseUrl(
   options?: ProviderRequestOptions
 ): string {
   const envPrefix = envPrefixOf(prefix);
-  return (
+  const resolved =
     options?.baseUrl ||
     configuredBaseUrl ||
     options?.env?.[`${envPrefix}_BASE_URL`] ||
@@ -198,9 +211,15 @@ function resolveBaseUrl(
     options?.env?.[`${envPrefix}_API_BASE`] ||
     getEnv(`${envPrefix}_BASE_URL`) ||
     getEnv(`${envPrefix}_BASEURL`) ||
-    getEnv(`${envPrefix}_API_BASE`) ||
-    DEFAULT_BASE_URL
-  ).replace(/\/+$/, "");
+    getEnv(`${envPrefix}_API_BASE`);
+  // Never fall back to another vendor's cloud: a custom prefix's API key
+  // must only ever travel to the endpoint the developer named.
+  if (!resolved) {
+    throw new ConfigError(
+      `[Agent Accelerator] Missing base URL for "${prefix}". Set ${envPrefix}_BASE_URL (or pass baseUrl); custom endpoints never default to api.openai.com.`
+    );
+  }
+  return resolved.replace(/\/+$/, "");
 }
 
 function resolveApiKey(
@@ -208,17 +227,23 @@ function resolveApiKey(
   configuredApiKey: string | undefined,
   options?: ProviderRequestOptions
 ): string | undefined {
+  const clean = (v: unknown): string | undefined => {
+    if (typeof v !== "string") return undefined;
+    const t = v.trim().replace(/^["']|["']$/g, "").trim();
+    return t || undefined;
+  };
   const envPrefix = envPrefixOf(prefix);
-  return (
-    options?.apiKey ||
-    configuredApiKey ||
-    options?.env?.[`${envPrefix}_API_KEY`] ||
-    options?.env?.[`${envPrefix}_BASE_API_KEY`] ||
-    getEnv(`${envPrefix}_API_KEY`) ||
-    getEnv(`${envPrefix}_BASE_API_KEY`) ||
+  const key = (
+    clean(options?.apiKey) ||
+    clean(configuredApiKey) ||
+    clean(options?.env?.[`${envPrefix}_API_KEY`]) ||
+    clean(options?.env?.[`${envPrefix}_BASE_API_KEY`]) ||
     getApiKey(prefix, undefined, options?.env) ||
     undefined
   );
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 /** Local endpoints (loopback / LAN / *.local) may omit the API key. Literal IPs only; hostnames like 10.evil.com are not local. */
@@ -395,14 +420,18 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
   if (context.systemPrompt) {
     messages.push({ role: "system", content: context.systemPrompt });
   }
+  let lastRole: string | null = "system";
   for (const m of context.messages) {
     if (m.role === "system") continue;
     if (m.role === "user") {
+      if (lastRole === "tool") {
+        messages.push({ role: "assistant", content: "I have processed the tool results." });
+      }
       if (typeof m.content === "string") {
-        if (m.content) messages.push({ role: "user", content: m.content });
+        if (m.content) { messages.push({ role: "user", content: m.content }); lastRole = "user"; }
       } else {
         const blocks = await contentPartsToBlocks(m.content);
-        if (blocks.length > 0) messages.push({ role: "user", content: blocks });
+        if (blocks.length > 0) { messages.push({ role: "user", content: blocks }); lastRole = "user"; }
       }
     } else if (m.role === "assistant") {
       if (typeof m.content === "string") {
@@ -426,7 +455,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
             function: { name: string; arguments: string };
             extra_content?: { google: { thought_signature: string } };
           } = {
-            id: part.callId || part.id,
+            id: clampToolCallId(part.callId || part.id),
             type: "function",
             function: { name: part.name, arguments: JSON.stringify(part.arguments || {}) },
           };
@@ -443,21 +472,26 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
           texts.push(part.text);
         }
       }
+      // Skip empty assistant turns (no text + no tool calls): strict
+      // routes reject them, and they carry no signal (pi drop rule).
+      if (texts.length === 0 && calls.length === 0) continue;
       messages.push({
         role: "assistant",
         content: texts.length > 0 ? texts.join("\n") : null,
         ...(calls.length > 0 ? { tool_calls: calls } : {}),
       });
+      lastRole = "assistant";
     } else if (m.role === "tool") {
       if (!Array.isArray(m.content)) continue;
       for (const part of m.content) {
         if (part.type === "tool_result") {
           messages.push({
             role: "tool",
-            tool_call_id: pairing.get(part.id) || part.id,
+            tool_call_id: clampToolCallId(pairing.get(part.id) || part.id),
             content: resultToOutput(part.result),
             name: part.name,
           });
+          lastRole = "tool";
         }
       }
     }
@@ -551,7 +585,7 @@ function parseResponse(
     const args = parseArguments(tc.function?.arguments);
     const sig = extractSignature(tc);
     toolCalls.push({
-      id: tc.id || newToolCallId(),
+      id: tc.id && !tc.id.includes("|") && tc.id.length <= 40 ? tc.id : clampToolCallId(tc.id || newToolCallId()),
       name: tc.function?.name || "unknown",
       arguments: args,
       rawArguments:
@@ -590,7 +624,7 @@ export interface CustomProviderOptions {
   baseUrl?: string;
   /** Static apiKey — overrides env. Explicit per-call `apiKey` still wins. */
   apiKey?: string;
-  /** Default baseUrl when no env is set. Defaults to OpenAI cloud. */
+  /** Default baseUrl when no env is set. There is no implicit default: without one the request fails fast. */
   defaultBaseUrl?: string;
 }
 
@@ -678,7 +712,32 @@ export class OpenAICompatibleChatProvider implements Provider {
     }
     applyCacheForCustom(this.prefix, options?.cache, `${this.prefix}/${modelId}`);
 
-    const messages = await fullHistoryMessages(context);
+    // Structured outputs: native `response_format` when supported, else
+    // emulated via system prompt (strict endpoints would 400 on json_schema
+    // for catalog `structured_output: false` models).
+    let effectiveContext = context;
+    let outputEmulated = false;
+    let outputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+    try {
+      outputSpec = normalizeStructuredOutput(options?.output ?? (options as { outputSchema?: unknown })?.outputSchema);
+    } catch {
+      outputSpec = undefined;
+    }
+    if (outputSpec && !modelSupportsStructuredOutput(this.prefix, modelId)) {
+      outputEmulated = true;
+      effectiveContext = {
+        ...context,
+        systemPrompt: augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec),
+      };
+      emitProviderWarning({
+        provider: this.prefix,
+        capability: "structured output",
+        requested: `${outputSpec.name} (${this.prefix}/${modelId})`,
+        reason: "the catalog reports structured_output: false for this model, so native response_format is unsupported.",
+        fallback: "emulated JSON instruction + client validation (no response_format is sent)",
+      });
+    }
+    const messages = await fullHistoryMessages(effectiveContext);
     const body: ChatRequestBody = {
       model: modelId,
       messages,
@@ -686,6 +745,8 @@ 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));
     const toolChoice = mapToolChoiceToOpenAI(
       options?.toolChoice as "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
     );
@@ -697,8 +758,19 @@ export class OpenAICompatibleChatProvider implements Provider {
           ? { type: "function", function: { name: (toolChoice as { name: string }).name } }
           : (toolChoice as ChatRequestBody["tool_choice"]);
     }
-    // No reasoning / service_tier / session / cache body primitives: strict
-    // endpoints reject unknown properties. Affinity is headers-only.
+    // Structured outputs use the standard Chat Completions `response_format`
+    // (safe on strict endpoints). Skipped when emulated (instruction already
+    // in messages). No reasoning / service_tier / session /
+    // cache body primitives: strict endpoints reject unknown properties.
+    // Affinity stays headers-only.
+    if (outputSpec && !outputEmulated) {
+      try {
+        const mapped = mapOutputToCompatChat(outputSpec);
+        if (mapped) body.response_format = mapped.response_format;
+      } catch {
+        // why: invalid output shapes fail fast at Agent construction/loop validation.
+      }
+    }
     // Q-38: request usage on streams where supported so terminal accounting
     // arrives on the final chunk. Strict servers that reject unknown fields
     // opt out via `COMPAT_NO_STREAM_OPTIONS=1`; an explicit per-call
@@ -731,8 +803,26 @@ export class OpenAICompatibleChatProvider implements Provider {
     for (const [k, v] of Object.entries(headers)) {
       if (INTERNAL_HEADERS.has(k.toLowerCase())) delete headers[k];
     }
+    // Strict-endpoint opt-out (pi sendSessionAffinityHeaders pattern):
+    // `COMPAT_NO_SESSION_HEADERS=1` or per-call `sendSessionHeaders:false`
+    // drops affinity headers that trigger CORS preflights / strict 400s.
+    // Body `session_id` is already omitted on compat (headers-only affinity).
+    try {
+      const noAffinity =
+        (options as { sendSessionHeaders?: unknown } | undefined)?.sendSessionHeaders === false ||
+        getEnv("COMPAT_NO_SESSION_HEADERS") === "1" ||
+        options?.env?.["COMPAT_NO_SESSION_HEADERS"] === "1";
+      if (noAffinity) {
+        for (const k of Object.keys(headers)) {
+          const lower = k.toLowerCase();
+          if (lower === "x-session-id" || lower === "x-client-request-id" || lower === "session_id") {
+            delete headers[k];
+          }
+        }
+      }
+    } catch {}
     setHeaderCaseInsensitive(headers, "Content-Type", "application/json");
-    if (apiKey) setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
+    if (apiKey && apiKey !== "unused") setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -746,7 +836,7 @@ export class OpenAICompatibleChatProvider implements Provider {
   ): Promise<{ status: number; statusText: string; headers: Record<string, string>; text: string }> {
     const { signal: effective, cleanup } = combinedSignal(signal, timeoutFor(options as { timeoutMs?: number } | undefined));
     try {
-      const res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, effective));
+      const res = await (options?.fetch ?? fetch)(url, this.requestInit(body, options, apiKey, sessionId, effective));
       const text = await res.text();
       const headers: Record<string, string> = {};
       res.headers.forEach((v, k) => {
@@ -762,17 +852,27 @@ export class OpenAICompatibleChatProvider implements Provider {
     status: number,
     url: string,
     bodyText: string,
-    modelId: string
+    modelId: string,
+    headers?: Record<string, string>
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code, errorType } = readErrorPayload(bodyText);
-    const err: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
+    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const hint =
+      status === 401
+        ? ` Check ${envPrefixOf(this.prefix)}_API_KEY (no quotes/spaces, correct provider) and that the key is loaded (bun --env-file=.env.local).`
+        : "";
+    const fullMessage = `${message}${hint}`;
+    const err: Record<string, unknown> & Error = new Error(fullMessage) as Record<string, unknown> & Error;
     (err as Record<string, unknown>)["statusCode"] = status;
     (err as Record<string, unknown>)["status"] = status;
     (err as Record<string, unknown>)["responseBody"] = bodyText.slice(0, 500);
     (err as Record<string, unknown>)["url"] = url.split("?")[0];
+    (err as Record<string, unknown>)["data"] = { error: { message: fullMessage } };
     if (code !== undefined) (err as Record<string, unknown>)["code"] = code;
     if (errorType) (err as Record<string, unknown>)["errorType"] = errorType;
+    if (raw) (err as Record<string, unknown>)["raw"] = raw;
+    const retryAfterMs = parseRetryAfterMs(headers);
+    if (retryAfterMs !== undefined) (err as Record<string, unknown>)["retryAfterMs"] = retryAfterMs;
     throw toConciseProviderError(err, this.prefix, modelId);
   }
 
@@ -783,13 +883,13 @@ export class OpenAICompatibleChatProvider implements Provider {
   ): Promise<ProviderGenerateResult> {
     const startTime = Date.now();
     const clean = cleanModelId(this.prefix, model);
-    const baseUrl = this.baseUrl(options);
-    const apiKey = this.requireApiKey(baseUrl, options);
     // Fail fast before any network call when the catalog knows the model
     // lacks the requested modality. Unknown models skip the guard; the
-    // endpoint verdict surfaces concisely.
+    // endpoint verdict surfaces concisely. Cheap local checks run first.
     assertModalitiesSupported(context, this.prefix, clean);
     assertNoVideoOrFileParts(context, this.prefix, clean);
+    const baseUrl = this.baseUrl(options);
+    const apiKey = this.requireApiKey(baseUrl, options);
     const url = `${baseUrl}/chat/completions`;
     const sessionId = options?.sessionId || options?.cache?.sessionId;
     const tools = options?.tools as StandardToolDeclaration[] | undefined;
@@ -812,7 +912,7 @@ export class OpenAICompatibleChatProvider implements Provider {
 
     const doCall = async (): Promise<ProviderGenerateResult> => {
       const res = await this.doFetch(url, body, options, apiKey, sessionId, options?.signal);
-      this.throwIfError(res.status, url, res.text, clean);
+      this.throwIfError(res.status, url, res.text, clean, res.headers);
       let response: ChatResponse;
       try {
         response = JSON.parse(res.text) as ChatResponse;
@@ -841,8 +941,7 @@ export class OpenAICompatibleChatProvider implements Provider {
 
     try {
       return await withRetries(doCall, {
-        maxRetries: options?.maxRetries,
-        maxRetryDelayMs: options?.maxRetryDelayMs,
+        ...retryOptionsFrom(options),
         signal: options?.signal,
         label: { providerId: this.prefix, modelId: clean },
       });
@@ -882,10 +981,10 @@ export class OpenAICompatibleChatProvider implements Provider {
 
     (async () => {
       try {
-        const baseUrl = this.baseUrl(options);
-        const apiKey = this.requireApiKey(baseUrl, options);
         assertModalitiesSupported(context, prefix, clean);
         assertNoVideoOrFileParts(context, prefix, clean);
+        const baseUrl = this.baseUrl(options);
+        const apiKey = this.requireApiKey(baseUrl, options);
         const url = `${baseUrl}/chat/completions`;
         const sessionId = options?.sessionId || options?.cache?.sessionId;
         const tools = options?.tools as StandardToolDeclaration[] | undefined;
@@ -907,25 +1006,30 @@ export class OpenAICompatibleChatProvider implements Provider {
         };
 
         const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
-        const streamTimeoutTimer =
-          streamTimeoutMs && streamTimeoutMs > 0
-            ? setTimeout(() => {
-                try {
-                  linked.abort();
-                } catch {}
-              }, streamTimeoutMs)
-            : undefined;
-        let res: Response;
-        try {
-          res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, linked.signal));
-        } finally {
-          if (streamTimeoutTimer) clearTimeout(streamTimeoutTimer);
-        }
-        if (!res.ok || !res.body) {
-          const text = !res.ok ? await res.text().catch(() => "") : "";
-          if (!res.ok) this.throwIfError(res.status, url, text, clean);
-          throw toConciseProviderError(new Error("OpenAI-compatible streaming response had no body"), prefix, clean);
-        }
+        // 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);
+            }
+          },
+          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),
+          signal: linked.signal,
+          label: { providerId: prefix, modelId: clean },
+        });
         const responseHeaders: Record<string, string> = {};
         res.headers.forEach((v, k) => {
           responseHeaders[k] = v;
@@ -934,7 +1038,7 @@ export class OpenAICompatibleChatProvider implements Provider {
         eventStream.push({ type: "start", raw: { request: rawRequest } } as never);
 
         const parser = new SSEParser();
-        const reader = res.body.getReader();
+        const reader = res.body!.getReader(); // openStreamResponse guarantees a body
         const decoder = new TextDecoder();
         let text = "";
         let thinking = "";
@@ -1113,10 +1217,10 @@ export class OpenAICompatibleChatProvider implements Provider {
           const args = parseStreamedToolArguments(c.startArgs, c.deltaArgs);
           const sig = signatures.get(index);
           const record: ToolCallRecord = {
-            id: c.id || newToolCallId(),
+            id: c.id && !c.id.includes("|") && c.id.length <= 40 ? c.id : clampToolCallId(c.id || newToolCallId()),
             name: c.name,
             arguments: args,
-            rawArguments: c.startArgs + c.deltaArgs,
+            rawArguments: selectRawArguments(c.startArgs, c.deltaArgs),
             ...withCompatSignature(sig),
           } as ToolCallRecord;
           toolCalls.push(record);
@@ -1146,6 +1250,13 @@ export class OpenAICompatibleChatProvider implements Provider {
           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));
+          return;
+        }
 
         const cleanThinking = cleanThinkingEarly;
         const finalThoughtSignature = toolCalls.map((c) => c.thoughtSignature).find(Boolean);
@@ -1172,8 +1283,7 @@ export class OpenAICompatibleChatProvider implements Provider {
         const isAbort =
           linked.signal.aborted ||
           eventStream.isCancelled() ||
-          (raw as { name?: string }).name === "AbortError" ||
-          /abort|cancell?ed/i.test(String((raw as { message?: string }).message ?? raw));
+          (raw as { name?: string }).name === "AbortError";
         eventStream.fail(
           isAbort ? Object.assign(new Error("Stream aborted"), { name: "AbortError" }) : raw
         );