agent-accelerator 0.3.0 → 0.4.5

package/src/providers/openai.ts

@@ -46,14 +46,27 @@ 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 } from "../utils/headers.ts";
+import { buildSessionHeaders, setHeaderCaseInsensitive } from "../utils/headers.ts";
 import { clampCacheKey } from "../utils/cache.ts";
 import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "../utils/errors.ts";
 import { withRetries } from "../utils/retry.ts";
+import {
+  parseArguments,
+  normalizeThinkingParts,
+  newToolCallId,
+  redactedHeaders,
+  readErrorPayload,
+  incompleteStreamError,
+  hasTruncatedToolArguments,
+  combinedSignal,
+  timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
+} from "./shared.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
-import { getModelFromCatalog, getModelsForProvider } from "../models/catalog.ts";
+import { getModelFromCatalog, getModelsForProvider, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   mapThinkingLevelToOpenAI,
   mapServiceTierToOpenAI,
@@ -61,6 +74,10 @@ import {
   mapToolChoiceToOpenAI,
   noteProviderTurn,
   parseStreamedToolArguments,
+  mapOutputToOpenAI,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
+  emitProviderWarning,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -92,6 +109,7 @@ interface ResponsesRequestBody {
   prompt_cache_key?: string;
   store?: boolean;
   stream?: boolean;
+  text?: { format: { type: "json_schema"; name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
   [k: string]: unknown;
 }
 
@@ -131,6 +149,12 @@ interface ResponsesObject {
 
 const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 
+/** Q-18: Responses transport never echoes thought signatures (no wire field).
+ * Local helper documents the namespacing decision per provider file. */
+function withProviderSignature(_sig: string | undefined): { thoughtSignature?: undefined } {
+  return {};
+}
+
 /** Internal headers that must never leak onto native REST requests. */
 const INTERNAL_HEADERS = new Set([
   "x-thought-signature-map",
@@ -154,7 +178,10 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
 }
 
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
-  return options?.apiKey || getApiKey("openai", undefined, options?.env);
+  const key = getApiKey("openai", options?.apiKey, options?.env);
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 /** Strips ONLY the `openai/` prefix. Bare ids pass through untouched. */
@@ -235,6 +262,20 @@ function resultToOutput(result: unknown): string {
   return safeStringify(result);
 }
 
+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";
+}
+
+function normalizeResponsesItemId(itemId: string): string {
+  let norm = normalizeResponsesIdPart(itemId);
+  if (!norm.startsWith("fc_")) {
+    norm = normalizeResponsesIdPart(`fc_${norm}`);
+  }
+  return norm;
+}
+
 /**
  * Builds the FULL explicit history (stateless — no server state, no
  * chaining). Assistant items intentionally carry no provider `id`/`status`:
@@ -284,10 +325,25 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
       const texts: string[] = [];
       for (const part of m.content) {
         if (part.type === "tool_call") {
+          // Cross-provider pipe IDs (`callId|itemId`) are split and
+          // normalized (64-char, `fc_` prefix) so replay never 400s.
+          const rawId = String(part.id ?? "");
+          const rawCallId = String(part.callId ?? part.id ?? "");
+          let itemId = rawId;
+          let callId = rawCallId;
+          if (rawId.includes("|")) {
+            const [c, i] = rawId.split("|");
+            if (c) callId = c;
+            if (i) itemId = i;
+          }
+          if (callId.includes("|")) {
+            const [c] = callId.split("|");
+            if (c) callId = c;
+          }
           items.push({
             type: "function_call",
-            id: part.id,
-            call_id: part.callId || part.id,
+            id: normalizeResponsesItemId(itemId),
+            call_id: normalizeResponsesIdPart(callId),
             name: part.name,
             arguments: JSON.stringify(part.arguments || {}),
           });
@@ -303,9 +359,11 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
     } else if (m.role === "tool") {
       if (typeof m.content === "string") {
         const queue = (m.name && idsByName.get(m.name)) || [];
+        const rawPair = queue.shift() || newToolCallId();
+        const rawCall = rawPair.includes("|") ? rawPair.split("|")[0]! : rawPair;
         items.push({
           type: "function_call_output",
-          call_id: queue.shift() || "call_0",
+          call_id: normalizeResponsesIdPart(rawCall),
           output: m.content,
         });
         continue;
@@ -313,9 +371,11 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
       if (!Array.isArray(m.content)) continue;
       for (const part of m.content) {
         if (part.type === "tool_result") {
+          const rawPair = pairing.get(part.id) || part.id;
+          const rawCall = rawPair.includes("|") ? rawPair.split("|")[0]! : rawPair;
           items.push({
             type: "function_call_output",
-            call_id: pairing.get(part.id) || part.id,
+            call_id: normalizeResponsesIdPart(rawCall),
             output: resultToOutput(part.result),
           });
         }
@@ -345,27 +405,6 @@ function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   };
 }
 
-function parseArguments(raw: string | undefined): Record<string, unknown> {
-  if (!raw) return {};
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as Record<string, unknown>;
-    }
-    return { raw };
-  } catch {
-    return { raw };
-  }
-}
-
-/** Trims/collapses assembled thinking parts (no edge-tripling). */
-function normalizeThinkingParts(parts: string[]): string | undefined {
-  const cleaned = parts
-    .map((p) => p.replace(/\n{3,}/g, "\n\n").trim())
-    .filter((p) => p.length > 0);
-  return cleaned.length > 0 ? cleaned.join("\n") : undefined;
-}
-
 function parseResponse(
   response: ResponsesObject,
   modelId: string,
@@ -384,6 +423,7 @@ function parseResponse(
   }
 
   let text = "";
+  let refusalText = "";
   const thinkingParts: string[] = [];
   const toolCalls: ToolCallRecord[] = [];
 
@@ -391,6 +431,15 @@ function parseResponse(
     if (item.type === "message") {
       for (const block of item.content ?? []) {
         if (block.type === "output_text" && block.text) text += block.text;
+        else if (block.type === "refusal" && block.text) {
+          text += block.text;
+          refusalText += block.text;
+        }
+      }
+      const itemRefusal = (item as { refusal?: unknown }).refusal;
+      if (typeof itemRefusal === "string" && itemRefusal) {
+        text += itemRefusal;
+        refusalText += itemRefusal;
       }
     } else if (item.type === "reasoning") {
       for (const block of item.content ?? []) {
@@ -404,7 +453,7 @@ function parseResponse(
     } else if (item.type === "function_call") {
       const args = parseArguments(item.arguments);
       toolCalls.push({
-        id: item.id || item.call_id || `call_${Math.random().toString(36).slice(2, 9)}`,
+        id: item.id || item.call_id || newToolCallId(),
         callId: item.call_id,
         name: item.name || "unknown",
         arguments: args,
@@ -413,6 +462,17 @@ function parseResponse(
     }
   }
 
+  // Q-23: `incomplete` -> length (content-filter truncations surface as
+  // refusal when refusal text is present).
+  const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
+  const finishReason =
+    toolCalls.length > 0
+      ? "tool_calls"
+      : refusalText || incompleteReason === "content_filter"
+        ? "refusal"
+        : response.status === "incomplete"
+          ? "length"
+          : "stop";
   return {
     text,
     // Trim/collapse reasoning assembly (provider summaries can trail with
@@ -422,7 +482,7 @@ function parseResponse(
     thoughtSignature: undefined,
     toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
     usage: mapUsage(response.usage),
-    finishReason: toolCalls.length > 0 ? "tool_calls" : response.status === "incomplete" ? "length" : "stop",
+    finishReason,
     responseId: response.id,
     model: modelId,
     provider: "openai",
@@ -431,32 +491,6 @@ function parseResponse(
   };
 }
 
-function redactedHeaders(headers: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    out[k] = k.toLowerCase() === "authorization" ? "[REDACTED]" : v;
-  }
-  return out;
-}
-
-function readErrorPayload(bodyText: string): { message: string; code?: string | number; errorType?: string } {
-  try {
-    const parsed: unknown = JSON.parse(bodyText);
-    const first = Array.isArray(parsed) ? parsed[0] : parsed;
-    const err = (first as { error?: { message?: string; code?: string | number; type?: string } })?.error;
-    if (err && typeof err.message === "string") {
-      return {
-        message: err.message,
-        code: err.code,
-        ...(typeof err.type === "string" ? { errorType: err.type } : {}),
-      };
-    }
-    return { message: bodyText.slice(0, 300) };
-  } catch {
-    return { message: bodyText.slice(0, 300) };
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
@@ -496,16 +530,38 @@ export class OpenAIResponsesProvider implements Provider {
     const serviceTier = mapServiceTierToOpenAI(options?.serviceTier);
     applyCacheForOpenAI(options?.cache, `openai/${modelId}`);
 
+    // Structured outputs: native `text.format` when supported, else emulated
+    // via instructions (catalog `structured_output: false` would 400).
+    let effectiveSystemPrompt = context.systemPrompt;
+    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("openai", modelId)) {
+      outputEmulated = true;
+      effectiveSystemPrompt = augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec);
+      emitProviderWarning({
+        provider: "openai",
+        capability: "structured output",
+        requested: `${outputSpec.name} (openai/${modelId})`,
+        reason: "the catalog reports structured_output: false for this model, so native text.format is unsupported.",
+        fallback: "emulated JSON instruction + client validation (no text.format is sent)",
+      });
+    }
+
     const body: ResponsesRequestBody = {
       model: modelId,
-      input: await fullHistoryInput(context),
+      input: await fullHistoryInput({ ...context, systemPrompt: effectiveSystemPrompt }),
       // Stateless by design: the server defaults store:true, so opt out
       // explicitly. Full history is always sent, so no chaining is needed
       // and provider switching stays trivial.
       store: false,
       ...(stream ? { stream: true } : {}),
     };
-    if (context.systemPrompt) body.instructions = context.systemPrompt;
+    if (effectiveSystemPrompt) body.instructions = effectiveSystemPrompt;
     const aiTools = toOpenAITools(tools);
     if (aiTools) body.tools = aiTools;
     const toolChoice = mapToolChoiceToOpenAI(
@@ -514,8 +570,17 @@ export class OpenAIResponsesProvider implements Provider {
     if (toolChoice !== undefined) body.tool_choice = toolChoice;
     if (effort) body.reasoning = { effort };
     if (serviceTier) body.service_tier = serviceTier;
+    // Structured outputs: Responses `text.format{type:json_schema,name,schema,strict}`.
+    // Skipped when emulated (instruction already in `instructions`).
+    if (outputSpec && !outputEmulated) {
+      try {
+        const mapped = mapOutputToOpenAI(outputSpec);
+        if (mapped) body.text = { format: mapped.format };
+      } catch {
+        // why: invalid output shapes fail fast at Agent construction/loop validation.
+      }
+    }
     // Cache affinity: prompt_cache_key replaces the legacy `user` field.
-    // (prompt_cache_options explicit breakpoints are out of scope.)
     // OpenAI enforces max 64 chars — clamp defensively so child session ids
     // (`parent-sub-tag-rand`) and user-supplied long ids never 400. Headers
     // are clamped the same way via buildSessionHeaders, keeping affinity
@@ -524,6 +589,29 @@ export class OpenAIResponsesProvider implements Provider {
       const cacheKey = clampCacheKey(sessionId);
       if (cacheKey) body.prompt_cache_key = cacheKey;
     }
+    // Long retention: `prompt_cache_retention: "24h"` when the catalog
+    // supports it (pi api/openai-responses.ts:97 rule). Other explicit modes
+    // stay warn+drop via applyCacheForOpenAI above.
+    if (options?.cache?.retention === "long") {
+      let supportsLong = true;
+      try {
+        const spec = getModelFromCatalog("openai", modelId);
+        if (spec && typeof spec.capabilities?.supportsLongCacheRetention === "boolean") {
+          supportsLong = spec.capabilities.supportsLongCacheRetention;
+        }
+      } catch {}
+      if (supportsLong) {
+        (body as Record<string, unknown>)["prompt_cache_retention"] = "24h";
+      } else {
+        emitProviderWarning({
+          provider: "openai",
+          capability: "cache retention",
+          requested: `long (openai/${modelId})`,
+          reason: "the catalog reports no long-cache support for this model.",
+          fallback: "default caching with prompt_cache_key affinity (no retention payload is sent)",
+        });
+      }
+    }
     // Stateless API use: previous_response_id / background / conversation are
     // NEVER sent (server state would break provider-agnostic switching).
     return body;
@@ -545,8 +633,11 @@ export class OpenAIResponsesProvider implements Provider {
     for (const [k, v] of Object.entries(headers)) {
       if (INTERNAL_HEADERS.has(k.toLowerCase())) delete headers[k];
     }
-    headers["Content-Type"] = "application/json";
-    headers["Authorization"] = `Bearer ${apiKey}`;
+    // Case-insensitive merge so a lowercase `authorization` custom header
+    // never coexists with the canonical bearer. Proxy flows
+    // (`apiKey === "unused"`) preserve custom auth instead of overwriting.
+    setHeaderCaseInsensitive(headers, "Content-Type", "application/json");
+    if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "Authorization", `Bearer ${apiKey}`);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -558,13 +649,18 @@ export class OpenAIResponsesProvider implements Provider {
     sessionId: string | undefined,
     signal?: AbortSignal
   ): Promise<{ status: number; statusText: string; headers: Record<string, string>; text: string }> {
-    const res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, signal));
-    const text = await res.text();
-    const headers: Record<string, string> = {};
-    res.headers.forEach((v, k) => {
-      headers[k] = v;
-    });
-    return { status: res.status, statusText: res.statusText, headers, text };
+    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 text = await res.text();
+      const headers: Record<string, string> = {};
+      res.headers.forEach((v, k) => {
+        headers[k] = v;
+      });
+      return { status: res.status, statusText: res.statusText, headers, text };
+    } finally {
+      cleanup();
+    }
   }
 
   private throwIfError(
@@ -574,14 +670,23 @@ export class OpenAIResponsesProvider implements Provider {
     modelId: 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 OPENAI_API_KEY (no quotes/spaces, correct provider), OPENAI_BASE_URL, 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];
+    // Preserve hint through toConciseProviderError re-wrap (it prefers
+    // data.error.message over responseBody).
+    (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;
     throw toConciseProviderError(err, "openai", modelId);
   }
 
@@ -728,7 +833,22 @@ export class OpenAIResponsesProvider implements Provider {
           body,
         };
 
-        const res = await fetch(url, this.requestInit(body, options, apiKey, sessionId, linked.signal));
+        // Q-17: optional per-call timeout races the linked abort signal.
+        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);
@@ -738,7 +858,7 @@ export class OpenAIResponsesProvider implements Provider {
         res.headers.forEach((v, k) => {
           responseHeaders[k] = v;
         });
-        const responseMeta = { status: res.status, statusText: res.statusText, headers: responseHeaders };
+        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();
@@ -750,6 +870,11 @@ export class OpenAIResponsesProvider implements Provider {
         const calls = new Map<number, { itemId: string; callId: string; name: string; startArgs: string; deltaArgs: string }>();
         let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = "stop";
+        let sawFinishReason = false;
+        let sawUsage = false;
+        let refusalSeen = false;
+        let badFrames = 0;
+        let framesSeen = 0;
         let responseId: string | undefined;
         let completedBody: unknown = undefined;
         let aborted = false;
@@ -765,11 +890,16 @@ export class OpenAIResponsesProvider implements Provider {
         );
 
         const handleMessage = (data: string): void => {
-          if (!data || data === "[DONE]") return;
+          if (!data || data === "[DONE]") {
+            if (data === "[DONE]") sawFinishReason = sawFinishReason || completedBody !== undefined || sawUsage;
+            return;
+          }
           let msg: Record<string, unknown>;
           try {
             msg = JSON.parse(data) as Record<string, unknown>;
+            framesSeen += 1;
           } catch {
+            badFrames += 1;
             return;
           }
           const type = msg["type"] as string;
@@ -790,6 +920,17 @@ export class OpenAIResponsesProvider implements Provider {
           } else if (type === "response.output_text.delta" && typeof msg["delta"] === "string") {
             text += msg["delta"] as string;
             eventStream.push({ type: "text_delta", delta: msg["delta"] as string, partialText: text });
+          } else if (
+            type === "response.refusal.delta" ||
+            type === "response.output_refusal.delta"
+          ) {
+            // Q-23: refusal deltas carry the filter text; surface as text and
+            // remember for a `refusal` finish reason.
+            if (typeof msg["delta"] === "string" && msg["delta"]) {
+              text += msg["delta"] as string;
+              refusalSeen = true;
+              eventStream.push({ type: "text_delta", delta: msg["delta"] as string, partialText: text });
+            }
           } else if (
             (type === "response.reasoning_text.delta" || type === "response.reasoning.delta") &&
             typeof msg["delta"] === "string"
@@ -827,7 +968,11 @@ export class OpenAIResponsesProvider implements Provider {
             const response = (msg["response"] as ResponsesObject) ?? {};
             completedBody = msg["response"];
             if (response.id) responseId = response.id;
-            if (response.usage) usage = mapUsage(response.usage);
+            if (response.usage) {
+              usage = mapUsage(response.usage);
+              sawUsage = true;
+            }
+            sawFinishReason = true;
             if (type === "response.failed" || response.status === "failed") {
               const message =
                 (response.error && typeof response.error.message === "string" && response.error.message) ||
@@ -839,7 +984,12 @@ export class OpenAIResponsesProvider implements Provider {
             }
             // Non-streaming maps `incomplete` → `length` (max tokens). Streaming
             // must do the same — otherwise truncated turns misreport `stop`.
-            if (response.status === "incomplete") finishReason = "length";
+            // Q-23: content-filter incompletes surface as `refusal`.
+            const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
+            if (response.status === "incomplete") {
+              finishReason = incompleteReason === "content_filter" ? "refusal" : "length";
+              sawFinishReason = true;
+            }
             // Merge any full tool items delivered at completion (authoritative
             // when present) so nothing depends solely on delta assembly.
             for (const item of response.output ?? []) {
@@ -876,6 +1026,17 @@ export class OpenAIResponsesProvider implements Provider {
                 }
               }
             }
+            // Merge completed refusal text (filter truncations often arrive only
+            // here with no preceding refusal delta).
+            for (const item of response.output ?? []) {
+              if (item.type !== "message") continue;
+              for (const block of item.content ?? []) {
+                if (block.type === "refusal" && block.text) {
+                  if (!text.includes(block.text)) text += block.text;
+                  refusalSeen = true;
+                }
+              }
+            }
             eventStream.push({ type: "usage", usage });
           }
         };
@@ -905,7 +1066,7 @@ export class OpenAIResponsesProvider implements Provider {
         for (const c of calls.values()) {
           const args = parseStreamedToolArguments(c.startArgs, c.deltaArgs);
           const record: ToolCallRecord = {
-            id: c.itemId || c.callId || `call_${Math.random().toString(36).slice(2, 9)}`,
+            id: c.itemId || c.callId || newToolCallId(),
             callId: c.callId || undefined,
             name: c.name,
             arguments: args,
@@ -916,9 +1077,40 @@ export class OpenAIResponsesProvider implements Provider {
         }
 
         noteProviderTurn(sessionId, "openai");
-        if (toolCalls.length > 0) finishReason = "tool_calls";
+        if (toolCalls.length > 0) {
+          finishReason = "tool_calls";
+          sawFinishReason = true;
+        } else if (refusalSeen && finishReason !== "length") {
+          finishReason = "refusal";
+          sawFinishReason = true;
+        }
 
-        const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        // Q-23: terminal-state guard. Loops ending with no completed body, no
+        // finish_reason, and no usage while carrying no content must fail as
+        // `incomplete_stream` (retryable) instead of resolving empty success.
+        // 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));
+          return;
+        }
+
+        const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({
           text,
           thinking: cleanThinking || undefined,
@@ -929,7 +1121,10 @@ export class OpenAIResponsesProvider implements Provider {
           responseId,
           model: clean,
           provider: "openai",
-          raw: { request: rawRequest, response: { ...responseMeta, body: completedBody } },
+          raw: {
+            request: rawRequest,
+            response: { ...responseMeta, body: completedBody, badFrames } as unknown as ProviderRawData["response"],
+          },
           durationMs: Date.now() - startTime,
         });
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });