@nexus-cortex/core 4.26.0

package/dist/adapters/ServerSideToolDetection.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Server-Side Tool Detection and Routing
+ *
+ * Determines whether to use server-side (agentic) tool execution vs client-side.
+ * Handles endpoint switching between Messages API and Responses API for XAI models.
+ *
+ * Architecture:
+ * - Detection is model-level + environment-driven
+ * - XAI: Messages API (/v1/messages) for client-side OR Responses API (/v1/responses) for server-side
+ * - XAI supports mixing client-side and server-side tools (server tools auto-execute, client tools pause)
+ * - Server-side tools require ENABLE_SERVER_SIDE_TOOLS=true
+ *
+ * Based on:
+ * - XAI API documentation (research/api-docs/xai_api_reference/)
+ * - HANDOFF_SESSION_REGISTRY_REFACTORING.md
+ * - ModelConfig.serverSideTools configuration
+ */
+import { ModelConfig } from '../models/ModelConfig.interface.js';
+import { CanonicalTool } from './FormatAdapter.interface.js';
+/**
+ * Detection Result
+ *
+ * Indicates whether to use server-side tools and which endpoint
+ */
+export interface ServerSideToolDetectionResult {
+    /** Whether server-side tools should be used */
+    useServerSideTools: boolean;
+    /** API endpoint to use */
+    endpoint: string;
+    /** API pattern to use */
+    apiPattern: 'messages' | 'responses';
+    /** Tools to send (filtered for client or server) */
+    tools: CanonicalTool[];
+    /** Reason for decision (for debugging) */
+    reason: string;
+}
+/**
+ * Check if server-side tools are enabled via environment variable
+ *
+ * @returns true if ENABLE_SERVER_SIDE_TOOLS is set to 'true' or '1'
+ */
+export declare function isServerSideToolsEnabled(): boolean;
+/**
+ * Detect if model supports server-side tools
+ *
+ * @param modelConfig - Model configuration
+ * @returns true if model has serverSideTools.supported = true
+ */
+export declare function modelSupportsServerSideTools(modelConfig: ModelConfig): boolean;
+/**
+ * Check if tools contain any server-side tools for this provider
+ *
+ * @param provider - Provider name
+ * @param tools - Array of canonical tools
+ * @returns true if any tools are server-side for this provider
+ */
+export declare function containsServerSideTools(provider: string, tools: CanonicalTool[]): boolean;
+/**
+ * Main detection logic: Should we use server-side tools?
+ *
+ * Decision criteria (ALL must be true):
+ * 1. ENABLE_SERVER_SIDE_TOOLS environment variable is set to 'true' or '1'
+ * 2. Model supports server-side tools (ModelConfig.serverSideTools.supported = true)
+ * 3. Tools array contains at least one server-side tool for this provider
+ * 4. Provider supports server-side tools (currently only XAI)
+ *
+ * @param modelConfig - Model configuration
+ * @param tools - Array of canonical tools to use
+ * @returns Detection result with endpoint and tool filtering
+ */
+export declare function shouldUseServerSideTools(modelConfig: ModelConfig, tools: CanonicalTool[]): ServerSideToolDetectionResult;
+/**
+ * Get Responses API endpoint for a model
+ *
+ * Switches from Messages API to Responses API endpoint.
+ *
+ * @param modelConfig - Model configuration
+ * @returns Responses API endpoint URL
+ */
+export declare function getResponsesAPIEndpoint(modelConfig: ModelConfig): string;
+/**
+ * Get Messages API endpoint for a model (reverse of getResponsesAPIEndpoint)
+ *
+ * Useful for switching back from Responses API to Messages API.
+ *
+ * @param modelConfig - Model configuration
+ * @returns Messages API endpoint URL
+ */
+export declare function getMessagesAPIEndpoint(modelConfig: ModelConfig): string;
+/**
+ * Validate that tools are compatible with server-side execution
+ *
+ * XAI Requirements:
+ * - Cannot mix client-side and server-side tools
+ * - Only specific models support server-side tools (grok-4, grok-4-fast, grok-4-fast-non-reasoning)
+ *
+ * @param modelConfig - Model configuration
+ * @param tools - Array of canonical tools
+ * @returns Validation result with errors if invalid
+ */
+export declare function validateServerSideToolRequest(modelConfig: ModelConfig, tools: CanonicalTool[]): {
+    valid: boolean;
+    errors?: string[];
+};
+//# sourceMappingURL=ServerSideToolDetection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ServerSideToolDetection.d.ts","sourceRoot":"","sources":["../../src/adapters/ServerSideToolDetection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,+CAA+C;IAC/C,kBAAkB,EAAE,OAAO,CAAC;IAE5B,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,UAAU,EAAE,UAAU,GAAG,WAAW,CAAC;IAErC,oDAAoD;IACpD,KAAK,EAAE,aAAa,EAAE,CAAC;IAEvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAGlD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAEzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,aAAa,EAAE,GACrB,6BAA6B,CA2F/B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAmCxE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAGvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,aAAa,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAsEvC"}

