graphlit-client 1.0.20260406002 → 1.0.20260408001

package/dist/client.d.ts

@@ -3057,6 +3057,10 @@ declare class Graphlit {
      * Fallback to non-streaming when streaming is not available
      */
     private fallbackToNonStreaming;
+    /**
+     * Stream with OpenAI client
+     */
+    private streamWithOpenAIResponses;
     /**
      * Stream with OpenAI client
      */

package/dist/client.js

@@ -6,13 +6,14 @@ import { RetryLink } from "@apollo/client/link/retry/index.js";
 import { attachPartialErrors } from "./partial-errors.js";
 import * as Types from "./generated/graphql-types.js";
 import * as Documents from "./generated/graphql-documents.js";
-import { getServiceType, getModelName, getModelEnum } from "./model-mapping.js";
+import { getServiceType, getModelName, getModelEnum, isOpenAIResponsesEligibleModel, } from "./model-mapping.js";
 import { StuckDetector } from "./helpers/stuck-detector.js";
 import { TurnEvaluator } from "./helpers/turn-evaluator.js";
 import { TokenBudgetTracker, truncateToolResult, windowToolRounds, estimateTokens, DEFAULT_CONTEXT_STRATEGY, } from "./helpers/context-management.js";
 import { ProviderError } from "./types/internal.js";
 import { UIEventAdapter } from "./streaming/ui-event-adapter.js";
-import { formatMessagesForOpenAI, formatMessagesForAnthropic, formatMessagesForGoogle, formatMessagesForMistral, formatMessagesForBedrock, } from "./streaming/llm-formatters.js";
+import { formatMessagesForOpenAI, formatMessagesForOpenAIResponsesInitialRound, extractInstructionsForOpenAIResponses, buildResponsesFunctionCallOutputItems, formatToolsForOpenAIResponses, formatMessagesForAnthropic, formatMessagesForGoogle, formatMessagesForMistral, formatMessagesForBedrock, } from "./streaming/llm-formatters.js";
+import { streamWithOpenAIResponses, } from "./streaming/openai-responses.js";
 import { streamWithOpenAI, streamWithAnthropic, streamWithGoogle, streamWithGroq, streamWithCerebras, streamWithCohere, streamWithMistral, streamWithBedrock, streamWithDeepseek, streamWithXai, } from "./streaming/providers.js";
 // Optional imports for streaming LLM clients
 // These are peer dependencies and may not be installed
@@ -50,6 +51,9 @@ function normalizeToolCallForExecution(toolCall) {
         firstStatusAt: toolCall.firstStatusAt ?? undefined,
     };
 }
