@kya-os/mcp-i-cloudflare 1.6.16 → 1.6.17-canary.clientinfo.20251126055019

package/dist/utils/client-info.js

@@ -0,0 +1,178 @@
+/**
+ * Client Info Utilities
+ *
+ * Handles MCP client information extraction, normalization, and handshake payload preparation.
+ * This consolidates logic for working with client metadata across initialize and handshake.
+ */
+/**
+ * Normalize client info from various formats
+ *
+ * @param value Client info from request (could be from initialize or handshake)
+ * @returns Normalized client info or undefined if invalid
+ */
+export function normalizeClientInfo(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const normalized = {};
+    const record = value;
+    const name = record.name;
+    if (typeof name === "string" && name.trim().length > 0) {
+        normalized.name = name.trim();
+    }
+    const title = record.title;
+    if (typeof title === "string" && title.trim().length > 0) {
+        normalized.title = title.trim();
+    }
+    const version = record.version;
+    if (typeof version === "string" && version.trim().length > 0) {
+        normalized.version = version.trim();
+    }
+    const platform = record.platform;
+    if (typeof platform === "string" && platform.trim().length > 0) {
+        normalized.platform = platform.trim();
+    }
+    const vendor = record.vendor;
+    if (typeof vendor === "string" && vendor.trim().length > 0) {
+        normalized.vendor = vendor.trim();
+    }
+    const persistentId = record.persistentId;
+    if (typeof persistentId === "string" && persistentId.trim().length > 0) {
+        normalized.persistentId = persistentId.trim();
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+/**
+ * Extract MCP client information from handshake request and initialize context
+ *
+ * @param request Handshake request
+ * @param initializeContext Optional context from previous initialize call
+ * @returns Extracted and normalized client info or undefined
+ */
+export function extractMCPClient(request, initializeContext) {
+    const fromHandshake = normalizeClientInfo(request.clientInfo);
+    const merged = {
+        ...(initializeContext?.clientInfo ?? {}),
+        ...(fromHandshake ?? {}),
+    };
+    const handshakeClientId = isRecord(request.clientInfo) &&
+        typeof request.clientInfo.clientId === "string" &&
+        request.clientInfo.clientId.trim().length > 0
+        ? request.clientInfo.clientId.trim()
+        : undefined;
+    const hasClientMetadata = Object.keys(merged).length > 0 ||
+        handshakeClientId ||
+        typeof request.clientProtocolVersion === "string" ||
+        isRecord(request.clientCapabilities);
+    if (!hasClientMetadata) {
+        return undefined;
+    }
+    const nameValue = merged.name;
+    const name = typeof nameValue === "string" && nameValue.trim().length > 0
+        ? nameValue.trim()
+        : "unknown";
+    const clientId = handshakeClientId || crypto.randomUUID();
+    const capabilities = isRecord(request.clientCapabilities)
+        ? request.clientCapabilities
+        : initializeContext?.capabilities;
+    return {
+        name,
+        title: merged.title,
+        version: merged.version,
+        platform: merged.platform,
+        vendor: merged.vendor,
+        persistentId: merged.persistentId,
+        protocolVersion: request.clientProtocolVersion ??
+            initializeContext?.protocolVersion ??
+            merged.protocolVersion,
+        capabilities,
+        clientId,
+    };
+}
+/**
+ * Prepare handshake payload with client information from initialize context
+ *
+ * @param params Original handshake request parameters
+ * @param initializeContext Optional context from previous initialize call
+ * @returns Enhanced handshake request with client info
+ */
+export function prepareHandshakePayload(params, initializeContext) {
+    const payload = {
+        ...params,
+    };
+    if (!payload.clientProtocolVersion && initializeContext?.protocolVersion) {
+        payload.clientProtocolVersion = initializeContext.protocolVersion;
+    }
+    if (!payload.clientCapabilities && initializeContext?.capabilities) {
+        payload.clientCapabilities = initializeContext.capabilities;
+    }
+    if (!payload.clientInfo && initializeContext?.clientInfo?.name) {
+        const source = initializeContext.clientInfo;
+        const name = source.name;
+        if (!name) {
+            return payload;
+        }
+        payload.clientInfo = {
+            name,
+            ...(source.title ? { title: source.title } : {}),
+            ...(source.version ? { version: source.version } : {}),
+            ...(source.platform ? { platform: source.platform } : {}),
+            ...(source.vendor ? { vendor: source.vendor } : {}),
+            ...(source.persistentId ? { persistentId: source.persistentId } : {}),
+        };
+    }
+    return payload;
+}
+/**
+ * Clone capabilities object (deep copy)
+ *
+ * @param capabilities Capabilities to clone
+ * @returns Cloned capabilities or undefined
+ */
+export function cloneCapabilities(capabilities) {
+    if (!isRecord(capabilities)) {
+        return undefined;
+    }
+    return JSON.parse(JSON.stringify(capabilities));
+}
+/**
+ * Type guard for record objects
+ *
+ * @param value Value to check
+ * @returns true if value is a record object
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Extract client ID from client info if available
+ *
+ * @param clientInfo Client info object
+ * @returns Client ID or undefined
+ */
+export function extractClientId(clientInfo) {
+    if (!isRecord(clientInfo)) {
+        return undefined;
+    }
+    const clientId = clientInfo.clientId;
+    if (typeof clientId === "string" && clientId.trim().length > 0) {
+        return clientId.trim();
+    }
+    return undefined;
+}
+/**
+ * Merge client info from multiple sources
+ *
+ * @param sources Array of potential client info sources (later sources override earlier)
+ * @returns Merged client info
+ */
+export function mergeClientInfo(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (source) {
+            Object.assign(merged, source);
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=client-info.js.map

package/dist/utils/client-info.js.map

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

package/dist/utils/error-formatter.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Error Formatter Utility
+ *
+ * Provides consistent JSON-RPC error response formatting for all error types.
+ * Handles special cases like DelegationRequiredError and OAuthRequiredError.
+ */
+/**
+ * JSON-RPC error response structure
+ */
+export interface JsonRpcErrorResponse {
+    jsonrpc: string;
+    id: unknown;
+    error: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+}
+/**
+ * Error codes for different error types
+ */
+export declare const ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly DELEGATION_REQUIRED: -32001;
+    readonly OAUTH_REQUIRED: -32002;
+    readonly AUTHORIZATION_REQUIRED: -32003;
+    readonly SESSION_EXPIRED: -32004;
+};
+/**
+ * Format a generic error into JSON-RPC response
+ *
+ * @param error The error to format
+ * @param id Request ID from JSON-RPC request
+ * @returns Formatted JSON-RPC error response
+ */
+export declare function formatJsonRpcError(error: unknown, id: unknown): JsonRpcErrorResponse;
+/**
+ * Format DelegationRequiredError into JSON-RPC response
+ *
+ * @param error Delegation required error
+ * @param id Request ID
+ * @returns Formatted error response with consent URL
+ */
+export declare function formatDelegationError(error: any, id: unknown): JsonRpcErrorResponse;
+/**
+ * Format OAuthRequiredError into JSON-RPC response
+ *
+ * @param error OAuth required error
+ * @param id Request ID
+ * @returns Formatted error response with OAuth URL
+ */
+export declare function formatOAuthError(error: any, id: unknown): JsonRpcErrorResponse;
+/**
+ * Check if error is a DelegationRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's a delegation required error
+ */
+export declare function isDelegationRequiredError(error: unknown): boolean;
+/**
+ * Check if error is an OAuthRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's an OAuth required error
+ */
+export declare function isOAuthRequiredError(error: unknown): boolean;
+/**
+ * Format method not found error
+ *
+ * @param method The method that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export declare function formatMethodNotFoundError(method: string, id: unknown): JsonRpcErrorResponse;
+/**
+ * Format tool not found error
+ *
+ * @param toolName The tool that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export declare function formatToolNotFoundError(toolName: string, id: unknown): JsonRpcErrorResponse;
+/**
+ * Format session expired error
+ *
+ * @param sessionId The expired session ID
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export declare function formatSessionExpiredError(sessionId: string, id: unknown): JsonRpcErrorResponse;
+/**
+ * Create a success response wrapper
+ *
+ * @param result The result to wrap
+ * @param id Request ID
+ * @returns JSON-RPC success response
+ */
+export declare function formatSuccessResponse(result: any, id: unknown): any;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/utils/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/error-formatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,GAAG,CAAC;KACZ,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;CAad,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CAoDpF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CA4BnF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CA8B9E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW5D;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CAS3F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CAS3F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,oBAAoB,CAY9F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,GAAG,GAAG,CAMnE"}

package/dist/utils/error-formatter.js

@@ -0,0 +1,245 @@
+/**
+ * Error Formatter Utility
+ *
+ * Provides consistent JSON-RPC error response formatting for all error types.
+ * Handles special cases like DelegationRequiredError and OAuthRequiredError.
+ */
+/**
+ * Error codes for different error types
+ */
+export const ERROR_CODES = {
+    // Standard JSON-RPC error codes
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    // Custom error codes for MCP-I
+    DELEGATION_REQUIRED: -32001,
+    OAUTH_REQUIRED: -32002,
+    AUTHORIZATION_REQUIRED: -32003,
+    SESSION_EXPIRED: -32004,
+};
+/**
+ * Format a generic error into JSON-RPC response
+ *
+ * @param error The error to format
+ * @param id Request ID from JSON-RPC request
+ * @returns Formatted JSON-RPC error response
+ */
+export function formatJsonRpcError(error, id) {
+    // Check if this is a special error type
+    if (isDelegationRequiredError(error)) {
+        return formatDelegationError(error, id);
+    }
+    if (isOAuthRequiredError(error)) {
+        return formatOAuthError(error, id);
+    }
+    // Generic error handling
+    let errorMessage = "Internal error";
+    let errorCode = ERROR_CODES.INTERNAL_ERROR;
+    let errorData = undefined;
+    if (error) {
+        // Check if it's an Error object with a message
+        if (typeof error === "object" && error instanceof Error && error.message) {
+            errorMessage = error.message;
+        }
+        // Check for custom error properties
+        else if (typeof error === "object" && "message" in error) {
+            errorMessage = String(error.message);
+        }
+        // For non-Error objects (strings, etc.), try to convert to string
+        else if (typeof error === "string") {
+            errorMessage = error;
+        }
+        // Extract additional error data if available
+        if (typeof error === "object" && "data" in error) {
+            errorData = error.data;
+        }
+        // Check for custom error code
+        if (typeof error === "object" && "code" in error) {
+            const customCode = error.code;
+            if (typeof customCode === "number") {
+                errorCode = customCode;
+            }
+        }
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: errorCode,
+            message: errorMessage,
+            ...(errorData !== undefined && { data: errorData }),
+        },
+    };
+}
+/**
+ * Format DelegationRequiredError into JSON-RPC response
+ *
+ * @param error Delegation required error
+ * @param id Request ID
+ * @returns Formatted error response with consent URL
+ */
+export function formatDelegationError(error, id) {
+    const toolName = error.toolName || "unknown";
+    const requiredScopes = error.requiredScopes || [];
+    const consentUrl = error.consentUrl;
+    const resumeToken = error.resumeToken;
+    // Format message with consent URL in MCP format
+    let message = error.message || `Delegation required for tool "${toolName}"`;
+    if (consentUrl) {
+        message = `${message}. <authorization_url>${consentUrl}</authorization_url>`;
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.DELEGATION_REQUIRED,
+            message,
+            data: {
+                toolName,
+                requiredScopes,
+                consentUrl,
+                resumeToken,
+                // MCP-I specific: provide authorization URL for client to display
+                authorizationUrl: consentUrl,
+            },
+        },
+    };
+}
+/**
+ * Format OAuthRequiredError into JSON-RPC response
+ *
+ * @param error OAuth required error
+ * @param id Request ID
+ * @returns Formatted error response with OAuth URL
+ */
+export function formatOAuthError(error, id) {
+    const toolName = error.toolName || "unknown";
+    const requiredScopes = error.requiredScopes || [];
+    const provider = error.provider;
+    const oauthUrl = error.oauthUrl;
+    const resumeToken = error.resumeToken;
+    // Format message with OAuth URL in MCP format
+    let message = error.message || `OAuth required for tool "${toolName}"`;
+    if (oauthUrl) {
+        message = `${message}. <authorization_url>${oauthUrl}</authorization_url>`;
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.OAUTH_REQUIRED,
+            message,
+            data: {
+                toolName,
+                requiredScopes,
+                provider,
+                oauthUrl,
+                resumeToken,
+                // MCP-I specific: provide authorization URL for client to display
+                authorizationUrl: oauthUrl,
+            },
+        },
+    };
+}
+/**
+ * Check if error is a DelegationRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's a delegation required error
+ */
+export function isDelegationRequiredError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const err = error;
+    return (err.name === "DelegationRequiredError" ||
+        err.constructor?.name === "DelegationRequiredError" ||
+        (err.code === ERROR_CODES.DELEGATION_REQUIRED && err.consentUrl));
+}
+/**
+ * Check if error is an OAuthRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's an OAuth required error
+ */
+export function isOAuthRequiredError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const err = error;
+    return (err.name === "OAuthRequiredError" ||
+        err.constructor?.name === "OAuthRequiredError" ||
+        (err.code === ERROR_CODES.OAUTH_REQUIRED && err.oauthUrl));
+}
+/**
+ * Format method not found error
+ *
+ * @param method The method that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatMethodNotFoundError(method, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.METHOD_NOT_FOUND,
+            message: `Unknown method: ${method}`,
+        },
+    };
+}
+/**
+ * Format tool not found error
+ *
+ * @param toolName The tool that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatToolNotFoundError(toolName, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.INVALID_PARAMS,
+            message: `Tool not found: ${toolName}`,
+        },
+    };
+}
+/**
+ * Format session expired error
+ *
+ * @param sessionId The expired session ID
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatSessionExpiredError(sessionId, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.SESSION_EXPIRED,
+            message: "Session has expired",
+            data: {
+                sessionId,
+            },
+        },
+    };
+}
+/**
+ * Create a success response wrapper
+ *
+ * @param result The result to wrap
+ * @param id Request ID
+ * @returns JSON-RPC success response
+ */
+export function formatSuccessResponse(result, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/utils/error-formatter.js.map

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

package/dist/utils/initialize-context.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Initialize Context Manager
+ *
+ * Manages MCP initialize context storage and retrieval for cross-request state.
+ * This allows us to preserve client info between initialize and handshake calls.
+ */
+import type { MCPClientCapabilities } from "@kya-os/contracts/handshake";
+import type { MCPClientInfo as SessionClientInfo } from "../types/client";
+/**
+ * Context stored from initialize request
+ */
+export interface InitializeContext {
+    timestamp: number;
+    protocolVersion?: string;
+    capabilities?: MCPClientCapabilities;
+    clientInfo?: Partial<SessionClientInfo>;
+}
+/**
+ * Request metadata for fingerprinting
+ */
+export interface RequestMeta {
+    fingerprint?: string;
+    userAgent?: string;
+    ip?: string;
+    cfRay?: string;
+    request?: Request;
+}
+/**
+ * Manages initialize contexts for session continuity
+ */
+export declare class InitializeContextManager {
+    private contexts;
+    constructor();
+    /**
+     * Store initialize context for later use in handshake
+     *
+     * @param meta Request metadata for fingerprinting
+     * @param params Initialize request parameters
+     */
+    store(meta: RequestMeta | undefined, params: unknown): void;
+    /**
+     * Consume initialize context (removes it after retrieval)
+     *
+     * @param meta Request metadata for fingerprinting
+     * @returns Initialize context if found and valid, undefined otherwise
+     */
+    consume(meta: RequestMeta | undefined): InitializeContext | undefined;
+    /**
+     * Prune expired contexts
+     */
+    private prune;
+    /**
+     * Normalize client info from various formats
+     *
+     * @param value Client info from request
+     * @returns Normalized client info or undefined
+     */
+    private normalizeClientInfo;
+    /**
+     * Clone capabilities object (deep copy)
+     *
+     * @param capabilities Capabilities to clone
+     * @returns Cloned capabilities or undefined
+     */
+    private cloneCapabilities;
+    /**
+     * Type guard for record objects
+     *
+     * @param value Value to check
+     * @returns true if value is a record object
+     */
+    private isRecord;
+    /**
+     * Get current size of context cache (for monitoring)
+     *
+     * @returns Number of stored contexts
+     */
+    size(): number;
+    /**
+     * Clear all contexts (for testing)
+     */
+    clear(): void;
+}
+/**
+ * Build request metadata from HTTP request
+ *
+ * @param request HTTP request
+ * @returns Request metadata with fingerprint
+ */
+export declare function buildRequestMeta(request: Request): RequestMeta;
+//# sourceMappingURL=initialize-context.d.ts.map

package/dist/utils/initialize-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize-context.d.ts","sourceRoot":"","sources":["../../src/utils/initialize-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;GAEG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAiC;;IAMjD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAqB3D;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS;IAoBrE;;OAEG;IACH,OAAO,CAAC,KAAK;IASb;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA2C3B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAsB9D"}