@nexus-cortex/core 4.26.0

package/dist/adapters/MessagesAPIAdapter.d.ts

@@ -0,0 +1,280 @@
+/**
+ * MessagesAPIAdapter
+ *
+ * Pattern-based adapter for the /messages API format used by Anthropic Claude and XAI Grok.
+ *
+ * API Pattern: /messages endpoint with input_schema
+ * Naming: snake_case (CRITICAL - NOT PascalCase)
+ * Structure: Flat (no wrapper)
+ *
+ * Phase 1.5: Multi-Provider Architecture
+ * Based on: SDK_FINDINGS.md, ANTHROPIC_TOOL_FORMAT_REFERENCE.md
+ *
+ * NOTE: This adapter handles any provider using the /messages API pattern,
+ * including Anthropic Claude and XAI Grok.
+ */
+import { FormatAdapter, CanonicalTool, CanonicalToolUse, CanonicalToolResult, CanonicalMessage } from './FormatAdapter.interface.js';
+import { ModelConfig } from '../models/ModelConfig.interface.js';
+/**
+ * Messages API Tool Format
+ *
+ * As used by providers implementing the /messages API pattern
+ */
+export interface MessagesAPITool {
+    /** Tool name (snake_case - REQUIRED) */
+    name: string;
+    /** Human-readable description (optional but recommended) */
+    description?: string;
+    /** Input schema - NOTE: property name is "input_schema" */
+    input_schema: {
+        /** Must be 'object' */
+        type: 'object';
+        /** Property definitions */
+        properties?: Record<string, unknown>;
+        /** Required property names */
+        required?: string[];
+        /** Additional JSON Schema properties */
+        [key: string]: unknown;
+    };
+    /** PTC: Defer tool loading — schema sent but not loaded until Tool Search finds it */
+    defer_loading?: boolean;
+    /** PTC: Restrict which callers can invoke this tool */
+    allowed_callers?: string[];
+}
+/**
+ * Union type for Messages API tool entries including PTC system tools.
+ * Used when building tool arrays for PTC-enabled requests.
+ */
+export type MessagesAPIToolEntry = MessagesAPITool | {
+    type: 'code_execution_20260120';
+} | {
+    type: 'tool_search_tool_bm25_20251119';
+};
+/**
+ * Anthropic ToolUse (tool call from model)
+ */
+export interface MessagesAPIToolUse {
+    /** Unique ID for this tool use */
+    id: string;
+    /** Type marker */
+    type: 'tool_use';
+    /** Tool name */
+    name: string;
+    /** Input arguments */
+    input: Record<string, unknown>;
+}
+/**
+ * Anthropic ToolResult (tool execution result)
+ */
+export interface MessagesAPIToolResult {
+    /** Type marker */
+    type: 'tool_result';
+    /** ID of the tool use this is responding to */
+    tool_use_id: string;
+    /** Result content (string or structured data) */
+    content: string | Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    /** Whether this is an error */
+    is_error?: boolean;
+}
+/**
+ * Anthropic Content Block (part of message)
+ */
+export type MessagesAPIContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | object;
+    is_error?: boolean;
+} | {
+    type: 'thinking';
+    thinking: string;
+    signature?: string;
+} | {
+    type: 'redacted_thinking';
+    data: string;
+} | {
+    type: 'server_tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'code_execution_tool_result';
+    tool_use_id: string;
+    content: string;
+    output?: {
+        stdout: string;
+        stderr: string;
+    };
+};
+/**
+ * Anthropic Message
+ *
+ * As defined in @anthropic-ai/sdk Messages API
+ */
+export interface MessagesAPIMessage {
+    /** Message role */
+    role: 'user' | 'assistant';
+    /** Message content blocks */
+    content: string | MessagesAPIContentBlock[];
+}
+/**
+ * Anthropic Messages Tools Adapter
+ *
+ * Converts between canonical format and Anthropic's tool format.
+ * Also compatible with XAI Grok (uses same API).
+ */
+export declare class MessagesAPIAdapter implements FormatAdapter {
+    readonly name = "MessagesAPIAdapter";
+    readonly apiPatterns: string[];
+    /**
+     * Convert canonical messages to Anthropic message format
+     *
+     * @param messages - Canonical messages
+     * @param modelConfig - Model configuration
+     * @returns Anthropic message array
+     */
+    toProviderMessages(messages: CanonicalMessage[], modelConfig: ModelConfig): MessagesAPIMessage[];
+    /**
+     * Convert Anthropic messages to canonical format
+     *
+     * @param providerMessages - Anthropic messages
+     * @param modelConfig - Model configuration
+     * @param sessionContext - Session context for timeline tracking
+     * @returns Canonical messages
+     */
+    fromProviderMessages(providerMessages: unknown[], modelConfig: ModelConfig, sessionContext: {
+        sessionId: string;
+        conversationId: string;
+        turnNumber: number;
+    }): CanonicalMessage[];
+    /**
+     * Convert canonical tools to Anthropic tool format
+     *
+     * @param tools - Canonical tool definitions
+     * @param modelConfig - Model configuration
+     * @returns Anthropic tool array
+     */
+    toProviderTools(tools: CanonicalTool[], modelConfig: ModelConfig): MessagesAPITool[];
+    /**
+     * Convert provider tools to canonical format
+     *
+     * @param providerTools - Anthropic tool array
+     * @param modelConfig - Model configuration
+     * @returns Canonical tool definitions
+     */
+    fromProviderTools(providerTools: unknown[], modelConfig: ModelConfig): CanonicalTool[];
+    /**
+     * Convert canonical tool use to Anthropic ToolUse
+     *
+     * @param toolUse - Canonical tool use
+     * @param _modelConfig - Model configuration
+     * @returns Anthropic ToolUse
+     */
+    toProviderToolUse(toolUse: CanonicalToolUse, _modelConfig: ModelConfig): MessagesAPIToolUse;
+    /**
+     * Convert Anthropic ToolUse to canonical format
+     *
+     * @param providerToolUse - Anthropic ToolUse
+     * @param modelConfig - Model configuration
+     * @returns Canonical tool use
+     */
+    fromProviderToolUse(providerToolUse: unknown, modelConfig: ModelConfig): CanonicalToolUse;
+    /**
+     * Convert canonical tool result to Anthropic ToolResult
+     *
+     * @param toolResult - Canonical tool result
+     * @param _modelConfig - Model configuration
+     * @returns Anthropic ToolResult
+     */
+    toProviderToolResult(toolResult: CanonicalToolResult, _modelConfig: ModelConfig): MessagesAPIToolResult;
+    /**
+     * Convert Anthropic ToolResult to canonical format
+     *
+     * @param providerToolResult - Anthropic ToolResult
+     * @param _modelConfig - Model configuration
+     * @returns Canonical tool result
+     */
+    fromProviderToolResult(providerToolResult: unknown, _modelConfig: ModelConfig): CanonicalToolResult;
+    /**
+     * Validate tool for Anthropic 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 (64 for Claude, same for XAI)
+     */
+    getMaxTools(modelConfig: ModelConfig): number;
+    /**
+     * Check if parallel tool calls are supported
+     *
+     * @param modelConfig - Model configuration
+     * @returns true (Anthropic supports parallel tool calls)
+     */
+    supportsParallelToolCalls(modelConfig: ModelConfig): boolean;
+    /**
+     * Convert canonical tool to Anthropic tool
+     */
+    private convertToMessagesAPITool;
+    /**
+     * Convert Anthropic tool to canonical tool
+     */
+    private convertFromMessagesAPITool;
+    /**
+     * Extract additional JSON Schema properties
+     *
+     * @param schema - Schema object
+     * @returns Additional properties (excluding type, properties, required)
+     */
+    private extractAdditionalSchemaProperties;
+    /**
+     * Convert canonical message to Anthropic message
+     */
+    private convertToMessagesAPIMessage;
+    /**
+     * Convert Anthropic message to canonical message
+     */
+    private convertFromMessagesAPIMessage;
+    /**
+     * Generate unique message UUID
+     */
+    private generateMessageUuid;
+    /**
+     * Validate and enhance tools for XAI compatibility
+     * XAI has stricter requirements than standard Anthropic API:
+     * - description is REQUIRED (not optional)
+     * - input_schema.properties is REQUIRED
+     * - input_schema.required is REQUIRED (can be empty array)
+     * - All properties should have descriptions
+     *
+     * Based on XAI API documentation and working implementation in Cortex V3
+     *
+     * @param tools - Canonical tool definitions
+     * @returns Enhanced tools with XAI-compliant schemas
+     */
+    private validateAndEnhanceToolsForXAI;
+}
+/**
+ * Default singleton instance
+ */
+export declare const messagesAPIAdapter: MessagesAPIAdapter;
+//# sourceMappingURL=MessagesAPIAdapter.d.ts.map

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

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