+// Temporary rollout guard: keep default OpenAI Responses routing off until we
+// intentionally flip the switch. Explicit `useResponsesApi: true` still forces it.
+const OPENAI_RESPONSES_AUTO_ROUTING_ENABLED = false;
 function buildConversationToolCallFromResult(toolResult) {
     return {
         __typename: "ConversationToolCall",
@@ -5650,7 +5654,7 @@ class Graphlit {
                 });
                 // Start the streaming conversation
                 // fullSpec is guaranteed non-null here — the !fullSpec check above returns early
-                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, options?.contextStrategy, options?.instructions, options?.scratchpad, options?.skills);
+                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, options?.contextStrategy, options?.useResponsesApi, options?.instructions, options?.scratchpad, options?.skills);
             }, abortSignal);
         }
         catch (error) {
@@ -5696,7 +5700,7 @@ class Graphlit {
     /**
      * Execute the streaming agent workflow with tool calling loop
      */
-    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, contextStrategy, instructions, scratchpad, skills) {
+    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, contextStrategy, useResponsesApi, instructions, scratchpad, skills) {
         // Collects artifact content IDs from tool handlers (e.g. code_execution).
         // Handlers register async ingestion promises; we await all of them before
         // completeConversation so the IDs are available without blocking the LLM.
@@ -5868,6 +5872,7 @@ class Graphlit {
             contextStrategy: mergedStrategy,
             maxRounds,
             abortSignal,
+            useResponsesApi,
             correlationId,
             persona,
             mimeType,
@@ -5928,7 +5933,7 @@ class Graphlit {
      * Shared between streamAgent (single turn) and runAgent (multi-turn harness).
      */
     async executeStreamingLoop(config) {
-        const { conversationId, specification, tools, toolHandlers, uiAdapter, budgetTracker, contextStrategy: { toolResultTokenLimit, toolRoundLimit, rebudgetThreshold }, maxRounds, abortSignal, mimeType, data, correlationId, persona, } = config;
+        const { conversationId, specification, tools, toolHandlers, uiAdapter, budgetTracker, contextStrategy: { toolResultTokenLimit, toolRoundLimit, rebudgetThreshold }, maxRounds, abortSignal, useResponsesApi, mimeType, data, correlationId, persona, } = config;
         let messages = config.messages;
         let currentRound = 0;
         let fullMessage = "";
@@ -5951,8 +5956,14 @@ class Graphlit {
             },
         };
         const serviceType = getServiceType(specification);
+        const useOpenAIResponses = (useResponsesApi === true ||
+            (OPENAI_RESPONSES_AUTO_ROUTING_ENABLED && useResponsesApi !== false)) &&
+            serviceType === Types.ModelServiceTypes.OpenAi &&
+            isOpenAIResponsesEligibleModel(specification);
         const toolMessagesStartIndex = messages.length;
         let lastRoundReasoning;
+        let openAIResponsesState;
+        let openAIResponsesPendingToolMessages = [];
         if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING && budgetTracker) {
             console.log(`📊 [Context Management] Initialized budget tracker: ${budgetTracker.usagePercent}% used, ` +
                 `${budgetTracker.remaining.toLocaleString()} tokens remaining. ` +
@@ -5970,6 +5981,10 @@ class Graphlit {
                     const beforeCount = messages.length;
                     messages = windowToolRounds(messages, toolRoundLimit);
                     budgetTracker.resetFromMessages(messages);
+                    if (useOpenAIResponses) {
+                        openAIResponsesState = undefined;
+                        openAIResponsesPendingToolMessages = [];
+                    }
                     const afterUsage = budgetTracker.usagePercent;
                     const droppedRounds = Math.max(0, Math.floor((beforeCount - messages.length) / 2));
                     if (droppedRounds > 0) {
@@ -6018,22 +6033,44 @@ class Graphlit {
                     if (serviceType === Types.ModelServiceTypes.OpenAi &&
                         (OpenAI || this.openaiClient)) {
                         if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
-                            console.log(`\n✅ [Streaming] Using OpenAI native streaming (Round ${currentRound})`);
+                            console.log(`\n✅ [Streaming] Using OpenAI ${useOpenAIResponses ? "Responses" : "native"} streaming (Round ${currentRound})`);
                         }
-                        const openaiMessages = formatMessagesForOpenAI(messages);
-                        if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING_MESSAGES) {
-                            console.log(`🔍 [OpenAI] Sending ${openaiMessages.length} messages to LLM: ${JSON.stringify(openaiMessages)}`);
+                        if (useOpenAIResponses) {
+                            if (!openAIResponsesState) {
+                                openAIResponsesState = {
+                                    instructions: extractInstructionsForOpenAIResponses(messages),
+                                    initialInput: formatMessagesForOpenAIResponsesInitialRound(messages),
+                                    continuationItems: [],
+                                };
+                            }
+                            if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING_MESSAGES) {
+                                console.log(`🔍 [OpenAI Responses] Sending ${openAIResponsesState.initialInput.length} initial items and ${openAIResponsesState.continuationItems.length} continuation items`);
+                            }
+                            const responsesResult = await this.streamWithOpenAIResponses(specification, messages, openAIResponsesPendingToolMessages, tools, uiAdapter, abortSignal, openAIResponsesState);
+                            roundMessage = responsesResult.message;
+                            toolCalls = responsesResult.toolCalls;
+                            openAIResponsesState = responsesResult.state;
+                            if (responsesResult.usage) {
+                                uiAdapter.setUsageData(responsesResult.usage);
+                            }
+                            openAIResponsesPendingToolMessages = [];
                         }
-                        await this.streamWithOpenAI(specification, openaiMessages, tools, uiAdapter, (message, calls, usage, reasoning) => {
-                            roundMessage = message;
-                            toolCalls = calls;
-                            roundReasoning = reasoning;
-                            if (usage) {
-                                uiAdapter.setUsageData(usage);
+                        else {
+                            const openaiMessages = formatMessagesForOpenAI(messages);
+                            if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING_MESSAGES) {
+                                console.log(`🔍 [OpenAI] Sending ${openaiMessages.length} messages to LLM: ${JSON.stringify(openaiMessages)}`);
                             }
-                        }, abortSignal);
+                            await this.streamWithOpenAI(specification, openaiMessages, tools, uiAdapter, (message, calls, usage, reasoning) => {
+                                roundMessage = message;
+                                toolCalls = calls;
+                                roundReasoning = reasoning;
+                                if (usage) {
+                                    uiAdapter.setUsageData(usage);
+                                }
+                            }, abortSignal);
+                        }
                         if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
-                            console.log(`\n🏁 [Streaming] OpenAI native streaming completed (Round ${currentRound})`);
+                            console.log(`\n🏁 [Streaming] OpenAI ${useOpenAIResponses ? "Responses" : "native"} streaming completed (Round ${currentRound})`);
                         }
                     }
                     else if (serviceType === Types.ModelServiceTypes.Anthropic &&
@@ -6620,6 +6657,11 @@ class Graphlit {
                         budgetTracker.addMessage(executionResult.budgetText);
                     }
                 }
+                if (useOpenAIResponses) {
+                    openAIResponsesPendingToolMessages = toolExecutionResults
+                        .map((executionResult) => executionResult?.toolMessage)
+                        .filter((message) => message != null);
+                }
             }
             // Emit context window usage after each tool round
             if (budgetTracker) {
@@ -7074,6 +7116,7 @@ class Graphlit {
                         contextStrategy: mergedStrategy,
                         maxRounds: DEFAULT_MAX_TOOL_ROUNDS,
                         abortSignal,
+                        useResponsesApi: options?.useResponsesApi,
                         correlationId: options?.correlationId,
                         persona: options?.persona,
                     });
@@ -7558,6 +7601,52 @@ class Graphlit {
             }
         }
     }
+    /**
+     * Stream with OpenAI client
+     */
+    async streamWithOpenAIResponses(specification, messages, toolMessages, tools, uiAdapter, abortSignal, state) {
+        if (!OpenAI && !this.openaiClient) {
+            throw new Error("OpenAI client not available");
+        }
+        const openaiClient = this.openaiClient ||
+            (OpenAI
+                ? new OpenAI({
+                    apiKey: process.env.OPENAI_API_KEY || "",
+                    maxRetries: 3,
+                    timeout: 60000,
+                })
+                : (() => {
+                    throw new Error("OpenAI module not available");
+                })());
+        const reasoningEffort = specification.openAI?.reasoningEffort || undefined;
+        const toolDefinitions = formatToolsForOpenAIResponses(tools);
+        const baseState = state || {
+            instructions: extractInstructionsForOpenAIResponses(messages),
+            initialInput: formatMessagesForOpenAIResponsesInitialRound(messages),
+            continuationItems: [],
+        };
+        const functionCallOutputs = buildResponsesFunctionCallOutputItems(toolMessages);
+        const input = [
+            ...baseState.initialInput,
+            ...baseState.continuationItems,
+            ...functionCallOutputs,
+        ];
+        const response = await streamWithOpenAIResponses(specification, baseState.instructions, input, toolDefinitions, openaiClient, (event) => uiAdapter.handleEvent(event), abortSignal, reasoningEffort);
+        return {
+            message: response.message,
+            toolCalls: response.toolCalls,
+            usage: response.usage,
+            state: {
+                instructions: baseState.instructions,
+                initialInput: baseState.initialInput,
+                continuationItems: [
+                    ...baseState.continuationItems,
+                    ...functionCallOutputs,
+                    ...response.outputItems,
+                ],
+            },
+        };
+    }
     /**
      * Stream with OpenAI client
      */

package/dist/generated/graphql-documents.js

@@ -16597,6 +16597,7 @@ export const CreatePersona = gql `
     id
     name
     state
+    type
     identifier
     platform
     displayName
@@ -16644,6 +16645,7 @@ export const GetPersona = gql `
       id
     }
     state
+    type
     user {
       id
     }
@@ -16673,6 +16675,7 @@ export const QueryPersonas = gql `
         id
       }
       state
+      type
       identifier
       platform
       displayName
@@ -16693,6 +16696,7 @@ export const UpdatePersona = gql `
     id
     name
     state
+    type
     identifier
     platform
     displayName
@@ -18989,6 +18993,7 @@ export const GetUser = gql `
       id
       name
       state
+      type
       identifier
       platform
       displayName
@@ -19117,6 +19122,7 @@ export const GetUserByIdentifier = gql `
       id
       name
       state
+      type
       identifier
       platform
       displayName
@@ -19246,6 +19252,7 @@ export const QueryUsers = gql `
         id
         name
         state
+        type
         identifier
         platform
         displayName

package/dist/generated/graphql-types.d.ts

@@ -19156,7 +19156,7 @@ export type PersonUpdateInput = {
     /** The person URI. */
     uri?: InputMaybe<Scalars['URL']['input']>;
 };
-/** Represents a user persona for per-user agent personalization. */
+/** Represents a persona for user or agent personalization. */
 export type Persona = {
     __typename?: 'Persona';
     /** The creation date of the persona. */
@@ -19187,6 +19187,8 @@ export type Persona = {
     state: EntityState;
     /** The IANA timezone of the persona. */
     timezone?: Maybe<Scalars['String']['output']>;
+    /** The type of the persona. */
+    type?: Maybe<PersonaTypes>;
     /** The user that created the entity. */
     user?: Maybe<EntityReference>;
 };
@@ -19220,6 +19222,8 @@ export type PersonaFilter = {
     search?: InputMaybe<Scalars['String']['input']>;
     /** Filter persona(s) by their states. */
     states?: InputMaybe<Array<EntityState>>;
+    /** Filter by persona type. */
+    types?: InputMaybe<Array<PersonaTypes>>;
 };
 /** Represents a persona. */
 export type PersonaInput = {
@@ -19237,6 +19241,8 @@ export type PersonaInput = {
     role?: InputMaybe<Scalars['String']['input']>;
     /** The IANA timezone of the persona. */
     timezone?: InputMaybe<Scalars['String']['input']>;
+    /** The type of the persona. Defaults to User. */
+    type?: InputMaybe<PersonaTypes>;
 };
 /** Represents persona query results. */
 export type PersonaResults = {
@@ -19244,6 +19250,13 @@ export type PersonaResults = {
     /** The list of persona query results. */
     results?: Maybe<Array<Persona>>;
 };
+/** Persona type */
+export declare enum PersonaTypes {
+    /** Agent persona */
+    Agent = "AGENT",
+    /** User persona */
+    User = "USER"
+}
 /** Represents a persona. */
 export type PersonaUpdateInput = {
     /** The display name of the persona. */
@@ -19262,6 +19275,8 @@ export type PersonaUpdateInput = {
     role?: InputMaybe<Scalars['String']['input']>;
     /** The IANA timezone of the persona. */
     timezone?: InputMaybe<Scalars['String']['input']>;
+    /** The type of the persona. */
+    type?: InputMaybe<PersonaTypes>;
 };
 /** Represents a place. */
 export type Place = {
@@ -44898,6 +44913,7 @@ export type CreatePersonaMutation = {
         id: string;
         name: string;
         state: EntityState;
+        type?: PersonaTypes | null;
         identifier?: string | null;
         platform?: string | null;
         displayName?: string | null;
@@ -44954,6 +44970,7 @@ export type GetPersonaQuery = {
         creationDate: any;
         modifiedDate?: any | null;
         state: EntityState;
+        type?: PersonaTypes | null;
         identifier?: string | null;
         platform?: string | null;
         displayName?: string | null;
@@ -44991,6 +45008,7 @@ export type QueryPersonasQuery = {
             modifiedDate?: any | null;
             relevance?: number | null;
             state: EntityState;
+            type?: PersonaTypes | null;
             identifier?: string | null;
             platform?: string | null;
             displayName?: string | null;
@@ -45019,6 +45037,7 @@ export type UpdatePersonaMutation = {
         id: string;
         name: string;
         state: EntityState;
+        type?: PersonaTypes | null;
         identifier?: string | null;
         platform?: string | null;
         displayName?: string | null;
@@ -47762,6 +47781,7 @@ export type GetUserQuery = {
             id: string;
             name: string;
             state: EntityState;
+            type?: PersonaTypes | null;
             identifier?: string | null;
             platform?: string | null;
             displayName?: string | null;
@@ -47915,6 +47935,7 @@ export type GetUserByIdentifierQuery = {
             id: string;
             name: string;
             state: EntityState;
+            type?: PersonaTypes | null;
             identifier?: string | null;
             platform?: string | null;
             displayName?: string | null;
@@ -48071,6 +48092,7 @@ export type QueryUsersQuery = {
                 id: string;
                 name: string;
                 state: EntityState;
+                type?: PersonaTypes | null;
                 identifier?: string | null;
                 platform?: string | null;
                 displayName?: string | null;

package/dist/generated/graphql-types.js

@@ -2858,6 +2858,14 @@ export var PersonFacetTypes;
     /** Creation Date */
     PersonFacetTypes["CreationDate"] = "CREATION_DATE";
 })(PersonFacetTypes || (PersonFacetTypes = {}));
+/** Persona type */
+export var PersonaTypes;
+(function (PersonaTypes) {
+    /** Agent persona */
+    PersonaTypes["Agent"] = "AGENT";
+    /** User persona */
+    PersonaTypes["User"] = "USER";
+})(PersonaTypes || (PersonaTypes = {}));
 /** Place facet types */
 export var PlaceFacetTypes;
 (function (PlaceFacetTypes) {

package/dist/model-mapping.d.ts

@@ -22,3 +22,9 @@ export declare function getServiceType(specification: any): string | undefined;
  * @returns The model enum value
  */
 export declare function getModelEnum(specification: any): string | undefined;
+/**
+ * Check whether an OpenAI specification should use the Responses API path.
+ * Eligible models are GPT-5.4 and newer.
+ */
+export declare function isOpenAIResponsesEligibleModel(specification: any): boolean;
+export declare const shouldUseOpenAIResponsesModel: typeof isOpenAIResponsesEligibleModel;

package/dist/model-mapping.js

@@ -66,6 +66,14 @@ const OPENAI_MODEL_MAP = {
     [Types.OpenAiModels.O4Mini_200K]: "o4-mini",
     [Types.OpenAiModels.O4Mini_200K_20250416]: "o4-mini-2025-04-16",
 };
+const OPENAI_RESPONSES_MODEL_ENUMS = new Set([
+    Types.OpenAiModels.Gpt54_1024K,
+    Types.OpenAiModels.Gpt54_1024K_20260305,
+    Types.OpenAiModels.Gpt54Mini_400K,
+    Types.OpenAiModels.Gpt54Mini_400K_20260317,
+    Types.OpenAiModels.Gpt54Nano_400K,
+    Types.OpenAiModels.Gpt54Nano_400K_20260317,
+]);
 // Anthropic model mappings
 const ANTHROPIC_MODEL_MAP = {
     // Claude 3 models
@@ -342,3 +350,31 @@ export function getModelEnum(specification) {
             return undefined;
     }
 }
+/**
+ * Check whether an OpenAI specification should use the Responses API path.
+ * Eligible models are GPT-5.4 and newer.
+ */
+export function isOpenAIResponsesEligibleModel(specification) {
+    if (specification?.serviceType !== Types.ModelServiceTypes.OpenAi) {
+        return false;
+    }
+    const modelEnum = getModelEnum(specification);
+    if (modelEnum && OPENAI_RESPONSES_MODEL_ENUMS.has(modelEnum)) {
+        return true;
+    }
+    const modelName = getModelName(specification);
+    if (!modelName) {
+        return false;
+    }
+    const match = modelName.match(/^gpt-(\d+)(?:\.(\d+))?(?:-[a-z0-9]+)?(?:-\d{4}-\d{2}-\d{2})?$/);
+    if (!match) {
+        return false;
+    }
+    const major = Number(match[1]);
+    const minor = match[2] ? Number(match[2]) : 0;
+    if (!Number.isFinite(major) || !Number.isFinite(minor)) {
+        return false;
+    }
+    return major > 5 || (major === 5 && minor >= 4);
+}
+export const shouldUseOpenAIResponsesModel = isOpenAIResponsesEligibleModel;

package/dist/streaming/llm-formatters.d.ts

@@ -21,6 +21,42 @@ export interface OpenAIMessage {
     }>;
     tool_call_id?: string;
 }
+export interface OpenAIResponsesTextContentPart {
+    type: "input_text";
+    text: string;
+}
+export interface OpenAIResponsesImageContentPart {
+    type: "input_image";
+    image_url: string;
+    detail: "low" | "high" | "auto";
+}
+export type OpenAIResponsesContentPart = OpenAIResponsesTextContentPart | OpenAIResponsesImageContentPart;
+export interface OpenAIResponsesMessageItem {
+    type: "message";
+    role: "user" | "assistant";
+    content: string | OpenAIResponsesContentPart[];
+}
+export interface OpenAIResponsesFunctionCallItem {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+    id?: string;
+}
+export interface OpenAIResponsesFunctionCallOutputItem {
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+    id?: string;
+}
+export type OpenAIResponsesInputItem = OpenAIResponsesMessageItem | OpenAIResponsesFunctionCallItem | OpenAIResponsesFunctionCallOutputItem | Record<string, unknown>;
+export interface OpenAIResponsesToolDefinition {
+    type: "function";
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+    strict: false;
+}
 /**
  * Anthropic message format
  */
@@ -74,6 +110,15 @@ export interface GoogleMessage {
  * Format GraphQL conversation messages for OpenAI SDK
  */
 export declare function formatMessagesForOpenAI(messages: ConversationMessage[]): OpenAIMessage[];
+export declare function extractInstructionsForOpenAIResponses(messages: ConversationMessage[]): string | undefined;
+export declare function formatMessagesForOpenAIResponsesInitialRound(messages: ConversationMessage[]): OpenAIResponsesInputItem[];
+export declare function buildResponsesFunctionCallOutputItems(toolMessages: ConversationMessage[]): OpenAIResponsesFunctionCallOutputItem[];
+export declare const buildOpenAIResponsesFunctionCallOutputItems: typeof buildResponsesFunctionCallOutputItems;
+export declare function formatToolsForOpenAIResponses(tools: Array<{
+    name: string;
+    description?: string | null;
+    schema?: string | null;
+}> | undefined): OpenAIResponsesToolDefinition[] | undefined;
 /**
  * Format GraphQL conversation messages for Anthropic SDK
  */

package/dist/streaming/llm-formatters.js

@@ -190,6 +190,130 @@ export function formatMessagesForOpenAI(messages) {
     }
     return formattedMessages;
 }
+export function extractInstructionsForOpenAIResponses(messages) {
+    const systemMessages = messages
+        .filter((message) => message.role === ConversationRoleTypes.System)
+        .map((message) => message.message?.trim() || "")
+        .filter((message) => message.length > 0);
+    return systemMessages.length > 0
+        ? systemMessages.join("\n\n")
+        : undefined;
+}
+export function formatMessagesForOpenAIResponsesInitialRound(messages) {
+    const formattedMessages = [];
+    for (const message of messages) {
+        if (!message.role || message.role === ConversationRoleTypes.System) {
+            continue;
+        }
+        const trimmedMessage = message.message?.trim() || "";
+        const hasToolCalls = !!message.toolCalls?.length;
+        if (!trimmedMessage && !hasToolCalls) {
+            continue;
+        }
+        switch (message.role) {
+            case ConversationRoleTypes.Assistant: {
+                if (trimmedMessage) {
+                    formattedMessages.push({
+                        type: "message",
+                        role: "assistant",
+                        content: trimmedMessage,
+                    });
+                }
+                if (message.toolCalls?.length) {
+                    for (const toolCall of message.toolCalls) {
+                        if (!toolCall) {
+                            continue;
+                        }
+                        formattedMessages.push({
+                            type: "function_call",
+                            id: toolCall.id,
+                            call_id: toolCall.id,
+                            name: toolCall.name,
+                            arguments: toolCall.arguments,
+                        });
+                    }
+                }
+                break;
+            }
+            case ConversationRoleTypes.Tool: {
+                if (!message.toolCallId) {
+                    continue;
+                }
+                formattedMessages.push({
+                    type: "function_call_output",
+                    call_id: message.toolCallId,
+                    output: stripImagesToText(trimmedMessage),
+                });
+                break;
+            }
+            default: {
+                if (message.mimeType && message.data) {
+                    const contentParts = [];
+                    if (trimmedMessage) {
+                        contentParts.push({
+                            type: "input_text",
+                            text: trimmedMessage,
+                        });
+                    }
+                    contentParts.push({
+                        type: "input_image",
+                        image_url: `data:${message.mimeType};base64,${message.data}`,
+                        detail: "auto",
+                    });
+                    formattedMessages.push({
+                        type: "message",
+                        role: "user",
+                        content: contentParts,
+                    });
+                }
+                else {
+                    formattedMessages.push({
+                        type: "message",
+                        role: "user",
+                        content: trimmedMessage,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return formattedMessages;
+}
+export function buildResponsesFunctionCallOutputItems(toolMessages) {
+    return toolMessages
+        .filter((message) => message.role === ConversationRoleTypes.Tool &&
+        typeof message.toolCallId === "string" &&
+        message.toolCallId.length > 0)
+        .map((message) => ({
+        type: "function_call_output",
+        call_id: message.toolCallId,
+        output: stripImagesToText(message.message?.trim() || ""),
+    }));
+}
+export const buildOpenAIResponsesFunctionCallOutputItems = buildResponsesFunctionCallOutputItems;
+export function formatToolsForOpenAIResponses(tools) {
+    if (!tools?.length) {
+        return undefined;
+    }
+    return tools.map((tool) => {
+        let parameters = {};
+        if (tool.schema) {
+            try {
+                parameters = JSON.parse(tool.schema);
+            }
+            catch {
+                parameters = {};
+            }
+        }
+        return {
+            type: "function",
+            name: tool.name,
+            description: tool.description || undefined,
+            parameters,
+            strict: false,
+        };
+    });
+}
 /**
  * Format GraphQL conversation messages for Anthropic SDK
  */

package/dist/streaming/openai-responses.d.ts

@@ -0,0 +1,10 @@
+import { ConversationToolCall, Specification } from "../generated/graphql-types.js";
+import { StreamEvent } from "../types/internal.js";
+import type { OpenAIResponsesInputItem, OpenAIResponsesToolDefinition } from "./llm-formatters.js";
+export interface OpenAIResponsesRoundResult {
+    message: string;
+    toolCalls: ConversationToolCall[];
+    usage?: unknown;
+    outputItems: OpenAIResponsesInputItem[];
+}
+export declare function streamWithOpenAIResponses(specification: Specification, instructions: string | undefined, input: OpenAIResponsesInputItem[], tools: OpenAIResponsesToolDefinition[] | undefined, openaiClient: any, onEvent: (event: StreamEvent) => void, abortSignal?: AbortSignal, reasoningEffort?: string): Promise<OpenAIResponsesRoundResult>;

package/dist/streaming/openai-responses.js

@@ -0,0 +1,221 @@
+import { getModelName } from "../model-mapping.js";
+import { ProviderError, extractRequestId, isNetworkError, isRateLimitError, isRetryableServerError, } from "../types/internal.js";
+function toToolCallId(item, outputIndex) {
+    return item.call_id || item.id || `tool_${Date.now()}_${outputIndex}`;
+}
+export async function streamWithOpenAIResponses(specification, instructions, input, tools, openaiClient, onEvent, abortSignal, reasoningEffort) {
+    let fullMessage = "";
+    let tokenCount = 0;
+    let usageData;
+    let outputItems = [];
+    const toolCallsByIndex = new Map();
+    const toolCallIdsByItemId = new Map();
+    const startedToolCallIds = new Set();
+    const parsedToolCallIds = new Set();
+    const getOrCreateToolCall = (outputIndex, item) => {
+        const existing = toolCallsByIndex.get(outputIndex);
+        if (existing) {
+            if (item?.name) {
+                existing.name = item.name;
+            }
+            if (typeof item?.arguments === "string" && !existing.arguments) {
+                existing.arguments = item.arguments;
+            }
+            return existing;
+        }
+        const toolCall = {
+            __typename: "ConversationToolCall",
+            id: toToolCallId(item || {}, outputIndex),
+            name: item?.name || "",
+            arguments: item?.arguments || "",
+        };
+        toolCallsByIndex.set(outputIndex, toolCall);
+        if (item?.id) {
+            toolCallIdsByItemId.set(item.id, toolCall.id);
+        }
+        return toolCall;
+    };
+    const emitToolCallStartIfNeeded = (toolCall) => {
+        if (startedToolCallIds.has(toolCall.id)) {
+            return;
+        }
+        startedToolCallIds.add(toolCall.id);
+        onEvent({
+            type: "tool_call_start",
+            toolCall: {
+                id: toolCall.id,
+                name: toolCall.name,
+            },
+        });
+    };
+    const emitToolCallParsedIfNeeded = (toolCall) => {
+        if (!toolCall.arguments || parsedToolCallIds.has(toolCall.id)) {
+            return;
+        }
+        parsedToolCallIds.add(toolCall.id);
+        onEvent({
+            type: "tool_call_parsed",
+            toolCall: {
+                id: toolCall.id,
+                name: toolCall.name,
+                arguments: toolCall.arguments,
+            },
+        });
+    };
+    try {
+        const modelName = getModelName(specification);
+        if (!modelName) {
+            throw new Error(`No model name found for specification: ${specification.name} (service: ${specification.serviceType})`);
+        }
+        const request = {
+            model: modelName,
+            input,
+            stream: true,
+            store: false,
+            include: ["reasoning.encrypted_content"],
+        };
+        if (instructions?.trim()) {
+            request.instructions = instructions.trim();
+        }
+        if (specification.openAI?.temperature !== undefined) {
+            request.temperature = specification.openAI.temperature;
+        }
+        if (specification.openAI?.completionTokenLimit) {
+            request.max_output_tokens = specification.openAI.completionTokenLimit;
+        }
+        if (tools?.length) {
+            request.tools = tools;
+        }
+        if (reasoningEffort) {
+            request.reasoning = { effort: reasoningEffort.toLowerCase() };
+        }
+        const stream = await openaiClient.responses.create(request, {
+            signal: abortSignal,
+        });
+        for await (const event of stream) {
+            switch (event.type) {
+                case "response.output_text.delta":
+                    if (event.delta) {
+                        fullMessage += event.delta;
+                        tokenCount++;
+                        onEvent({ type: "token", token: event.delta });
+                    }
+                    break;
+                case "response.output_item.added": {
+                    const item = event.item;
+                    if (item?.type !== "function_call") {
+                        break;
+                    }
+                    const toolCall = getOrCreateToolCall(event.output_index, item);
+                    emitToolCallStartIfNeeded(toolCall);
+                    break;
+                }
+                case "response.function_call_arguments.delta": {
+                    const toolCallId = toolCallIdsByItemId.get(event.item_id) ||
+                        toolCallsByIndex.get(event.output_index)?.id;
+                    const toolCall = toolCallsByIndex.get(event.output_index);
+                    if (!toolCall || !toolCallId) {
+                        break;
+                    }
+                    toolCall.arguments += event.delta;
+                    onEvent({
+                        type: "tool_call_delta",
+                        toolCallId,
+                        argumentDelta: event.delta,
+                    });
+                    break;
+                }
+                case "response.function_call_arguments.done": {
+                    const toolCall = toolCallsByIndex.get(event.output_index);
+                    if (!toolCall) {
+                        break;
+                    }
+                    toolCall.arguments = event.arguments;
+                    emitToolCallParsedIfNeeded(toolCall);
+                    break;
+                }
+                case "response.output_item.done": {
+                    const item = event.item;
+                    if (item?.type !== "function_call") {
+                        break;
+                    }
+                    const toolCall = getOrCreateToolCall(event.output_index, item);
+                    if (item.id) {
+                        toolCallIdsByItemId.set(item.id, toolCall.id);
+                    }
+                    emitToolCallStartIfNeeded(toolCall);
+                    if (typeof item.arguments === "string") {
+                        toolCall.arguments = item.arguments;
+                        emitToolCallParsedIfNeeded(toolCall);
+                    }
+                    break;
+                }
+                case "response.completed":
+                    usageData = event.response?.usage;
+                    outputItems = (event.response?.output || []);
+                    if (!fullMessage && typeof event.response?.output_text === "string") {
+                        fullMessage = event.response.output_text;
+                    }
+                    break;
+                case "error":
+                case "response.error":
+                    throw new Error(event.error?.message || "OpenAI Responses streaming error");
+                case "response.failed":
+                    throw new Error(event.response?.error?.message || "OpenAI Responses request failed");
+            }
+        }
+        const orderedToolCalls = Array.from(toolCallsByIndex.entries())
+            .sort(([left], [right]) => left - right)
+            .map(([, toolCall]) => toolCall);
+        for (const toolCall of orderedToolCalls) {
+            emitToolCallParsedIfNeeded(toolCall);
+        }
+        onEvent({
+            type: "complete",
+            tokens: tokenCount,
+        });
+        return {
+            message: fullMessage,
+            toolCalls: orderedToolCalls,
+            usage: usageData,
+            outputItems,
+        };
+    }
+    catch (error) {
+        const errorMessage = error.message || error.toString();
+        if (isRateLimitError(error)) {
+            throw new ProviderError(`OpenAI rate limit exceeded: ${errorMessage}`, {
+                provider: "openai",
+                statusCode: 429,
+                retryable: true,
+                requestId: extractRequestId(error),
+                cause: error,
+            });
+        }
+        if (isNetworkError(error)) {
+            throw new ProviderError(`OpenAI network error: ${errorMessage}`, {
+                provider: "openai",
+                statusCode: error.status ?? 0,
+                retryable: true,
+                requestId: extractRequestId(error),
+                cause: error,
+            });
+        }
+        if (isRetryableServerError(error)) {
+            throw new ProviderError(`OpenAI server error: ${errorMessage}`, {
+                provider: "openai",
+                statusCode: error.status ?? error.statusCode ?? 500,
+                retryable: true,
+                requestId: extractRequestId(error),
+                cause: error,
+            });
+        }
+        throw new ProviderError(`OpenAI error: ${errorMessage}`, {
+            provider: "openai",
+            statusCode: error.status ?? error.statusCode ?? 400,
+            retryable: false,
+            requestId: extractRequestId(error),
+            cause: error,
+        });
+    }
+}

package/dist/types/agent.d.ts

@@ -66,6 +66,8 @@ export interface StreamAgentOptions {
     chunkingStrategy?: "character" | "word" | "sentence";
     smoothingDelay?: number;
     contextStrategy?: ContextStrategy;
+    /** Explicitly route eligible OpenAI GPT-5.4+ models through Responses; false forces legacy Chat Completions. */
+    useResponsesApi?: boolean;
     /** Harness-injected instructions appended to the formatted conversation (e.g. wind-down, stuck intervention). */
     instructions?: string;
     /** Harness-injected scratchpad text, merged with conversation scratchpad. Placed right before user-prompt. */
@@ -157,6 +159,7 @@ export interface RunAgentOptions {
     smoothingEnabled?: boolean;
     chunkingStrategy?: "character" | "word" | "sentence";
     smoothingDelay?: number;
+    useResponsesApi?: boolean;
     /** Skill references to inject into the agent's context window. Retrieved via querySkills, passed by reference. */
     skills?: EntityReferenceInput[];
 }
@@ -205,6 +208,7 @@ export interface StreamingLoopConfig {
     };
     maxRounds: number;
     abortSignal: AbortSignal | undefined;
+    useResponsesApi?: boolean;
     correlationId?: string;
     persona?: EntityReferenceInput;
     mimeType?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20260406002",
+  "version": "1.0.20260408001",
   "description": "Graphlit API Client for TypeScript",
   "type": "module",
   "main": "./dist/client.js",
@@ -85,7 +85,7 @@
     "cohere-ai": "^7.20.0",
     "groq-sdk": "^0.25.0",
     "js-tiktoken": "^1.0.16",
-    "openai": "^5.3.0"
+    "openai": "^5.23.2"
   },
   "devDependencies": {
     "@graphql-codegen/typescript-document-nodes": "^5.0.7",