@nexus-cortex/core 4.26.0

package/dist/adapters/ResponsesAPIAdapter.d.ts

@@ -0,0 +1,323 @@
+/**
+ * ResponsesAPIAdapter
+ *
+ * Pattern-based adapter for the /v1/responses API format (stateful conversation API).
+ *
+ * API Pattern: /v1/responses (stateful with 30-day storage)
+ * Naming: snake_case (standard)
+ * Structure: Input items with typed content blocks
+ *
+ * Phase 1.5: Multi-Provider Architecture
+ * Based on: OpenAI Responses API documentation
+ *
+ * Models using this adapter:
+ * - gpt-5-codex (400K/128K context)
+ * - codex-mini-latest
+ * - Future models using Responses API
+ *
+ * Key Differences from Chat Completions API:
+ * - Stateful: Uses previous_response_id for conversation continuity
+ * - Storage: Responses stored for 30 days
+ * - Endpoint: /v1/responses (not /v1/chat/completions)
+ * - Format: Input items array with typed content blocks
+ * - Output: Response object with output items array
+ */
+import { FormatAdapter, CanonicalTool, CanonicalToolUse, CanonicalToolResult, CanonicalMessage } from './FormatAdapter.interface.js';
+import { ModelConfig } from '../models/ModelConfig.interface.js';
+/**
+ * OpenAI Responses API Input Item (message)
+ */
+export interface OpenAIResponsesAPIMessageItem {
+    /** Item type - "message" for text/chat messages */
+    type: 'message';
+    /** Message role: user, assistant, or developer (system) */
+    role: 'user' | 'assistant' | 'developer';
+    /** Content blocks array */
+    content: OpenAIResponsesContentBlock[];
+}
+/**
+ * OpenAI Responses API Function Call Output Item
+ */
+export interface OpenAIResponsesAPIFunctionCallOutputItem {
+    /** Item type - "function_call_output" for tool results */
+    type: 'function_call_output';
+    /** The call_id from the function call */
+    call_id: string;
+    /** The output/result of the function */
+    output: string;
+}
+/**
+ * OpenAI Responses API Function Call Input Item (assistant tool request)
+ * In the Responses API, function_call is a top-level input item, not a content block.
+ */
+export interface OpenAIResponsesAPIFunctionCallItem {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+/**
+ * Union type for all input item types
+ */
+export type OpenAIResponsesAPIInputItem = OpenAIResponsesAPIMessageItem | OpenAIResponsesAPIFunctionCallItem | OpenAIResponsesAPIFunctionCallOutputItem;
+/**
+ * OpenAI Responses API Content Block
+ */
+export type OpenAIResponsesContentBlock = OpenAIResponsesInputTextBlock | OpenAIResponsesInputImageBlock | OpenAIResponsesOutputTextBlock | OpenAIResponsesFunctionCallBlock | OpenAIResponsesReasoningBlock;
+/**
+ * Input text content block
+ */
+export interface OpenAIResponsesInputTextBlock {
+    type: 'input_text';
+    text: string;
+}
+/**
+ * Input image content block
+ */
+export interface OpenAIResponsesInputImageBlock {
+    type: 'input_image';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/**
+ * Output text content block
+ */
+export interface OpenAIResponsesOutputTextBlock {
+    type: 'output_text';
+    text: string;
+}
+/**
+ * Function call content block
+ */
+export interface OpenAIResponsesFunctionCallBlock {
+    type: 'function_call';
+    id: string;
+    name: string;
+    arguments: string;
+}
+/**
+ * Reasoning content block (for o-series and gpt-5 models)
+ */
+export interface OpenAIResponsesReasoningBlock {
+    type: 'reasoning';
+    reasoning: string;
+    encrypted_content?: string;
+}
+/**
+ * OpenAI Responses API Output Item
+ */
+export interface OpenAIResponsesOutputItem {
+    /** Item type */
+    type: 'message' | 'function_call' | 'reasoning';
+    /** Message role (for message type) */
+    role?: 'assistant';
+    /** Content blocks (for message type) */
+    content?: OpenAIResponsesContentBlock[];
+    /**
+     * Function call details (for function_call type).
+     *
+     * R18c (multi-model bench finding): function_call items have BOTH `id`
+     * (opaque item id like `fc_0190...`) AND `call_id` (the call id like
+     * `call_7Ra...`). The `call_id` is what `function_call_output.call_id`
+     * matches against. The streaming path captured this correctly (see
+     * streamResponsesAPI L2132), but `fromProviderMessages` was reading
+     * `item.id` and threading it as the canonical tool_use id — so when the
+     * orchestrator later sent tool_result with that id as `call_id`, the
+     * OpenAI API rejected with "No tool output found for function call
+     * call_7Ra..." because the call_id never matched.
+     */
+    id?: string;
+    call_id?: string;
+    name?: string;
+    arguments?: string;
+    /** Reasoning content (for reasoning type) */
+    reasoning?: string;
+    encrypted_content?: string;
+}
+/**
+ * OpenAI Responses API Response Object
+ */
+export interface OpenAIResponsesResponse {
+    /** Response ID for chaining conversations */
+    id: string;
+    /** Object type - always "response" */
+    object: 'response';
+    /** Model ID used */
+    model: string;
+    /** Output items array */
+    output: OpenAIResponsesOutputItem[];
+    /** Aggregated text output (SDK convenience property) */
+    output_text?: string;
+    /** Response status */
+    status: 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete';
+    /** Error details (if failed) */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Creation timestamp */
+    created: number;
+    /** Conversation ID (if using conversations) */
+    conversation?: {
+        id: string;
+    };
+}
+/**
+ * OpenAI Responses API Tool Definition (Client-side)
+ * Similar to Functions API but in Responses context
+ */
+export interface OpenAIResponsesAPITool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: {
+            type: 'object';
+            properties?: Record<string, unknown>;
+            required?: string[];
+            [key: string]: unknown;
+        };
+    };
+}
+/**
+ * XAI Server-Side Tool Definition (for Responses API)
+ *
+ * Format for XAI's agentic server-side tools.
+ * These tools execute autonomously on the server.
+ *
+ * Examples:
+ * - { type: 'web_search' }
+ * - { type: 'x_search' }
+ * - { type: 'code_execution' }
+ */
+export interface XAIServerSideTool {
+    type: 'web_search' | 'x_search' | 'code_execution' | string;
+    config?: Record<string, unknown>;
+}
+/**
+ * OpenAI Responses Adapter
+ *
+ * Converts between canonical format and OpenAI's Responses API format.
+ * Supports stateful conversations with previous_response_id.
+ */
+export declare class ResponsesAPIAdapter implements FormatAdapter {
+    readonly name = "ResponsesAPIAdapter";
+    readonly apiPatterns: string[];
+    /**
+     * Convert canonical messages to OpenAI Responses API input items
+     *
+     * @param messages - Canonical messages
+     * @param modelConfig - Model configuration
+     * @returns OpenAI Responses input items array
+     */
+    toProviderMessages(messages: CanonicalMessage[], _modelConfig: ModelConfig): OpenAIResponsesAPIInputItem[];
+    /**
+     * Convert OpenAI Responses API output to canonical messages
+     *
+     * @param providerMessages - OpenAI Responses output items (or full response object)
+     * @param modelConfig - Model configuration
+     * @param sessionContext - Session context for timeline tracking
+     * @returns Canonical messages
+     */
+    fromProviderMessages(providerMessages: unknown[] | unknown, modelConfig: ModelConfig, sessionContext: {
+        sessionId: string;
+        conversationId: string;
+        turnNumber: number;
+    }): CanonicalMessage[];
+    /**
+     * Convert canonical tools to OpenAI Responses API tool format
+     *
+     * Handles BOTH client-side and server-side tools:
+     * - Client-side: Standard function calling format { type: 'function', function: {...} }
+     * - Server-side (XAI): Simple type format { type: 'web_search' }
+     *
+     * @param tools - Canonical tool definitions
+     * @param modelConfig - Model configuration
+     * @returns OpenAI Responses tools array (mixed client + server)
+     */
+    toProviderTools(tools: CanonicalTool[], modelConfig: ModelConfig): (OpenAIResponsesAPITool | XAIServerSideTool)[];
+    /**
+     * Convert provider tools to canonical format
+     *
+     * @param providerTools - OpenAI Responses tools array
+     * @param _modelConfig - Model configuration
+     * @returns Canonical tool definitions
+     */
+    fromProviderTools(providerTools: unknown[], _modelConfig: ModelConfig): CanonicalTool[];
+    /**
+     * Convert canonical tool use to OpenAI Responses function call
+     *
+     * @param toolUse - Canonical tool use
+     * @param modelConfig - Model configuration
+     * @returns OpenAI Responses function call
+     */
+    toProviderToolUse(toolUse: CanonicalToolUse, _modelConfig: ModelConfig): OpenAIResponsesFunctionCallBlock;
+    /**
+     * Convert OpenAI Responses function call to canonical format
+     *
+     * @param providerToolUse - OpenAI Responses function call
+     * @param modelConfig - Model configuration
+     * @returns Canonical tool use
+     */
+    fromProviderToolUse(providerToolUse: unknown, modelConfig: ModelConfig): CanonicalToolUse;
+    /**
+     * Convert canonical tool result to OpenAI Responses format
+     *
+     * Note: Responses API doesn't have a direct tool result message type.
+     * Tool results are typically sent as user messages with text content.
+     *
+     * @param toolResult - Canonical tool result
+     * @param _modelConfig - Model configuration
+     * @returns Input text block with tool result
+     */
+    toProviderToolResult(toolResult: CanonicalToolResult, _modelConfig: ModelConfig): OpenAIResponsesInputTextBlock;
+    /**
+     * Convert OpenAI Responses tool result to canonical format
+     *
+     * @param providerToolResult - OpenAI Responses tool result (text block)
+     * @param _modelConfig - Model configuration
+     * @returns Canonical tool result
+     */
+    fromProviderToolResult(providerToolResult: unknown, _modelConfig: ModelConfig): CanonicalToolResult;
+    /**
+     * Validate tool for OpenAI Responses API compatibility
+     *
+     * @param tool - Canonical tool to validate
+     * @param modelConfig - Model configuration
+     * @returns Validation result
+     */
+    validateTool(tool: CanonicalTool, _modelConfig: ModelConfig): {
+        valid: boolean;
+        errors?: string[];
+    };
+    /**
+     * Get maximum tools supported
+     *
+     * @param modelConfig - Model configuration
+     * @returns Max tools
+     */
+    getMaxTools(modelConfig: ModelConfig): number;
+    /**
+     * Check if parallel tool calls are supported
+     *
+     * @param modelConfig - Model configuration
+     * @returns true if parallel tool calls supported
+     */
+    supportsParallelToolCalls(modelConfig: ModelConfig): boolean;
+    /**
+     * Extract additional JSON Schema properties
+     */
+    private extractAdditionalSchemaProperties;
+    /**
+     * Generate unique message UUID
+     */
+    private generateMessageUuid;
+}
+/**
+ * Default singleton instance
+ */
+export declare const responsesAPIAdapter: ResponsesAPIAdapter;
+//# sourceMappingURL=ResponsesAPIAdapter.d.ts.map

package/dist/adapters/ResponsesAPIAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponsesAPIAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/ResponsesAPIAdapter.ts"],"names":[],"mappings":"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"}