@llumiverse/drivers 1.2.0 → 1.4.0-dev.20260629.090753Z

package/src/openai/index.ts

@@ -1,39 +1,44 @@
 import {
-    AbstractDriver,
-    AIModel,
-    Completion,
-    CompletionChunkObject,
-    CompletionResult,
-    DataSource,
-    DriverOptions,
-    EmbeddingsOptions,
-    EmbeddingsResult,
-    ExecutionOptions,
-    ExecutionTokenUsage,
+    type AIModel,
+    type Completion,
+    type CompletionChunkObject,
+    type CompletionResult,
+    type DataSource,
+    type DriverOptions,
+    type EmbeddingResultItem,
+    type EmbeddingsOptions,
+    type EmbeddingsResult,
+    type ExecutionOptions,
+    type ExecutionTokenUsage,
     getConversationMeta,
     getModelCapabilities,
     incrementConversationTurn,
-    JSONSchema,
+    type JSONSchema,
     LlumiverseError,
-    LlumiverseErrorContext,
-    modelModalitiesToArray,
+    type LlumiverseErrorContext,
     ModelType,
-    OpenAiDalleOptions,
-    OpenAiGptImageOptions,
-    Providers,
+    modelModalitiesToArray,
+    normalizeEmbeddingsOptions,
+    OPENAI_DEFAULT_EMBEDDING_MODEL,
+    type OpenAiDalleOptions,
+    type OpenAiGptImageOptions,
+    type Providers,
     stripBase64ImagesFromConversation,
     stripHeartbeatsFromConversation,
     supportsToolUse,
-    ToolDefinition,
-    ToolUse,
-    TrainingJob,
+    type TextFallbackOptions,
+    type ToolDefinition,
+    type ToolUse,
+    type TrainingJob,
     TrainingJobStatus,
-    TrainingOptions,
-    TrainingPromptOptions,
+    type TrainingOptions,
+    type TrainingPromptOptions,
     truncateLargeTextInConversation,
     unwrapConversationArray,
-} from "@llumiverse/core";
-import OpenAI, { AzureOpenAI } from "openai";
+} from '@llumiverse/core';
+import { AbstractDriver } from '@llumiverse/core/driver';
+import type OpenAI from 'openai';
+import type { AzureOpenAI } from 'openai';
 import {
     APIConnectionError,
     APIConnectionTimeoutError,
@@ -50,23 +55,49 @@ import {
     RateLimitError,
     UnprocessableEntityError,
 } from 'openai/error';
-import { formatOpenAILikeMultimodalPrompt } from "./openai_format.js";
+import { formatOpenAILikeMultimodalPrompt } from './openai_format.js';
 
 // Response API types
 type ResponseInputItem = OpenAI.Responses.ResponseInputItem;
 type EasyInputMessage = OpenAI.Responses.EasyInputMessage;
+type OpenAIRequestOptions = Partial<TextFallbackOptions> & {
+    image_detail?: 'low' | 'high' | 'auto';
+    effort?: string;
+    reasoning_effort?: string;
+};
+type OpenAIErrorWithStatus = Error & { status?: unknown };
+type OpenAIUsageWithProviderDetails = OpenAI.Responses.ResponseUsage & {
+    cached_tokens?: number | null;
+    prompt_tokens_details?: {
+        cached_tokens?: number | null;
+    } | null;
+};
+type MutableRoleItem = { role: 'user' | 'developer' | 'system' | 'assistant' };
+type MutableInputImagePart = { type: string; detail?: string };
+type OpenAIFunctionItem = ResponseInputItem & {
+    type?: string;
+    name?: string;
+    arguments?: string;
+    output?: string;
+};
 
 // Helper function to convert string to CompletionResult[]
 function textToCompletionResult(text: string): CompletionResult[] {
-    return text ? [{ type: "text", value: text }] : [];
+    return text ? [{ type: 'text', value: text }] : [];
+}
+
+function hasNumericStatus(error: unknown): boolean {
+    return error instanceof Error && typeof (error as OpenAIErrorWithStatus).status === 'number';
 }
 
 function isOpenAIReasoningModel(model: string): boolean {
     const normalized = model.toLowerCase();
-    return normalized.includes("o1")
-        || normalized.includes("o3")
-        || normalized.includes("o4")
-        || normalized.includes("gpt-5");
+    return (
+        normalized.includes('o1') ||
+        normalized.includes('o3') ||
+        normalized.includes('o4') ||
+        normalized.includes('gpt-5')
+    );
 }
 
 function isGpt5ProModel(model: string): boolean {
@@ -74,33 +105,35 @@ function isGpt5ProModel(model: string): boolean {
     return /^gpt-5(?:\.\d+)?-pro/.test(modelName);
 }
 
-function openAIReasoningEffort(model: string, effort: string | undefined): "low" | "medium" | "high" | undefined {
+function openAIReasoningEffort(model: string, effort: string | undefined): 'low' | 'medium' | 'high' | undefined {
     if (!effort || !isOpenAIReasoningModel(model)) {
         return undefined;
     }
     if (isGpt5ProModel(model)) {
-        return "high";
+        return 'high';
     }
-    return effort === "low" || effort === "medium" || effort === "high" ? effort : undefined;
+    return effort === 'low' || effort === 'medium' || effort === 'high' ? effort : undefined;
 }
 
 //TODO: Do we need a list?, replace with if statements and modernize?
 const supportFineTunning = new Set([
-    "gpt-3.5-turbo-1106",
-    "gpt-3.5-turbo-0613",
-    "babbage-002",
-    "davinci-002",
-    "gpt-4-0613"
+    'gpt-3.5-turbo-1106',
+    'gpt-3.5-turbo-0613',
+    'babbage-002',
+    'davinci-002',
+    'gpt-4-0613',
 ]);
 
-export interface BaseOpenAIDriverOptions extends DriverOptions {
-}
+export interface BaseOpenAIDriverOptions extends DriverOptions {}
 
-export abstract class BaseOpenAIDriver extends AbstractDriver<
-    BaseOpenAIDriverOptions,
-    ResponseInputItem[]
-> {
-    abstract provider: Providers.openai | Providers.azure_openai | Providers.xai | Providers.azure_foundry | Providers.openai_compatible;
+export abstract class BaseOpenAIDriver extends AbstractDriver<BaseOpenAIDriverOptions, ResponseInputItem[]> {
+    abstract provider:
+        | Providers.openai
+        | Providers.azure_openai
+        | Providers.xai
+        | Providers.azure_foundry
+        | Providers.togetherai
+        | Providers.openai_compatible;
     abstract service: OpenAI | AzureOpenAI;
 
     constructor(opts: BaseOpenAIDriverOptions) {
@@ -108,10 +141,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         this.formatPrompt = formatOpenAILikeMultimodalPrompt;
     }
 
-    extractDataFromResponse(
-        _options: ExecutionOptions,
-        result: OpenAI.Responses.Response
-    ): Completion {
+    extractDataFromResponse(_options: ExecutionOptions, result: OpenAI.Responses.Response): Completion {
         const tokenInfo = mapUsage(result.usage);
 
         const tools = collectTools(result.output);
@@ -119,8 +149,8 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         const allResults = extractCompletionResults(result.output);
 
         if (allResults.length === 0 && !tools) {
-            this.logger.error({ result }, "[OpenAI] Response is not valid");
-            throw new Error("Response is not valid: no data");
+            this.logger.error({ result }, '[OpenAI] Response is not valid');
+            throw new Error('Response is not valid: no data');
         }
 
         return {
@@ -131,17 +161,22 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         };
     }
 
-    async requestTextCompletionStream(prompt: ResponseInputItem[], options: ExecutionOptions): Promise<AsyncIterable<CompletionChunkObject>> {
-        if (options.model_options?._option_id !== undefined &&
-            options.model_options?._option_id !== "openai-text" &&
-            options.model_options?._option_id !== "openai-thinking" &&
-            options.model_options?._option_id !== "text-fallback") {
-            this.logger.debug({ options: options.model_options }, "Unexpected option id");
+    async requestTextCompletionStream(
+        prompt: ResponseInputItem[],
+        options: ExecutionOptions,
+    ): Promise<AsyncIterable<CompletionChunkObject>> {
+        if (
+            options.model_options?._option_id !== undefined &&
+            options.model_options?._option_id !== 'openai-text' &&
+            options.model_options?._option_id !== 'openai-thinking' &&
+            options.model_options?._option_id !== 'text-fallback'
+        ) {
+            this.logger.debug({ options: options.model_options }, 'Unexpected option id');
         }
 
         // Include conversation history (same as non-streaming)
         // Fix orphaned function_call items (can occur when agent is stopped mid-tool-execution)
-        let conversation = fixOrphanedToolUse(updateConversation(options.conversation, prompt));
+        let conversation = fixOrphanedToolResults(fixOrphanedToolUse(updateConversation(options.conversation, prompt)));
 
         const toolDefs = getToolDefinitions(options.tools);
         const useTools: boolean = toolDefs ? supportsToolUse(options.model, this.provider, true) : false;
@@ -154,17 +189,16 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
 
         convertRoles(prompt, options.model);
 
-        const model_options = options.model_options as any;
-        insert_image_detail(prompt, model_options?.image_detail ?? "auto");
+        const model_options = options.model_options as OpenAIRequestOptions | undefined;
+        insert_image_detail(prompt, model_options?.image_detail ?? 'auto');
 
-        let parsedSchema: JSONSchema | undefined = undefined;
+        let parsedSchema: JSONSchema | undefined;
         let strictMode = false;
-        if (options.result_schema && supportsSchema(options.model)) {
+        if (options.result_schema && supportsSchema(options.model, this.provider)) {
             try {
                 parsedSchema = openAISchemaFormat(options.result_schema);
                 strictMode = true;
-            }
-            catch (e) {
+            } catch {
                 parsedSchema = limitedSchemaFormat(options.result_schema);
                 strictMode = false;
             }
@@ -183,36 +217,41 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             top_p: isReasoningModel ? undefined : model_options?.top_p,
             max_output_tokens: model_options?.max_tokens,
             tools: useTools ? toolDefs : undefined,
-            text: parsedSchema ? {
-                format: {
-                    type: "json_schema",
-                    name: "format_output",
-                    schema: parsedSchema,
-                    strict: strictMode,
-                }
-            } : undefined,
+            text: parsedSchema
+                ? {
+                      format: {
+                          type: 'json_schema',
+                          name: 'format_output',
+                          schema: parsedSchema,
+                          strict: strictMode,
+                      },
+                  }
+                : undefined,
         });
 
         return mapResponseStream(stream);
     }
 
     async requestTextCompletion(prompt: ResponseInputItem[], options: ExecutionOptions): Promise<Completion> {
-        if (options.model_options?._option_id !== undefined &&
-            options.model_options?._option_id !== "openai-text" &&
-            options.model_options?._option_id !== "openai-thinking") {
-            this.logger.debug({ options: options.model_options }, "Unexpected option id");
+        if (
+            options.model_options?._option_id !== undefined &&
+            options.model_options?._option_id !== 'openai-text' &&
+            options.model_options?._option_id !== 'openai-thinking' &&
+            options.model_options?._option_id !== 'text-fallback'
+        ) {
+            this.logger.debug({ options: options.model_options }, 'Unexpected option id');
         }
 
         convertRoles(prompt, options.model);
 
-        const model_options = options.model_options as any;
-        insert_image_detail(prompt, model_options?.image_detail ?? "auto");
+        const model_options = options.model_options as OpenAIRequestOptions | undefined;
+        insert_image_detail(prompt, model_options?.image_detail ?? 'auto');
 
         const toolDefs = getToolDefinitions(options.tools);
         const useTools: boolean = toolDefs ? supportsToolUse(options.model, this.provider) : false;
 
         // Fix orphaned function_call items (can occur when agent is stopped mid-tool-execution)
-        let conversation = fixOrphanedToolUse(updateConversation(options.conversation, prompt));
+        let conversation = fixOrphanedToolResults(fixOrphanedToolUse(updateConversation(options.conversation, prompt)));
 
         // When no tools are provided but conversation contains function_call/function_call_output
         // items (e.g. checkpoint summary calls), convert them to text to avoid API errors
@@ -220,14 +259,13 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             conversation = convertOpenAIFunctionItemsToText(conversation);
         }
 
-        let parsedSchema: JSONSchema | undefined = undefined;
+        let parsedSchema: JSONSchema | undefined;
         let strictMode = false;
-        if (options.result_schema && supportsSchema(options.model)) {
+        if (options.result_schema && supportsSchema(options.model, this.provider)) {
             try {
                 parsedSchema = openAISchemaFormat(options.result_schema);
                 strictMode = true;
-            }
-            catch (e) {
+            } catch {
                 parsedSchema = limitedSchemaFormat(options.result_schema);
                 strictMode = false;
             }
@@ -246,14 +284,16 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             top_p: isReasoningModel ? undefined : model_options?.top_p,
             max_output_tokens: model_options?.max_tokens, //TODO: use max_tokens for older models, currently relying on OpenAI to handle it
             tools: useTools ? toolDefs : undefined,
-            text: parsedSchema ? {
-                format: {
-                    type: "json_schema",
-                    name: "format_output",
-                    schema: parsedSchema,
-                    strict: strictMode,
-                }
-            } : undefined,
+            text: parsedSchema
+                ? {
+                      format: {
+                          type: 'json_schema',
+                          name: 'format_output',
+                          schema: parsedSchema,
+                          strict: strictMode,
+                      },
+                  }
+                : undefined,
         });
 
         const completion = this.extractDataFromResponse(options, res);
@@ -271,7 +311,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         const stripOptions = {
             keepForTurns: options.stripImagesAfterTurns ?? Infinity,
             currentTurn,
-            textMaxTokens: options.stripTextMaxTokens
+            textMaxTokens: options.stripTextMaxTokens,
         };
         let processedConversation = stripBase64ImagesFromConversation(conversation, stripOptions);
 
@@ -291,14 +331,15 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
 
     protected canStream(_options: ExecutionOptions): Promise<boolean> {
         // Image generation models don't support streaming
-        if (_options.model.includes("dall-e")
-            || _options.model.includes("gpt-image")
-            || _options.model.includes("chatgpt-image")) {
+        if (
+            _options.model.includes('dall-e') ||
+            _options.model.includes('gpt-image') ||
+            _options.model.includes('chatgpt-image')
+        ) {
             return Promise.resolve(false);
         }
 
-        if (_options.model.includes("o1")
-            && !(_options.model.includes("mini") || _options.model.includes("preview"))) {
+        if (_options.model.includes('o1') && !(_options.model.includes('mini') || _options.model.includes('preview'))) {
             //o1 full does not support streaming
             //TODO: Update when OpenAI adds support for streaming, last check 16/02/2025
             return Promise.resolve(false);
@@ -314,7 +355,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         prompt: ResponseInputItem[],
         result: unknown[],
         toolUse: unknown[] | undefined,
-        options: ExecutionOptions
+        options: ExecutionOptions,
     ): ResponseInputItem[] | undefined {
         // Build assistant message from accumulated CompletionResult[]
         const completionResults = result as CompletionResult[];
@@ -327,6 +368,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         // Add assistant message as EasyInputMessage
         if (textContent) {
             const assistantMessage: EasyInputMessage = {
+                type: 'message',
                 role: 'assistant',
                 content: textContent,
             };
@@ -335,7 +377,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
 
         // Add function calls as separate items (Response API format)
         if (toolUse && toolUse.length > 0) {
-            const functionCalls: OpenAI.Responses.ResponseFunctionToolCall[] = (toolUse as ToolUse[]).map(t => ({
+            const functionCalls: OpenAI.Responses.ResponseFunctionToolCall[] = (toolUse as ToolUse[]).map((t) => ({
                 type: 'function_call' as const,
                 call_id: t.id,
                 name: t.tool_name,
@@ -352,7 +394,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         const stripOptions = {
             keepForTurns: options.stripImagesAfterTurns ?? Infinity,
             currentTurn,
-            textMaxTokens: options.stripTextMaxTokens
+            textMaxTokens: options.stripTextMaxTokens,
         };
         let processedConversation = stripBase64ImagesFromConversation(conversation, stripOptions);
         processedConversation = truncateLargeTextInConversation(processedConversation, stripOptions);
@@ -365,11 +407,11 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
     }
 
     createTrainingPrompt(options: TrainingPromptOptions): Promise<string> {
-        if (options.model.includes("gpt")) {
+        if (options.model.includes('gpt')) {
             return super.createTrainingPrompt(options);
         } else {
             // babbage, davinci not yet implemented
-            throw new Error("Unsupported model for training: " + options.model);
+            throw new Error(`Unsupported model for training: ${options.model}`);
         }
     }
 
@@ -377,14 +419,14 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         const url = await dataset.getURL();
         const file = await this.service.files.create({
             file: await fetch(url),
-            purpose: "fine-tune",
+            purpose: 'fine-tune',
         });
 
         const job = await this.service.fineTuning.jobs.create({
             training_file: file.id,
             model: options.model,
-            hyperparameters: options.params
-        })
+            hyperparameters: options.params,
+        });
 
         return jobInfo(job);
     }
@@ -405,7 +447,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         try {
             await this.service.models.list();
             return true;
-        } catch (error) {
+        } catch {
             return false;
         }
     }
@@ -423,9 +465,21 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
 
         //Some of these use the completions API instead of the chat completions API.
         //Others are for non-text input modalities. Therefore common to both.
-        const wordBlacklist = ["embed", "whisper", "transcribe", "audio", "moderation", "tts",
-            "realtime", "babbage", "davinci", "codex", "o1-pro", "computer-use", "sora"];
-
+        const wordBlacklist = [
+            'embed',
+            'whisper',
+            'transcribe',
+            'audio',
+            'moderation',
+            'tts',
+            'realtime',
+            'babbage',
+            'davinci',
+            'codex',
+            'o1-pro',
+            'computer-use',
+            'sora',
+        ];
 
         //OpenAI has very little information, filtering based on name.
         result = result.filter((m) => {
@@ -433,61 +487,84 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         });
 
         const models = filter ? result.filter(filter) : result;
-        const aiModels = models.map((m) => {
-            const modelCapability = getModelCapabilities(m.id, "openai");
-            let owner = m.owned_by;
-            if (owner == "system") {
-                owner = "openai";
-            }
-
-            // Determine model type based on capabilities
-            let modelType = ModelType.Text;
-            if (m.id.includes("dall-e") || m.id.includes("gpt-image")) {
-                modelType = ModelType.Image;
-            }
+        const aiModels = models
+            .map((m) => {
+                const modelCapability = getModelCapabilities(m.id, this.provider);
+                let owner = m.owned_by;
+                if (owner === 'system') {
+                    owner = 'openai';
+                }
 
+                // Determine model type based on capabilities
+                let modelType = ModelType.Text;
+                if (m.id.includes('dall-e') || m.id.includes('gpt-image')) {
+                    modelType = ModelType.Image;
+                }
 
-            return {
-                id: m.id,
-                name: m.id,
-                provider: this.provider,
-                owner: owner,
-                type: modelType,
-                input_modalities: modelModalitiesToArray(modelCapability.input),
-                output_modalities: modelModalitiesToArray(modelCapability.output),
-                tool_support: modelCapability.tool_support,
-            } satisfies AIModel<string>;
-        }).sort((a, b) => a.id.localeCompare(b.id));
+                return {
+                    id: m.id,
+                    name: m.id,
+                    provider: this.provider,
+                    owner: owner,
+                    type: modelType,
+                    input_modalities: modelModalitiesToArray(modelCapability.input),
+                    output_modalities: modelModalitiesToArray(modelCapability.output),
+                    tool_support: modelCapability.tool_support,
+                } satisfies AIModel<string>;
+            })
+            .sort((a, b) => a.id.localeCompare(b.id));
 
         return aiModels;
     }
 
+    async generateEmbeddings(options: EmbeddingsOptions): Promise<EmbeddingsResult> {
+        const normalized = normalizeEmbeddingsOptions(options);
+        const model = normalized.model ?? OPENAI_DEFAULT_EMBEDDING_MODEL;
 
-    async generateEmbeddings({ text, image, model = "text-embedding-3-small" }: EmbeddingsOptions): Promise<EmbeddingsResult> {
-
-        if (image) {
-            throw new Error("Image embeddings not supported by OpenAI");
-        }
+        const texts: string[] = normalized.inputs.map((input) => {
+            if (input.type !== 'text') {
+                throw new Error(
+                    `Provider 'openai' does not support '${input.type}' embeddings; only 'text' is supported.`,
+                );
+            }
+            return input.text;
+        });
 
-        if (!text) {
-            throw new Error("No text provided");
-        }
+        try {
+            const res = await this.service.embeddings.create({
+                input: texts,
+                model,
+                ...(normalized.dimensions ? { dimensions: normalized.dimensions } : {}),
+                encoding_format: 'float',
+            });
 
-        const res = await this.service.embeddings.create({
-            input: text,
-            model: model,
-        });
+            // OpenAI does not guarantee data is returned in the same order as the input,
+            // but does return a stable `index` per item. Sort by index to align with inputs.
+            const ordered = [...res.data].sort((a, b) => a.index - b.index);
+            const items = ordered.map((entry): EmbeddingResultItem => {
+                if (!entry.embedding || entry.embedding.length === 0) {
+                    throw new Error(`OpenAI embedding empty for input index ${entry.index}`);
+                }
+                return { outputs: [{ values: entry.embedding, modality: 'text' }] };
+            });
 
-        const embeddings = res.data[0].embedding;
+            const usage = res.usage
+                ? { input_tokens: res.usage.prompt_tokens, input_text_tokens: res.usage.prompt_tokens }
+                : undefined;
 
-        if (!embeddings || embeddings.length === 0) {
-            throw new Error("No embedding found");
+            return { model, results: items, usage };
+        } catch (error) {
+            if (LlumiverseError.isLlumiverseError(error)) throw error;
+            if (error instanceof Error && !hasNumericStatus(error)) throw error;
+            throw this.formatLlumiverseError(error, {
+                provider: this.provider,
+                model,
+                operation: 'execute',
+            });
         }
-
-        return { values: embeddings, model } satisfies EmbeddingsResult;
     }
 
-    imageModels = ["dall-e", "gpt-image", "chatgpt-image"];
+    imageModels = ['dall-e', 'gpt-image', 'chatgpt-image'];
 
     /**
      * Determine if a model is specifically an image generation model (not conversational image model)
@@ -495,7 +572,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
     isImageModel(model: string): boolean {
         // DALL-E models are standalone image generation
         // gpt-image models can generate images in conversations, not standalone
-        return this.imageModels.some(imageModel => model.includes(imageModel));
+        return this.imageModels.some((imageModel) => model.includes(imageModel));
     }
 
     /**
@@ -508,15 +585,15 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         const model_options = options.model_options as OpenAiDalleOptions | OpenAiGptImageOptions | undefined;
 
         // Extract prompt text from ResponseInputItem[]
-        let promptText = "";
+        let promptText = '';
         for (const item of prompt) {
             if ('content' in item && typeof item.content === 'string') {
-                promptText += item.content + "\\n";
+                promptText += `${item.content}\\n`;
             } else if ('content' in item && Array.isArray(item.content)) {
                 // Extract text from content array
                 for (const part of item.content) {
                     if ('type' in part && part.type === 'input_text' && 'text' in part) {
-                        promptText += part.text + "\\n";
+                        promptText += `${part.text}\\n`;
                     }
                 }
             }
@@ -527,17 +604,17 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             const generateParams: OpenAI.Images.ImageGenerateParamsNonStreaming = {
                 model: options.model,
                 prompt: promptText,
-                size: model_options?.size || "1024x1024",
+                size: model_options?.size || '1024x1024',
             };
 
             // Add DALL-E specific options
-            if (options.model.includes("dall-e") || model_options?._option_id === "openai-dalle") {
+            if (options.model.includes('dall-e') || model_options?._option_id === 'openai-dalle') {
                 const dalleOptions = model_options as OpenAiDalleOptions | undefined;
                 generateParams.n = dalleOptions?.n || 1;
-                generateParams.response_format = dalleOptions?.response_format || "b64_json";
+                generateParams.response_format = dalleOptions?.response_format || 'b64_json';
 
-                if (options.model.includes("dall-e-3")) {
-                    generateParams.quality = dalleOptions?.image_quality || "standard";
+                if (options.model.includes('dall-e-3')) {
+                    generateParams.quality = dalleOptions?.image_quality || 'standard';
                     if (dalleOptions?.style) {
                         generateParams.style = dalleOptions.style;
                     }
@@ -567,31 +644,35 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
                     }
 
                     results.push({
-                        type: "image",
-                        value: imageValue
+                        type: 'image',
+                        value: imageValue,
                     });
                 }
             }
 
             return {
-                result: results
+                result: results,
             };
-
-        } catch (error: any) {
+        } catch (error: unknown) {
             this.logger.error({ error }, `[${this.provider}] Image generation failed`);
+            const generationError = error instanceof Error ? error : new Error(String(error));
+            const errorCode =
+                (error as { code?: unknown })?.code === 'content_policy_violation'
+                    ? 'content_policy_violation'
+                    : 'validation_error';
             return {
                 result: [],
                 error: {
-                    message: error.message,
-                    code: error.code || 'GENERATION_FAILED'
-                }
+                    message: generationError.message,
+                    code: errorCode,
+                },
             };
         }
     }
 
     /**
      * Format OpenAI API errors into LlumiverseError with proper status codes and retryability.
-     * 
+     *
      * OpenAI API errors have a specific structure:
      * - APIError.status: HTTP status code (400, 401, 403, 404, 409, 422, 429, 500+)
      * - APIError.error: Error object with type, message, param, code
@@ -599,7 +680,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
      * - APIError.code: Error code (e.g., 'invalid_api_key', 'rate_limit_exceeded')
      * - APIError.param: Parameter that caused the error (optional)
      * - APIError.type: Error type (optional)
-     * 
+     *
      * Common error types:
      * - BadRequestError (400): Invalid request parameters
      * - AuthenticationError (401): Invalid API key
@@ -613,20 +694,17 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
      * - APIConnectionTimeoutError: Request timeout (no status code)
      * - LengthFinishReasonError: Response truncated due to length
      * - ContentFilterFinishReasonError: Content filtered
-     * 
+     *
      * This implementation works for:
      * - OpenAI API
      * - Azure OpenAI
      * - xAI (uses OpenAI-compatible API)
      * - Azure Foundry (OpenAI-compatible)
      * - Other OpenAI-compatible APIs
-     * 
+     *
      * @see https://platform.openai.com/docs/guides/error-codes
      */
-    public formatLlumiverseError(
-        error: unknown,
-        context: LlumiverseErrorContext
-    ): LlumiverseError {
+    public formatLlumiverseError(error: unknown, context: LlumiverseErrorContext): LlumiverseError {
         // Check if it's an OpenAI API error
         const isOpenAIError = this.isOpenAIApiError(error);
 
@@ -681,7 +759,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             context,
             error,
             httpStatusCode,
-            errorName
+            errorName,
         );
     }
 
@@ -690,22 +768,20 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
      */
     private isOpenAIApiError(error: unknown): error is APIError | OpenAIError {
         return (
-            error !== null &&
-            typeof error === 'object' &&
-            (error instanceof APIError || error instanceof OpenAIError)
+            error !== null && typeof error === 'object' && (error instanceof APIError || error instanceof OpenAIError)
         );
     }
 
     /**
      * Determine if an OpenAI API error is retryable.
-     * 
+     *
      * Retryable errors:
      * - RateLimitError (429): Rate limit exceeded, retry with backoff
      * - InternalServerError (500+): Server-side errors
      * - APIConnectionTimeoutError: Request timeout
      * - Error codes: 'timeout', 'server_error', 'service_unavailable'
      * - Status codes: 408, 429, 502, 503, 504, 529, 5xx
-     * 
+     *
      * Non-retryable errors:
      * - BadRequestError (400): Invalid request parameters
      * - AuthenticationError (401): Invalid API key
@@ -717,7 +793,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
      * - ContentFilterFinishReasonError: Content filtered
      * - Error codes: 'invalid_api_key', 'invalid_request_error', 'model_not_found'
      * - Other 4xx client errors
-     * 
+     *
      * @param error - The error object
      * @param httpStatusCode - The HTTP status code if available
      * @param errorCode - The error code if available
@@ -728,7 +804,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         error: unknown,
         httpStatusCode: number | undefined,
         errorCode: string | null | undefined,
-        errorType: string | undefined
+        errorType: string | undefined,
     ): boolean | undefined {
         // Check specific OpenAI error types by class
         if (error instanceof RateLimitError) return true;
@@ -759,7 +835,7 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
             if (errorCode === 'model_not_found') return false;
             if (errorCode === 'insufficient_quota') return false;
             if (errorCode === 'invalid_model') return false;
-            if (errorCode.includes('invalid_')) return false;
+            if (typeof errorCode === 'string' && errorCode.includes('invalid_')) return false;
         }
 
         // Check error type
@@ -787,10 +863,8 @@ export abstract class BaseOpenAIDriver extends AbstractDriver<
         // Unknown error type - let consumer decide retry strategy
         return undefined;
     }
-
 }
 
-
 function jobInfo(job: OpenAI.FineTuning.Jobs.FineTuningJob): TrainingJob {
     //validating_files`, `queued`, `running`, `succeeded`, `failed`, or `cancelled`.
     const jobStatus = job.status;
@@ -800,7 +874,9 @@ function jobInfo(job: OpenAI.FineTuning.Jobs.FineTuningJob): TrainingJob {
         status = TrainingJobStatus.succeeded;
     } else if (jobStatus === 'failed') {
         status = TrainingJobStatus.failed;
-        details = job.error ? `${job.error.code} - ${job.error.message} ${job.error.param ? " [" + job.error.param + "]" : ""}` : "error";
+        details = job.error
+            ? `${job.error.code} - ${job.error.message} ${job.error.param ? ` [${job.error.param}]` : ''}`
+            : 'error';
     } else if (jobStatus === 'cancelled') {
         status = TrainingJobStatus.cancelled;
     } else {
@@ -811,20 +887,22 @@ function jobInfo(job: OpenAI.FineTuning.Jobs.FineTuningJob): TrainingJob {
         id: job.id,
         model: job.fine_tuned_model || undefined,
         status,
-        details
-    }
+        details,
+    };
 }
 
-function mapUsage(usage?: OpenAI.Responses.ResponseUsage | null): ExecutionTokenUsage | undefined {
+function mapUsage(usage?: OpenAIUsageWithProviderDetails | null): ExecutionTokenUsage | undefined {
     if (!usage) {
         return undefined;
     }
+    const cachedTokens =
+        usage.input_tokens_details?.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? usage.cached_tokens;
     return {
         prompt: usage.input_tokens,
         result: usage.output_tokens,
         total: usage.total_tokens,
-        prompt_cached: usage.input_tokens_details?.cached_tokens ?? undefined,
-        prompt_new: usage.input_tokens - (usage.input_tokens_details?.cached_tokens ?? 0),
+        prompt_cached: cachedTokens ?? undefined,
+        prompt_new: usage.input_tokens - (cachedTokens ?? 0),
     };
 }
 
@@ -833,7 +911,7 @@ function completionResultsToText(completionResults: CompletionResult[] | undefin
         return '';
     }
     return completionResults
-        .map(r => {
+        .map((r) => {
             switch (r.type) {
                 case 'text':
                     return r.value;
@@ -842,8 +920,10 @@ function completionResultsToText(completionResults: CompletionResult[] | undefin
                 case 'image':
                     // Skip images in conversation - they're in the result
                     return '';
-                default:
-                    return String((r as any).value || '');
+                default: {
+                    const _exhaustive: never = r;
+                    return String(_exhaustive);
+                }
             }
         })
         .join('');
@@ -856,6 +936,7 @@ function createAssistantMessageFromCompletion(completion: Completion): ResponseI
     // Add assistant text message if present
     if (textContent) {
         const assistantMessage: EasyInputMessage = {
+            type: 'message',
             role: 'assistant',
             content: textContent,
         };
@@ -869,9 +950,7 @@ function createAssistantMessageFromCompletion(completion: Completion): ResponseI
                 type: 'function_call',
                 call_id: t.id,
                 name: t.tool_name,
-                arguments: typeof t.tool_input === 'string'
-                    ? t.tool_input
-                    : JSON.stringify(t.tool_input ?? {}),
+                arguments: typeof t.tool_input === 'string' ? t.tool_input : JSON.stringify(t.tool_input ?? {}),
             };
             result.push(functionCall);
         }
@@ -880,23 +959,31 @@ function createAssistantMessageFromCompletion(completion: Completion): ResponseI
     return result;
 }
 
-function mapResponseStream(stream: AsyncIterable<OpenAI.Responses.ResponseStreamEvent>): AsyncIterable<CompletionChunkObject> {
-    const toolCallMetadata = new Map<string, { syntheticId: string, name?: string }>();
+export function mapResponseStream(
+    stream: AsyncIterable<OpenAI.Responses.ResponseStreamEvent>,
+): AsyncIterable<CompletionChunkObject> {
+    const toolCallMetadata = new Map<string, { syntheticId: string; callId?: string; name?: string }>();
 
     return {
         async *[Symbol.asyncIterator]() {
+            let hasTextDeltas = false;
+            let refusalText = '';
             for await (const event of stream) {
                 if (event.type === 'response.output_item.added' && event.item.type === 'function_call') {
                     const syntheticId = `tool_${event.output_index}`;
-                    const actualId = event.item.id ?? event.item.call_id;
-                    if (actualId) {
-                        toolCallMetadata.set(actualId, { syntheticId, name: event.item.name });
+                    const callId = event.item.call_id ?? event.item.id;
+                    const metadata = { syntheticId, callId, name: event.item.name };
+                    if (event.item.id) {
+                        toolCallMetadata.set(event.item.id, metadata);
+                    }
+                    if (event.item.call_id) {
+                        toolCallMetadata.set(event.item.call_id, metadata);
                     }
-                    const toolUse: ToolUse & { _actual_id?: string } = {
+                    const toolUse: ToolUse<unknown> & { _actual_id?: string } = {
                         id: syntheticId,
-                        _actual_id: actualId,
+                        _actual_id: callId,
                         tool_name: event.item.name,
-                        tool_input: '' as any,
+                        tool_input: '',
                     };
                     yield {
                         result: [],
@@ -905,11 +992,12 @@ function mapResponseStream(stream: AsyncIterable<OpenAI.Responses.ResponseStream
                 } else if (event.type === 'response.function_call_arguments.delta') {
                     const metadata = toolCallMetadata.get(event.item_id);
                     const syntheticId = metadata?.syntheticId ?? `tool_${event.output_index}`;
-                    const toolUse: ToolUse & { _actual_id?: string } = {
+                    const callId = metadata?.callId ?? event.item_id;
+                    const toolUse: ToolUse<unknown> & { _actual_id?: string } = {
                         id: syntheticId,
-                        _actual_id: event.item_id,
+                        _actual_id: callId,
                         tool_name: metadata?.name ?? '',
-                        tool_input: event.delta as any,
+                        tool_input: event.delta,
                     };
                     yield {
                         result: [],
@@ -925,16 +1013,36 @@ function mapResponseStream(stream: AsyncIterable<OpenAI.Responses.ResponseStream
                     const syntheticId = metadata?.syntheticId ?? `tool_${event.output_index}`;
                     const tool_name = metadata?.name ?? event.name ?? '';
                     if (event.item_id) {
-                        toolCallMetadata.set(event.item_id, { syntheticId, name: tool_name });
+                        toolCallMetadata.set(event.item_id, { syntheticId, callId: metadata?.callId, name: tool_name });
                     }
                 } else if (event.type === 'response.output_text.delta') {
+                    hasTextDeltas = true;
                     yield {
                         result: textToCompletionResult(event.delta),
                     } satisfies CompletionChunkObject;
-                }
-                // Note: We don't emit response.output_text.done because the text was already
-                // streamed via delta events. Emitting it again would duplicate the content.
-                else if (event.type === 'response.completed' || event.type === 'response.incomplete' || event.type === 'response.failed') {
+                } else if (event.type === 'response.output_text.done') {
+                    // Fallback: some models (e.g. gpt-5 with json_schema structured output) buffer
+                    // the entire output and never emit delta events — only the done event with the
+                    // full text. Emit it here only when no deltas arrived to avoid duplication.
+                    if (!hasTextDeltas && event.text) {
+                        yield {
+                            result: textToCompletionResult(event.text),
+                        } satisfies CompletionChunkObject;
+                    }
+                } else if (event.type === 'response.refusal.delta') {
+                    refusalText += event.delta;
+                } else if (event.type === 'response.refusal.done') {
+                    throw new Error(`[OpenAI] Model refused: ${event.refusal || refusalText}`);
+                } else if ((event as { type: string }).type === 'response.error') {
+                    const errEvent = event as unknown as { message: string; code?: string | null };
+                    throw new Error(
+                        `[OpenAI Responses API] ${errEvent.message}${errEvent.code ? ` (${errEvent.code})` : ''}`,
+                    );
+                } else if (
+                    event.type === 'response.completed' ||
+                    event.type === 'response.incomplete' ||
+                    event.type === 'response.failed'
+                ) {
                     const finalTools = collectTools(event.response.output);
                     yield {
                         result: [],
@@ -943,12 +1051,12 @@ function mapResponseStream(stream: AsyncIterable<OpenAI.Responses.ResponseStream
                     } satisfies CompletionChunkObject;
                 }
             }
-        }
+        },
     };
 }
 
 function insert_image_detail(items: ResponseInputItem[], detail_level: string): ResponseInputItem[] {
-    if (detail_level === "auto" || detail_level === "low" || detail_level === "high") {
+    if (detail_level === 'auto' || detail_level === 'low' || detail_level === 'high') {
         for (const item of items) {
             // Check if it's an EasyInputMessage or Message with content array
             if ('role' in item && 'content' in item && item.role !== 'assistant') {
@@ -956,7 +1064,7 @@ function insert_image_detail(items: ResponseInputItem[], detail_level: string):
                 if (Array.isArray(content)) {
                     for (const part of content) {
                         if (typeof part === 'object' && part.type === 'input_image') {
-                            (part as any).detail = detail_level;
+                            (part as MutableInputImagePart).detail = detail_level;
                         }
                     }
                 }
@@ -968,19 +1076,19 @@ function insert_image_detail(items: ResponseInputItem[], detail_level: string):
 
 function convertRoles(items: ResponseInputItem[], model: string): ResponseInputItem[] {
     //New openai models use developer role instead of system
-    if (model.includes("o1") || model.includes("o3")) {
-        if (model.includes("o1-mini") || model.includes("o1-preview")) {
+    if (model.includes('o1') || model.includes('o3')) {
+        if (model.includes('o1-mini') || model.includes('o1-preview')) {
             //o1-mini and o1-preview support neither system nor developer
             for (const item of items) {
                 if ('role' in item && (item as EasyInputMessage).role === 'system') {
-                    (item as any).role = 'user';
+                    (item as MutableRoleItem).role = 'user';
                 }
             }
         } else {
             //Models newer than o1 use developer role
             for (const item of items) {
                 if ('role' in item && (item as EasyInputMessage).role === 'system') {
-                    (item as any).role = 'developer';
+                    (item as MutableRoleItem).role = 'developer';
                 }
             }
         }
@@ -990,12 +1098,12 @@ function convertRoles(items: ResponseInputItem[], model: string): ResponseInputI
 
 //Structured output support is typically aligned with tool use support
 //Not true for realtime models, which do not support structured output, but do support tool use.
-function supportsSchema(model: string): boolean {
-    const realtimeModel = model.includes("realtime");
+function supportsSchema(model: string, provider: string | Providers): boolean {
+    const realtimeModel = model.includes('realtime');
     if (realtimeModel) {
         return false;
     }
-    return supportsToolUse(model, "openai");
+    return supportsToolUse(model, provider);
 }
 
 /**
@@ -1004,17 +1112,17 @@ function supportsSchema(model: string): boolean {
  * tools to be defined in the API request.
  */
 export function convertOpenAIFunctionItemsToText(items: ResponseInputItem[]): ResponseInputItem[] {
-    const hasFunctionItems = items.some(item => {
-        const type = (item as any).type;
+    const hasFunctionItems = items.some((item) => {
+        const type = (item as OpenAIFunctionItem).type;
         return type === 'function_call' || type === 'function_call_output';
     });
     if (!hasFunctionItems) return items;
 
-    return items.map(item => {
-        const typed = item as any;
+    return items.map((item) => {
+        const typed = item as OpenAIFunctionItem;
         if (typed.type === 'function_call') {
             const argsStr = typed.arguments || '';
-            const truncated = argsStr.length > 500 ? argsStr.substring(0, 500) + '...' : argsStr;
+            const truncated = argsStr.length > 500 ? `${argsStr.substring(0, 500)}...` : argsStr;
             return {
                 role: 'assistant' as const,
                 content: `[Tool call: ${typed.name}(${truncated})]`,
@@ -1022,7 +1130,7 @@ export function convertOpenAIFunctionItemsToText(items: ResponseInputItem[]): Re
         }
         if (typed.type === 'function_call_output') {
             const output = typed.output || 'No output';
-            const truncated = output.length > 500 ? output.substring(0, 500) + '...' : output;
+            const truncated = output.length > 500 ? `${output.substring(0, 500)}...` : output;
             return {
                 role: 'user' as const,
                 content: `[Tool result: ${truncated}]`,
@@ -1036,15 +1144,14 @@ function getToolDefinitions(tools: ToolDefinition[] | undefined | null): OpenAI.
     return tools ? tools.map(getToolDefinition) : undefined;
 }
 function getToolDefinition(toolDef: ToolDefinition): OpenAI.Responses.FunctionTool {
-    let parsedSchema: JSONSchema | undefined = undefined;
+    let parsedSchema: JSONSchema | undefined;
     let strictMode = false;
     if (toolDef.input_schema) {
         try {
             //TODO: type assertion here is not safe, does not work with satisfies
             parsedSchema = openAISchemaFormat(toolDef.input_schema as JSONSchema);
             strictMode = true;
-        }
-        catch (e) {
+        } catch {
             //TODO: type assertion here is not safe, does not work with satisfies
             parsedSchema = limitedSchemaFormat(toolDef.input_schema as JSONSchema);
             strictMode = false;
@@ -1052,7 +1159,7 @@ function getToolDefinition(toolDef: ToolDefinition): OpenAI.Responses.FunctionTo
     }
 
     return {
-        type: "function",
+        type: 'function',
         name: toolDef.name,
         description: toolDef.description,
         parameters: parsedSchema ?? null,
@@ -1064,7 +1171,7 @@ function updateConversation(conversation: unknown, items: ResponseInputItem[]):
     if (!items) {
         // Unwrap array if wrapped, otherwise treat as array
         const unwrapped = unwrapConversationArray<ResponseInputItem>(conversation);
-        return unwrapped ?? (conversation as ResponseInputItem[] || []);
+        return unwrapped ?? ((conversation as ResponseInputItem[]) || []);
     }
     if (!conversation) {
         return items;
@@ -1075,12 +1182,12 @@ function updateConversation(conversation: unknown, items: ResponseInputItem[]):
     return [...convArray, ...items];
 }
 
-export function collectTools(output?: OpenAI.Responses.ResponseOutputItem[]): ToolUse[] | undefined {
+export function collectTools(output?: OpenAI.Responses.ResponseOutputItem[]): ToolUse<unknown>[] | undefined {
     if (!output) {
         return undefined;
     }
 
-    const tools: ToolUse[] = [];
+    const tools: ToolUse<unknown>[] = [];
     for (const item of output) {
         if (item.type === 'function_call') {
             const id = item.call_id || item.id;
@@ -1113,8 +1220,8 @@ function extractCompletionResults(output?: OpenAI.Responses.ResponseOutputItem[]
             for (const part of item.content) {
                 if (part.type === 'output_text' && part.text) {
                     results.push({
-                        type: "text",
-                        value: part.text
+                        type: 'text',
+                        value: part.text,
                     });
                 }
             }
@@ -1122,12 +1229,10 @@ function extractCompletionResults(output?: OpenAI.Responses.ResponseOutputItem[]
             // GPT-image models return base64 encoded images in result field
             const base64Data = item.result;
             // Format as data URL for consistency with other image outputs
-            const imageUrl = base64Data.startsWith('data:')
-                ? base64Data
-                : `data:image/png;base64,${base64Data}`;
+            const imageUrl = base64Data.startsWith('data:') ? base64Data : `data:image/png;base64,${base64Data}`;
             results.push({
-                type: "image",
-                value: imageUrl
+                type: 'image',
+                value: imageUrl,
             });
         }
     }
@@ -1136,7 +1241,7 @@ function extractCompletionResults(output?: OpenAI.Responses.ResponseOutputItem[]
 
 //For strict mode false
 function limitedSchemaFormat(schema: JSONSchema): JSONSchema {
-    const formattedSchema = { ...schema };
+    const formattedSchema: JSONSchema = { ...schema };
 
     // Defaults not supported
     delete formattedSchema.default;
@@ -1177,16 +1282,16 @@ function limitedSchemaFormat(schema: JSONSchema): JSONSchema {
 //For strict mode true
 function openAISchemaFormat(schema: JSONSchema, nesting: number = 0): JSONSchema {
     if (nesting > 5) {
-        throw new Error("OpenAI schema nesting too deep");
+        throw new Error('OpenAI schema nesting too deep');
     }
 
-    const formattedSchema = { ...schema };
+    const formattedSchema: JSONSchema = { ...schema };
 
     // Defaults not supported
     delete formattedSchema.default;
 
     // Additional properties not supported, required to be set.
-    if (formattedSchema?.type === "object") {
+    if (formattedSchema?.type === 'object') {
         formattedSchema.additionalProperties = false;
     }
 
@@ -1215,18 +1320,24 @@ function openAISchemaFormat(schema: JSONSchema, nesting: number = 0): JSONSchema
             }
         }
     }
-    if (formattedSchema?.type === 'object' && (!formattedSchema?.properties || Object.keys(formattedSchema?.properties ?? {}).length == 0)) {
+    if (
+        formattedSchema?.type === 'object' &&
+        (!formattedSchema?.properties || Object.keys(formattedSchema?.properties ?? {}).length === 0)
+    ) {
         //If no properties are defined, then additionalProperties: true was set or the object would be empty.
         //OpenAI does not support this on structured output/ strict mode.
-        throw new Error("OpenAI does not support empty objects or objects with additionalProperties set to true");
+        throw new Error('OpenAI does not support empty objects or objects with additionalProperties set to true');
     }
 
-    return formattedSchema
+    return formattedSchema;
 }
 
-function responseFinishReason(response: OpenAI.Responses.Response, tools?: ToolUse[] | undefined): string | undefined {
+function responseFinishReason(
+    response: OpenAI.Responses.Response,
+    tools?: ToolUse<unknown>[] | undefined,
+): string | undefined {
     if (tools && tools.length > 0) {
-        return "tool_use";
+        return 'tool_use';
     }
     if (response.status === 'incomplete') {
         if (response.incomplete_details?.reason === 'max_output_tokens') {
@@ -1305,7 +1416,31 @@ export function fixOrphanedToolUse(items: ResponseInputItem[]): ResponseInputIte
     return result;
 }
 
-function safeJsonParse(value: unknown): any {
+/**
+ * Drop function_call_output items whose call_id has no matching function_call
+ * item anywhere in the input. Mirror of {@link fixOrphanedToolUse}: that
+ * synthesizes outputs for calls left unanswered (e.g. a cancelled run); this
+ * removes outputs left dangling after their function_call was dropped (e.g. by
+ * conversation compaction/trimming). The OpenAI Responses API requires every
+ * function_call_output to reference a prior function_call's call_id.
+ */
+export function fixOrphanedToolResults(items: ResponseInputItem[]): ResponseInputItem[] {
+    if (items.length === 0) return items;
+    const callIds = new Set<string>();
+    for (const item of items) {
+        if ('type' in item && item.type === 'function_call') {
+            callIds.add(item.call_id);
+        }
+    }
+    return items.filter((item) => {
+        if ('type' in item && item.type === 'function_call_output') {
+            return callIds.has(item.call_id);
+        }
+        return true;
+    });
+}
+
+function safeJsonParse(value: unknown): unknown {
     if (typeof value !== 'string') {
         return value;
     }