package/dist/adapters/ServerSideToolDetection.js

@@ -0,0 +1,249 @@
+/**
+ * Server-Side Tool Detection and Routing
+ *
+ * Determines whether to use server-side (agentic) tool execution vs client-side.
+ * Handles endpoint switching between Messages API and Responses API for XAI models.
+ *
+ * Architecture:
+ * - Detection is model-level + environment-driven
+ * - XAI: Messages API (/v1/messages) for client-side OR Responses API (/v1/responses) for server-side
+ * - XAI supports mixing client-side and server-side tools (server tools auto-execute, client tools pause)
+ * - Server-side tools require ENABLE_SERVER_SIDE_TOOLS=true
+ *
+ * Based on:
+ * - XAI API documentation (research/api-docs/xai_api_reference/)
+ * - HANDOFF_SESSION_REGISTRY_REFACTORING.md
+ * - ModelConfig.serverSideTools configuration
+ */
+import { isServerSideTool, separateTools } from '../tools/ServerSideTools.js';
+/**
+ * Check if server-side tools are enabled via environment variable
+ *
+ * @returns true if ENABLE_SERVER_SIDE_TOOLS is set to 'true' or '1'
+ */
+export function isServerSideToolsEnabled() {
+    const envVar = process.env.ENABLE_SERVER_SIDE_TOOLS;
+    return envVar === 'true' || envVar === '1';
+}
+/**
+ * Detect if model supports server-side tools
+ *
+ * @param modelConfig - Model configuration
+ * @returns true if model has serverSideTools.supported = true
+ */
+export function modelSupportsServerSideTools(modelConfig) {
+    return modelConfig.serverSideTools?.supported === true;
+}
+/**
+ * Check if tools contain any server-side tools for this provider
+ *
+ * @param provider - Provider name
+ * @param tools - Array of canonical tools
+ * @returns true if any tools are server-side for this provider
+ */
+export function containsServerSideTools(provider, tools) {
+    return tools.some(tool => isServerSideTool(provider, tool.name));
+}
+/**
+ * Main detection logic: Should we use server-side tools?
+ *
+ * Decision criteria (ALL must be true):
+ * 1. ENABLE_SERVER_SIDE_TOOLS environment variable is set to 'true' or '1'
+ * 2. Model supports server-side tools (ModelConfig.serverSideTools.supported = true)
+ * 3. Tools array contains at least one server-side tool for this provider
+ * 4. Provider supports server-side tools (currently only XAI)
+ *
+ * @param modelConfig - Model configuration
+ * @param tools - Array of canonical tools to use
+ * @returns Detection result with endpoint and tool filtering
+ */
+export function shouldUseServerSideTools(modelConfig, tools) {
+    const provider = modelConfig.provider;
+    // Step 1: Check environment variable
+    if (!isServerSideToolsEnabled()) {
+        // Filter out server-side tools since they can't be used with client-side APIs
+        const clientTools = tools.filter(tool => !isServerSideTool(provider, tool.name));
+        if (clientTools.length < tools.length) {
+            console.warn(`[ServerSideToolDetection] ENABLE_SERVER_SIDE_TOOLS is disabled. Filtered out ${tools.length - clientTools.length} server-side tools.`);
+        }
+        return {
+            useServerSideTools: false,
+            endpoint: modelConfig.api.endpoint,
+            apiPattern: modelConfig.api.pattern,
+            tools: clientTools, // Return only client-side tools
+            reason: 'ENABLE_SERVER_SIDE_TOOLS environment variable not set'
+        };
+    }
+    // Step 2: Check model support
+    if (!modelSupportsServerSideTools(modelConfig)) {
+        return {
+            useServerSideTools: false,
+            endpoint: modelConfig.api.endpoint,
+            apiPattern: modelConfig.api.pattern,
+            tools,
+            reason: 'Model does not support server-side tools'
+        };
+    }
+    // Step 3: Check if tools contain server-side tools
+    if (!containsServerSideTools(provider, tools)) {
+        return {
+            useServerSideTools: false,
+            endpoint: modelConfig.api.endpoint,
+            apiPattern: modelConfig.api.pattern,
+            tools,
+            reason: 'No server-side tools in request'
+        };
+    }
+    // Step 4: Separate tools and validate (cannot mix client and server)
+    const { clientTools, serverTools } = separateTools(provider, tools);
+    if (clientTools.length > 0 && serverTools.length > 0) {
+        // XAI supports hybrid mode: server-side tools auto-execute, client-side tools pause and return
+        // Per xAI advanced usage docs: "You can combine server-side agentic tools with custom client-side tools"
+        if (process.env.DEBUG === 'true') {
+            console.log(`[ServerSideToolDetection] Hybrid mode: ${serverTools.length} server-side + ${clientTools.length} client-side tools for ${provider}. ` +
+                `Server tools: ${serverTools.map(t => t.name).join(', ')}. ` +
+                `Client tools: ${clientTools.map(t => t.name).slice(0, 5).join(', ')}${clientTools.length > 5 ? ` (+${clientTools.length - 5} more)` : ''}`);
+        }
+        // Use ALL tools (both server-side and client-side) via Responses API
+        const responsesEndpoint = getResponsesAPIEndpoint(modelConfig);
+        return {
+            useServerSideTools: true,
+            endpoint: responsesEndpoint,
+            apiPattern: 'responses',
+            tools: [...serverTools, ...clientTools], // ALL tools — hybrid mode
+            reason: 'Hybrid mode: server-side + client-side tools via Responses API'
+        };
+    }
+    if (serverTools.length === 0) {
+        // No server-side tools present
+        return {
+            useServerSideTools: false,
+            endpoint: modelConfig.api.endpoint,
+            apiPattern: modelConfig.api.pattern,
+            tools,
+            reason: 'No server-side tools in request'
+        };
+    }
+    // All criteria met - use server-side tools
+    // Switch to Responses API endpoint
+    const responsesEndpoint = getResponsesAPIEndpoint(modelConfig);
+    return {
+        useServerSideTools: true,
+        endpoint: responsesEndpoint,
+        apiPattern: 'responses',
+        tools: serverTools,
+        reason: 'All criteria met - using server-side agentic tools via Responses API'
+    };
+}
+/**
+ * Get Responses API endpoint for a model
+ *
+ * Switches from Messages API to Responses API endpoint.
+ *
+ * @param modelConfig - Model configuration
+ * @returns Responses API endpoint URL
+ */
+export function getResponsesAPIEndpoint(modelConfig) {
+    // For XAI: derive the responses endpoint idempotently. The configured
+    // endpoint may be /v1/messages (XAI_API_MODE=messages) OR already
+    // /v1/responses (XAI_API_MODE=responses) — strip both so we never produce
+    // a doubled .../v1/responses/v1/responses path (R27: 404 "No handler found
+    // on route"). Mirrors the openai branch below.
+    if (modelConfig.provider === 'xai') {
+        const baseUrl = modelConfig.api.endpoint
+            .replace('/v1/messages', '')
+            .replace('/v1/responses', '');
+        return `${baseUrl}/v1/responses`;
+    }
+    // R20: OpenAI dynamic switch — /v1/chat/completions → /v1/responses
+    if (modelConfig.provider === 'openai') {
+        const baseUrl = modelConfig.api.endpoint
+            .replace('/v1/chat/completions', '')
+            .replace('/v1/responses', '');
+        return `${baseUrl}/v1/responses`;
+    }
+    // For other providers (future): use supportedEndpoints config
+    const responsesSupported = modelConfig.serverSideTools?.supportedEndpoints?.includes('responses');
+    if (responsesSupported) {
+        // Generic endpoint switching logic
+        const baseUrl = modelConfig.api.endpoint.replace(/\/(v1\/)?[^/]+$/, '');
+        return `${baseUrl}/v1/responses`;
+    }
+    // Fallback: use original endpoint (shouldn't reach here if detection is correct)
+    console.warn(`[ServerSideToolDetection] WARNING: No Responses API endpoint configured for ${modelConfig.provider}. ` +
+        `Using original endpoint: ${modelConfig.api.endpoint}`);
+    return modelConfig.api.endpoint;
+}
+/**
+ * Get Messages API endpoint for a model (reverse of getResponsesAPIEndpoint)
+ *
+ * Useful for switching back from Responses API to Messages API.
+ *
+ * @param modelConfig - Model configuration
+ * @returns Messages API endpoint URL
+ */
+export function getMessagesAPIEndpoint(modelConfig) {
+    // This is typically the default endpoint in ModelConfig
+    return modelConfig.api.endpoint;
+}
+/**
+ * Validate that tools are compatible with server-side execution
+ *
+ * XAI Requirements:
+ * - Cannot mix client-side and server-side tools
+ * - Only specific models support server-side tools (grok-4, grok-4-fast, grok-4-fast-non-reasoning)
+ *
+ * @param modelConfig - Model configuration
+ * @param tools - Array of canonical tools
+ * @returns Validation result with errors if invalid
+ */
+export function validateServerSideToolRequest(modelConfig, tools) {
+    const errors = [];
+    const provider = modelConfig.provider;
+    // Check model support
+    if (!modelSupportsServerSideTools(modelConfig)) {
+        errors.push(`Model ${modelConfig.id} does not support server-side tools`);
+    }
+    // Check tools composition (hybrid mode supported for XAI and OpenAI Responses API)
+    const { clientTools, serverTools } = separateTools(provider, tools);
+    // R20: OpenAI Responses API supports hybrid mode just like XAI — hosted tools
+    // (web_search, code_interpreter, etc.) execute server-side while function
+    // tools pause and return for client execution.
+    if (clientTools.length > 0 && serverTools.length > 0 && provider !== 'xai' && provider !== 'openai') {
+        errors.push(`Cannot mix client-side and server-side tools for provider ${provider}. ` +
+            `Client tools: ${clientTools.map(t => t.name).join(', ')}. ` +
+            `Server tools: ${serverTools.map(t => t.name).join(', ')}`);
+    }
+    // R20: OpenAI server-side tool availability check (mirrors the XAI branch
+    // below). Tools must be in the model's `serverSideTools.availableTools` list.
+    if (provider === 'openai' && serverTools.length > 0) {
+        const availableTools = modelConfig.serverSideTools?.availableTools || [];
+        const unavailableTools = serverTools.filter(tool => !availableTools.includes(tool.name));
+        if (unavailableTools.length > 0) {
+            errors.push(`Tools not available for ${modelConfig.id}: ${unavailableTools.map(t => t.name).join(', ')}. ` +
+                `Available tools: ${availableTools.join(', ')}`);
+        }
+    }
+    // XAI-specific validations
+    if (provider === 'xai') {
+        // Check model compatibility
+        const compatibleModels = ['grok-4', 'grok-4-fast', 'grok-4-fast-non-reasoning', 'grok-4-0709', 'grok-code-fast-1'];
+        const isCompatible = compatibleModels.some(model => modelConfig.id.includes(model));
+        if (!isCompatible) {
+            errors.push(`Model ${modelConfig.id} may not support server-side tools. ` +
+                `Recommended models: grok-4, grok-4-fast, grok-4-fast-non-reasoning`);
+        }
+        // Validate available tools
+        const availableTools = modelConfig.serverSideTools?.availableTools || [];
+        const unavailableTools = serverTools.filter(tool => !availableTools.includes(tool.name));
+        if (unavailableTools.length > 0) {
+            errors.push(`Tools not available for ${modelConfig.id}: ${unavailableTools.map(t => t.name).join(', ')}. ` +
+                `Available tools: ${availableTools.join(', ')}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined
+    };
+}
+//# sourceMappingURL=ServerSideToolDetection.js.map

package/dist/adapters/ServerSideToolDetection.js.map

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

package/dist/adapters/ToolNamingHandler.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Tool Naming Handler
+ *
+ * Handles naming convention conversion for tools at the gateway layer.
+ * This separates naming concerns from API format conversion, allowing
+ * adapters to focus solely on API-specific formats.
+ *
+ * Phase 1.5: Multi-Provider Architecture
+ * Week 3: Tool Naming Handler Implementation
+ *
+ * Architecture Principle:
+ * - Gateway handles naming conversion
+ * - Adapters handle API format conversion
+ * - Separation of concerns for maintainability
+ */
+import { CanonicalTool, CanonicalToolUse, CanonicalToolResult } from './FormatAdapter.interface.js';
+/**
+ * Tool Naming Handler
+ *
+ * Applies naming conventions to tools before they are passed to adapters.
+ * This ensures adapters receive tools with the correct naming for their API pattern.
+ */
+export declare class ToolNamingHandler {
+    static convertNameCache: Map<string, string>;
+    /**
+     * Apply naming convention to tools
+     *
+     * Converts tool names from canonical format to the specified convention.
+     * This should be called by the gateway BEFORE passing tools to adapters.
+     *
+     * @param tools - Canonical tools with any naming
+     * @param convention - Target naming convention
+     * @returns Tools with converted names
+     */
+    applyNamingConvention(tools: CanonicalTool[], convention: 'snake_case' | 'PascalCase'): CanonicalTool[];
+    /**
+     * Apply naming convention to tool use
+     *
+     * Converts tool use names to match the specified convention.
+     *
+     * @param toolUse - Tool use with any naming
+     * @param convention - Target naming convention
+     * @returns Tool use with converted name
+     */
+    applyNamingToToolUse(toolUse: CanonicalToolUse, convention: 'snake_case' | 'PascalCase'): CanonicalToolUse;
+    /**
+     * Apply naming convention to tool result
+     *
+     * Note: Tool results reference tools by ID, not name, so no conversion needed.
+     * This method is provided for API consistency but returns the result unchanged.
+     *
+     * @param toolResult - Tool result
+     * @param convention - Target naming convention (unused)
+     * @returns Tool result unchanged
+     */
+    applyNamingToToolResult(toolResult: CanonicalToolResult, _convention: 'snake_case' | 'PascalCase'): CanonicalToolResult;
+    /**
+     * Convert a single name to the specified convention
+     *
+     * @param name - Name to convert
+     * @param convention - Target convention
+     * @returns Converted name
+     */
+    convertName(name: string, convention: 'snake_case' | 'PascalCase'): string;
+    /**
+     * Detect names of the form `<server>__<tool>` where both halves are
+     * non-empty and the server-name half doesn't itself look like a
+     * doubly-underscored native identifier (which would be `read__file` and
+     * is handled by the regular conversion path).
+     */
+    private isMcpNamespacedName;
+    /**
+     * Convert string to snake_case
+     *
+     * @param str - Input string
+     * @returns snake_case version
+     *
+     * @example
+     * toSnakeCase('ReadFile') → 'read_file'
+     * toSnakeCase('readFile') → 'read_file'
+     * toSnakeCase('read_file') → 'read_file'
+     */
+    private toSnakeCase;
+    /**
+     * Convert string to PascalCase
+     *
+     * @param str - Input string
+     * @returns PascalCase version
+     *
+     * @example
+     * toPascalCase('read_file') → 'ReadFile'
+     * toPascalCase('ReadFile') → 'ReadFile'
+     * toPascalCase('readFile') → 'ReadFile'
+     */
+    private toPascalCase;
+    /**
+     * Check if string is in snake_case format
+     *
+     * @param str - String to check
+     * @returns true if snake_case
+     */
+    private isSnakeCase;
+    /**
+     * Check if string is in PascalCase format
+     *
+     * @param str - String to check
+     * @returns true if PascalCase
+     */
+    private isPascalCase;
+    /**
+     * Detect the current naming convention of a string
+     *
+     * @param str - String to analyze
+     * @returns Detected convention or 'unknown'
+     */
+    detectConvention(str: string): 'snake_case' | 'PascalCase' | 'camelCase' | 'unknown';
+    /**
+     * Validate that tools have the correct naming convention
+     *
+     * @param tools - Tools to validate
+     * @param expectedConvention - Expected naming convention
+     * @returns Validation result with any errors
+     */
+    validateNaming(tools: CanonicalTool[], expectedConvention: 'snake_case' | 'PascalCase'): {
+        valid: boolean;
+        errors?: string[];
+    };
+}
+//# sourceMappingURL=ToolNamingHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolNamingHandler.d.ts","sourceRoot":"","sources":["../../src/adapters/ToolNamingHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEpG;;;;;GAKG;AACH,qBAAa,iBAAiB;IAG5B,MAAM,CAAC,gBAAgB,sBAA6B;IAEpD;;;;;;;;;OASG;IACH,qBAAqB,CACnB,KAAK,EAAE,aAAa,EAAE,EACtB,UAAU,EAAE,YAAY,GAAG,YAAY,GACtC,aAAa,EAAE;IAOlB;;;;;;;;OAQG;IACH,oBAAoB,CAClB,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,YAAY,GAAG,YAAY,GACtC,gBAAgB;IAOnB;;;;;;;;;OASG;IACH,uBAAuB,CACrB,UAAU,EAAE,mBAAmB,EAC/B,WAAW,EAAE,YAAY,GAAG,YAAY,GACvC,mBAAmB;IAMtB;;;;;;OAMG;IACH,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,YAAY,GAAG,YAAY,GACtC,MAAM;IAmBT;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS;IAapF;;;;;;OAMG;IACH,cAAc,CACZ,KAAK,EAAE,aAAa,EAAE,EACtB,kBAAkB,EAAE,YAAY,GAAG,YAAY,GAC9C;QACD,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB;CAsBF"}